Agentes de IA para vibe coding: gerenciamento do ciclo de vida do agente com a Agents CLI e o ADK 2.0

1. Visão geral

Este laboratório faz parte do curso intensivo de programação com vibe de 5 dias sobre agentes de IA com o Google do Kaggle. Encontre outros codelabs e recursos disponíveis no site do evento.

Neste codelab, você vai aprender a usar a CLI do Agents para controlar todo o ciclo de vida de desenvolvimento local de um agente de IA. Seja para encapsular modelos do Gemini ou criar agentes personalizados do zero com o Kit de Desenvolvimento de Agente (ADK 2.0), a CLI Agents oferece as ferramentas para criar estruturas, criar, verificar e testar seus agentes localmente.

O que você vai aprender

• Como instalar e configurar o agents-cli e as skills associadas.
• Como criar um novo projeto de agente.
• A estrutura e os arquivos principais de um projeto de agente de fluxo de trabalho de gráfico do ADK 2.0.
• Como executar a lintagem e a limpeza de código automatizadas.
• Como iniciar e usar o playground da Web local para testes interativos com recarregamento automático.

O que é necessário

• Python 3.11 ou mais recente
• Gerenciador de pacotes uv
• Node.js 18 ou mais recente (se você estiver usando habilidades de agente de programação)
• IDE do Antigravity (instale e configure no Google Antigravity)

Pré-requisitos

Este codelab pressupõe que você tem familiaridade com:

• Usando um terminal e uma linha de comando.

Não é necessário ter experiência com agentes de IA ou ADK 2.0.

2. Configurar a autenticação e o ambiente

Forneça suas credenciais de autenticação para que o agente possa chamar os modelos do Gemini.

Opção 1: chave da API Gemini (Google AI Studio)

Se você estiver usando uma chave de API Gemini padrão (que pode ser obtida no Google AI Studio), exporte-a na sessão do terminal do IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Opção 2: Application Default Credentials do Google Cloud

Se você estiver usando a Vertex AI no Google Cloud, faça a autenticação com as credenciais padrão do aplicativo (ADC) do Google Cloud e defina seu projeto ativo do Google Cloud:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Configurar a Agents CLI e as habilidades

A primeira etapa é instalar a ferramenta agents-cli. Essa ferramenta faz o trabalho pesado do gerenciamento de projetos de agentes.

Observação para usuários do Antigravity:durante este codelab, o Antigravity pode gerar planos de implementação ou mostrar pop-ups antes de executar comandos ou escrever código. Revise e aprove esses planos ou pop-ups para permitir que o Antigravity continue com as tarefas.

Dica de cota:se você ficar sem cota durante o teste ou desenvolvimento, mude o modelo no Antigravity para outro disponível.

Com o Antigravity instalado, execute o comando de configuração diretamente no terminal.

👉 Abra um terminal e execute:

uvx google-agents-cli setup

Esse comando instala automaticamente:

1. A ferramenta Agents CLI globalmente no seu sistema.
2. Sete habilidades de assistente de programação específicas do domínio que o Antigravity pode usar para ajudar você a criar, estruturar, avaliar e implantar agentes. Essas habilidades são instaladas uma vez globalmente no ~/.agents/skills/ e descobertas automaticamente pelo Antigravity.

Observação: as habilidades são instaladas em ~/.agents/skills/ e coletadas automaticamente pelo Antigravity. É possível verificar isso usando o comando /skills ou as configurações do Antigravity.

Resposta esperada (cortada):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Criar o projeto do agente

Nesta seção, você vai criar um diretório de projeto totalmente estruturado usando o modelo de protótipo.

👉 Comando do Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

O Antigravity executa automaticamente o comando de scaffolding (agents-cli scaffold create customer-support-agent --prototype --yes) e configura os arquivos do projeto para você.

Dica do Antigravity:inicialmente, o Antigravity pode fornecer apenas um plano de implementação. Se for o caso, clique ou digite Continuar para executar. Leia a saída com atenção e decida se é necessário pedir mais informações ao Antigravity caso ele não tenha chegado ao resultado esperado abaixo.

5. Conheça o código do agente

👉 Peça para o Antigravity explicar o código gerado:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

No IDE do Antigravity, os arquivos e artefatos de projetos recém-criados são mostrados diretamente no painel auxiliar (lado esquerdo). Você pode ver app/agent.py lá ou abrir no explorador de arquivos do IDE para analisar o código gerado.

Observação:agora você está analisando o código do agente que o Antigravity acabou de criar. Como o Antigravity gera implementações de forma dinâmica, o código no seu arquivo app/agent.py pode ter uma estrutura ou formatação diferente do snippet de exemplo abaixo. O agente de cada usuário será um pouco diferente, mas eles vão compartilhar os mesmos conceitos principais. Se você achar que o script gerado não é adequado ou está faltando alguma funcionalidade, lembre-se de que é possível continuar pedindo para o Antigravity iterar e refinar o código.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Principais conceitos

