O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar um agente com o ADK e a CLI de agentes na Agent Platform

Este documento demonstra como criar, avaliar e implantar um protótipo de agente de IA usando o Kit de Desenvolvimento de Agente (ADK) com a Agents CLI na Agent Platform. O ADK é um framework de código aberto que prioriza o código para criar agentes de IA sofisticados. A Agents CLI oferece uma interface unificada e legível por máquina para que as ferramentas de desenvolvimento de IA interajam com o ADK, permitindo o gerenciamento completo do ciclo de vida do agente. Ele encapsula o conhecimento especializado de ADK, avaliação de agentes e implantação no Google Cloud, permitindo que as ferramentas para desenvolvedores de IA realizem ações complexas com base em comandos de linguagem natural.

Ao usar a Agents CLI com sua ferramenta para desenvolvedores com tecnologia de IA preferida, como a CLI do Gemini, o Claude Code ou o Codex, você pode usar comandos de linguagem natural para definir, testar localmente e implantar um agente de protótipo em umGoogle Cloud ambiente de execução.

Neste tutorial, você vai aprender a criar um agente de "compressor de homem das cavernas", que transforma textos detalhados em resumos concisos, inspirados em homem das cavernas.

Antes de começar

Siga os seguintes pré-requisitos:

Verifique se você tem um projeto do Google Cloud e se ativou a API Agent Platform. Caso contrário, conclua um dos seguintes guias de início rápido:
- Guia de início rápido do console doGoogle Cloud para o Agent Studio para a Gemini Enterprise Agent Platform
- Guia de início rápido da API para modelos
Instale uma ferramenta para desenvolvedores com tecnologia de IA, como o Antigravity, a CLI do Gemini, o Claude Code ou o Codex. Essa ferramenta é necessária para interagir com a Agents CLI.

Configuração

Instale o uv, um instalador de pacotes Python. Para instruções, consulte o guia de instalação do uv.
Execute o comando de configuração da Agents CLI usando uvx (incluído em uv). Esse é o único comando da Agents CLI que você executa diretamente:
```
uvx google-agents-cli setup
```
Abra sua ferramenta para desenvolvedores de IA, como o Antigravity.

Projeto de scaffold

Instrua sua ferramenta para desenvolvedores de IA com o seguinte comando:

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

Sua ferramenta para desenvolvedores de IA ativa as habilidades google-agents-cli-workflow e google-agents-cli-scaffold. Ele executa as seguintes ações:

Faz perguntas para esclarecer, como o destino de implantação e as restrições de segurança.
Grava um arquivo DESIGN_SPEC.md que captura o propósito do agente.

Estrutura o projeto:

agents-cli create caveman-agent --prototype --yes
cd caveman-agent && agents-cli install

Esse processo cria um projeto com código de agente boilerplate, testes e conjuntos de avaliação.

Criar agente

Sua ferramenta para desenvolvedores de IA edita app/agent.py, substituindo o agente padrão pela lógica do compressor de cavernas. Ele usa a habilidade google-agents-cli-adk-code para padrões de design do ADK.

A definição do agente resultante é semelhante a esta:

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules:
   - Omit articles, filler words, and politeness.
   - Use short sentences and simple words.
   - Preserve technical terms.
   - The tone should be abrupt and funny, but the core meaning must be retained.

   Example input:  "I would like to deploy the application to production environment."
   Example output: "Me deploy. Production. Now."
   """,
)

Em seguida, a ferramenta para desenvolvedores de IA realiza um teste funcional básico:

agents-cli run "Please help me understand the deployment options available for my project"

Esta é a saída esperada do teste:

"Opções de implantação: Agent Runtime, Cloud Run, GKE. Escolha uma opção. Ship."

Avaliar agente

Para avaliar o agente, instrua sua ferramenta para desenvolvedores de IA com o seguinte comando:

Write evaluations for the caveman agent and run them.

Sua ferramenta para desenvolvedores de IA ativa a habilidade google-agents-cli-eval e realiza estas tarefas:

Cria tests/eval/evalsets/caveman.evalset.json com casos de teste que abrangem qualidade de compactação, preservação de termos técnicos e tom.
Configura os critérios do LLM como juiz em tests/eval/eval_config.json.
Executa a avaliação:
```
agents-cli eval run
```

Se os casos de teste falharem, forneça feedback corretivo à ferramenta para desenvolvedores de IA. Exemplo:

A resposta ao teste de saudação é muito educada. Deixe mais brusco.

Sua ferramenta para desenvolvedores de IA ajusta as instruções do agente, executa novamente agents-cli eval run e itera até atingir a qualidade desejada.

Implantar agente

Para implantar e executar o agente no Google Cloud, instrua sua ferramenta de desenvolvimento de IA da seguinte maneira:

Deploy this agent to Cloud Run.

Sua ferramenta para desenvolvedores de IA ativa a habilidade google-agents-cli-deploy e:

Adiciona a configuração de infraestrutura de implantação necessária:
```
agents-cli scaffold enhance --deployment-target cloud_run
```
Implanta o agente:
```
agents-cli deploy
```

O agente agora está implantado no Cloud Run. A saída inclui o URL do serviço, que você usa para acessar o agente.

Observar agente

O Cloud Trace é ativado por padrão. Para ver traces, abra o Explorador do Cloud Trace no console do Google Cloud e envie solicitações ao agente implantado. Você vai ver períodos para chamadas de LLM e execuções de ferramentas.

Para ativar uma observabilidade mais detalhada, instrua sua ferramenta para desenvolvedores de IA:

Set up observability infrastructure for my agent.

A ferramenta para desenvolvedores de IA provisiona uma conta de serviço, um bucket do Cloud Storage e um conjunto de dados do BigQuery, além de atualizar o serviço implantado para usar esses recursos. Consulte o Guia de observabilidade para mais detalhes.

Resumo das ações

Esta tabela resume os comandos e as ações correspondentes realizadas pela ferramenta para desenvolvedores de IA:

Instrução do usuário	Ações da ferramenta para desenvolvedores de IA
"Criar um agente de compressão de caverna"	Estrutura o projeto, escreve o código do agente e testa localmente.
"Escrever e executar avaliações"	Cria o evalset, configura o LLM como juiz e executa `agents-cli eval run`.
"Implantar no Cloud Run"	Adiciona a configuração do destino de implantação e implanta no Cloud Run.
"Configurar observabilidade"	Provisiona a conta de serviço, o bucket do Cloud Storage e o conjunto de dados do BigQuery.

As habilidades da Agents CLI fornecem o contexto necessário para que sua ferramenta de desenvolvimento de IA use os padrões apropriados do ADK, estruture avaliações e configure implantações.

A seguir

Explore designs de agentes mais complexos com estes comandos:

Adicionar ferramentas: "Integre uma ferramenta Pesquisa Google para que o agente possa acessar informações atuais."
Sistemas multiagente: "Crie um agente que possa interagir com outros agentes usando o modelo adk_a2a."
RAG: "Crie um agente que responda a perguntas com base na nossa documentação usando o modelo agentic_rag."

Saiba mais sobre a Agent Platform:

ADK: crie, implante e orquestre arquiteturas agênticas.
Agent Runtime: crie, implante e gerencie agentes.
Preços: Aprenda mais sobre os preços da Agent Platform.
Guia de início rápido da Agents CLI

Criar um agente com o ADK e a CLI de agentes na Agent Platform Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.