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

Este documento demonstra como criar, avaliar e implantar um agente de IA protótipo usando o Kit de Desenvolvimento de Agente (ADK) com a CLI de agentes na Agent Platform. O ADK é um framework de código aberto e com foco no código para criar agentes de IA sofisticados. A CLI de agentes 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 do ciclo de vida do agente de ponta a ponta. Ela encapsula o conhecimento especializado do ADK, a avaliação e a implantação de agentes para Google Cloud, permitindo que as ferramentas de desenvolvimento de IA executem ações complexas a partir de comandos de linguagem natural.

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

Este tutorial orienta você na criação de um agente "compressor de caverna", que transforma textos detalhados em resumos concisos, inspirados no homem das cavernas.

Antes de começar

Atenda aos seguintes pré-requisitos:

  1. Verifique se você tem um Google Cloud projeto e ativou a API Agent Platform. Caso contrário, conclua um dos seguintes guias de início rápido:

  2. 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 de agentes.

Configuração

  1. Instale o uv, um instalador de pacotes Python. Para instruções, consulte o guia de instalação do uv.

  2. Execute o comando de configuração da CLI de agentes usando uvx (incluído no uv). Esse é o único comando da CLI de agentes que você executa diretamente:

    uvx google-agents-cli setup

  3. Abra sua ferramenta de desenvolvimento de IA, como o Antigravity.

Projeto de andaime

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 as restrições de segurança.
  • Grava um arquivo DESIGN_SPEC.md que captura a finalidade do agente.

  • Cria a estrutura 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 padrão, 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 caverna. 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 executa 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: Agent Runtime, Cloud Run, GKE. Escolha uma. Enviar."

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 executa estas tarefas:

  • Cria tests/eval/evalsets/caveman.evalset.json com casos de teste que abrangem a qualidade da compactação, a preservação de termos técnicos e o 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, forneça feedback corretivo à sua ferramenta de desenvolvimento de IA. Exemplo:

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

Sua ferramenta de desenvolvimento de IA ajusta as instruções do agente, executa agents-cli eval run novamente e itera até que a qualidade desejada seja alcançada.

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.

Observar agente

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

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

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 e atualiza 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 executadas pela sua ferramenta de desenvolvimento de IA:

Instrução do usuário Ações da sua ferramenta de desenvolvimento de IA
"Criar um agente compressor de caverna" Cria a estrutura do projeto, grava o código do agente e testa localmente.
"Escrever avaliações e executá-las" Cria o conjunto de avaliação, configura o LLM como juiz e executa agents-cli eval run.
"Implantar isso no Cloud Run" Adiciona a configuração do 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 de agentes fornecem o contexto necessário para que sua ferramenta de desenvolvimento de IA use padrões de ADK adequados, avaliações de estrutura e implantações de configuração.

A seguir

Confira designs de agentes mais complexos com estes comandos:

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

Saiba mais sobre a Agent Platform: