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

Este documento mostra como criar, avaliar e implantar um protótipo de agente de IA usando o Kit de Desenvolvimento de Agente (ADK) com a CLI Agents na plataforma de agentes. O ADK é um framework de código aberto com foco em código para criar agentes de IA sofisticados. A CLI Agents 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 do ADK, da avaliação e da implantação de agentes no Google Cloud, permitindo que as ferramentas de desenvolvimento de IA executem ações complexas com base em comandos de linguagem natural.

Ao usar a CLI Agents com sua ferramenta de desenvolvimento 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 um tempo de execução doGoogle Cloud .

Neste tutorial, você vai criar um agente "compressor das cavernas", que transforma textos longos em resumos concisos, inspirado no homem das cavernas.

Antes de começar

Atenda aos seguintes pré-requisitos:

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

Configuração

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

Projeto de scaffolding

Instrua sua ferramenta de desenvolvimento de IA com o seguinte comando:

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

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

Faz perguntas esclarecedoras, como o destino da implantação e restrições de segurança.
Grava um arquivo DESIGN_SPEC.md que captura a finalidade do agente.

Faz o scaffolding do 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 de desenvolvimento de IA edita app/agent.py, substituindo o agente padrão pela lógica do compressor de homem das 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-flash-latest"),
   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, sua ferramenta de desenvolvimento de IA realiza um teste de funcionalidade básica:

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

Esta é a saída esperada desse teste:

"Opções de implantação: ambiente de execução do agente, Cloud Run, GKE. Escolha uma. Envio."

Avaliar agente

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

Write evaluations for the caveman agent and run them.

Sua ferramenta de desenvolvimento 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 de LLM como juiz em tests/eval/eval_config.json.
Executa a avaliação:
```
agents-cli eval run
```

Se os casos de teste falharem, envie feedback corretivo para sua ferramenta de desenvolvimento de IA. Exemplo:

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

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

Implantar agente

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

Deploy this agent to Cloud Run.

Sua ferramenta de desenvolvimento 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.

Agente de observação

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

Para ativar uma observabilidade mais detalhada, instrua sua ferramenta de desenvolvimento de IA a:

Set up observability infrastructure for my agent.

Sua ferramenta de desenvolvimento 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 sua ferramenta de desenvolvimento de IA:

Instruções para usuários	Suas ações de ferramentas de desenvolvimento de IA
"Crie um agente compressor de homem das cavernas"	Cria a estrutura do projeto, escreve o código do agente e testa localmente.
"Escrever e executar avaliações"	Cria um evalset, configura o LLM como um juiz e executa `agents-cli eval run`.
"Implantar no Cloud Run"	Adiciona a configuração de destino de implantação e implanta no Cloud Run.
Configurar a observabilidade	Provisiona a conta de serviço, o bucket do Cloud Storage e o conjunto de dados do BigQuery.

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

A seguir

Explore designs de agentes mais complexos com estes comandos:

Adicionar ferramentas: "Integre uma ferramenta da 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 plataforma de agentes:

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

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