• Fluxo de trabalho e arestas: no ADK 2.0, os aplicativos de agente são orquestrados como um gráfico usando Workflow. A lista edges define o fluxo de execução, encadeando nós de START e ativando ramificações condicionais com base em rotas (por exemplo, roteamento para faq_agent em "shipping" ou handle_unrelated em "unrelated").
• LlmAgent: nós declarativos que definem tarefas com tecnologia LLM com instruções, modelos e saídas estruturadas específicos (output_schema).
• Nós e contexto: funções Python decoradas com @node (ou funções padrão) que executam lógica, acessam o estado de execução via Context e geram objetos Event para transmitir dados e sinais de roteamento ao longo do gráfico.
• Modelo: `gemini-3.1-flash-lite' é usado como o modelo de raciocínio rápido padrão.
• Wrapper do app: o objeto App de nível superior envolve o fluxo de trabalho raiz. Ferramentas externas, como o playground local, os arneses de avaliação do ADK e o Agent Runtime, descobrem e executam seu fluxo de trabalho por meio dessa interface app padronizada.

6. Linting automatizado

Antes de executar ou testar seu agente, é recomendável garantir que o código esteja limpo e formatado corretamente.

👉 Comando do Antigravity:

Run linting on my agent project to verify its health.

O Antigravity executa o agents-cli lint nos bastidores para fazer verificações pré-configuradas, verificando importações, sintaxe e consistência de formatação em todos os arquivos.

7. Teste interativo com o Playground

O playground da Web local é a maneira mais rápida de verificar o comportamento do seu agente. Ela oferece uma interface de chat interativa em que você pode conversar com seu agente e inspecionar as execuções de ferramentas em tempo real.

👉 Comando do Antigravity:

Launch the local development playground for my agent.

O Antigravity vai iniciar o servidor de desenvolvimento local (agents-cli playground). Abra o URL fornecido (normalmente http://127.0.0.1:8080/dev-ui/?app=app) no navegador da Web e selecione a pasta app no menu suspenso para começar a conversar com o agente.

Comece a conversar com o agente na interface da Web. Faça uma pergunta relacionada ao frete:

How much is standard shipping?

Observe como o fluxo de trabalho categoriza e encaminha para faq_agent responder. Também tente fazer uma pergunta não relacionada para verificar se o fluxo de trabalho encaminha para handle_unrelated e se recusa a responder corretamente:

What is the weather like?

Testar a atualização automática em tempo real

Você pode ver como as edições em tempo real no seu agente são refletidas no Playground.

1. Modifique a instrução faq_agent em app/agent.py pedindo ao Antigravity:

   Modify the faq_agent instruction in app/agent.py to make the shipping rates
   response more playful and enthusiastic. Add some emojis and highlight the
   free shipping threshold.
   

2. Envie uma nova mensagem ao agente no playground para testar a recarga automática:

   How much is standard shipping?
   

   O playground recarrega e executa automaticamente o código atualizado em tempo real sem precisar reiniciar um servidor. Agora você vai ver alguns emojis na resposta.

8. Execução da linha de comando

Para testes rápidos, automação ou programação de scripts, peça ao Antigravity para executar seu agente diretamente do terminal.

👉 Comando do Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

O Antigravity vai executar o comando de consulta (agents-cli run "How long does standard delivery take?"). Isso executa uma inferência rápida de um único turno e imprime a resposta final do agente junto com os detalhes da execução da ferramenta.

9. Limpeza

Para evitar deixar recursos indesejados no ambiente local, siga estas etapas de limpeza:

1. Interromper servidores locais: se o servidor agents-cli playground ainda estiver em execução, interrompa-o no terminal pressionando Ctrl + C.
2. Remover arquivos do projeto local: exclua o diretório do projeto do agente de scaffolding da sua máquina local.

rm -rf customer-support-agent

10. Resumo e próximas etapas

Parabéns! Você gerenciou com sucesso o ciclo de vida de desenvolvimento local de ponta a ponta de um agente de IA usando a Agents CLI e o ADK 2.0.

O que você aprendeu

• Configurar suas ferramentas: instale a CLI Agents e configure habilidades de fluxo de trabalho específicas do domínio para a Antigravity.
• Estruturou um projeto: criou um projeto customer-support-agent totalmente estruturado usando modelos padronizados.
• Estrutura analisada do ADK 2.0: exploramos fluxos de trabalho de gráficos, agentes de LLM, nós, arestas e roteamento condicional.
• Managed Local Health: realizou verificações automatizadas de qualidade do código usando agents-cli lint.
• Comportamento verificado: testamos o agente de forma interativa com recarga dinâmica em tempo real no ambiente de teste e executamos testes rápidos na linha de comando.

A seguir

Agora que você já domina o loop de desenvolvimento local, veja como expandir e colocar seu agente em produção:

• Avaliação: atribua uma pontuação ao seu agente em relação a um conjunto de avaliação usando agents-cli eval run para medir a acurácia e encontrar regressões.
• Enterprise Cloud Scale: implantação e observabilidade: empacote e implante seu agente em ambientes de produção, como Agent Runtime ou Cloud Run, usando agents-cli deploy. Configure a telemetria de produção para transmitir registros e rastreamentos de execução para o Cloud Trace e o BigQuery.

Outros recursos

• Repositório do GitHub da CLI do Agents
• Documentação do Kit de Desenvolvimento de Agente (ADK)
• Agent Platform Overview