Google ADK Code: padrões Python antes de implementar agentes

ANÁLISE EDITORIAL

Escrever um agente com Google ADK envolve mais do que declarar um modelo e uma função. É preciso escolher o tipo de agente, transformar funções em ferramentas, organizar estado, callbacks e subagentes, decidir quando usar fluxo sequencial, paralelo ou em grafo e separar teste rápido de avaliação comportamental. A Skill Google Agents CLI ADK Code reúne referências Python para essas decisões, mas não cria um projeto sozinha.

A utilidade está na ordem de trabalho. A própria Skill manda ativar primeiro o workflow do Google Agents CLI, estudar receitas mantidas quando a capacidade já existe, criar ou aprimorar o scaffold e só então escrever código. Ela também separa implementação, avaliação e deploy. Isso reduz improviso, mas exige disciplina: os exemplos são referência fixada em um commit, não garantia de que toda assinatura, modelo ou serviço permanecerá igual.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre um núcleo de agente conectado a módulos de ferramentas e caminhos abstratos de workflow. Não é captura de tela, interface real, logotipo oficial, código executado, agente implantado nem prova de acesso ao Google Cloud.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado funciona como uma referência de código para o SDK Python do Google Agent Development Kit. Ele cobre definição de Agent, ferramentas, callbacks, estado, artefatos, memória, comunicação entre agentes e formas de orquestração. A pasta inclui três documentos de apoio: uma referência Python, outra para workflows em grafo e um índice de receitas mantidas.

Ela não é a Skill de scaffold e não é a Skill de deploy. A instrução oficial diz para usar google-agents-cli-scaffold ao criar ou aprimorar a estrutura do projeto e google-agents-cli-deploy quando chegar a hora de escolher destino e publicar. Também exige que google-agents-cli-workflow seja ativada primeiro, pois essa Skill define as fases, os gates de aprovação e as regras de preservação de código.

A referência distingue agentes controlados pelo modelo de fluxos determinísticos. Para uma sequência conhecida, há SequentialAgent. Para tarefas independentes, ParallelAgent. Para repetição com critério de parada, LoopAgent. O material também documenta a API de Workflow em grafo, útil quando a topologia precisa ser explícita, com caminhos, junções, processamento paralelo e etapas de aprovação humana.

Para quem serve

Serve para desenvolvedores Python que já escolheram Google ADK e precisam transformar uma especificação aprovada em código. Também ajuda arquitetos e revisores a conferir se uma implementação usa o mecanismo certo para ferramenta, estado, callback, delegação ou workflow, em vez de criar uma abstração própria sem necessidade.

É mais útil quando existe uma pergunta concreta. “Como compartilho estado entre etapas?”, “quando um subagente deve ser ferramenta?” ou “como paro um loop depois de uma avaliação?” direcionam a leitura para um padrão verificável. O índice de receitas também mapeia capacidades maiores, como RAG, memória entre sessões, aprovação antes de ação arriscada, credenciais por usuário e trabalho orientado a eventos.

Não serve como tutorial autossuficiente para quem ainda não definiu o problema, os dados, as permissões ou o destino. Também não substitui a documentação atual do ADK, o código instalado, os arquivos AGENTS.md das receitas, testes de integração ou avaliação com casos reais. Use a Skill como mapa de implementação, não como autorização para executar infraestrutura.

Compatibilidade e pré-requisitos

A release auditada é a v1.4.1. O metadado oficial do PyPI exige Python 3.11 ou superior e declara Apache-2.0. O fluxo oficial usa uv para instalar e executar o CLI. O guia inicial do projeto também lista Node.js porque a instalação das Skills pode passar pelo ecossistema npx.

O cliente precisa reconhecer Agent Skills e carregar a pasta correta. O repositório declara compatibilidade com diferentes agentes de programação, incluindo Codex, Claude Code e Gemini CLI, mas localização, comandos e permissões mudam por cliente. Confirme onde o cliente instala Skills e se ele carrega referências relativas antes de copiar o pacote.

Para escrever um agente funcional, ainda são necessários o Google ADK e as dependências do projeto criado. Autenticação pode usar Gemini API em desenvolvimento ou Google Cloud em outros cenários. Isso pode envolver chaves, projeto, localização e variáveis de ambiente. Nenhuma credencial vem no ZIP do Bastidores.

O pacote local e sua dependência funcional

O download local preserva SKILL.md, LICENSE, references/samples.md, references/adk-python.md e references/adk-workflows.md. O arquivo ORIGEM.md registra repositório, caminho, commit, data, estrelas, release, licença e limites. São seis arquivos textuais.

O pacote não contém google-agents-cli, SDK, scripts Python, receitas clonadas, projetos, ambiente virtual, dependências, modelos, arquivos .env, chaves ou tokens. A exclusão é deliberada: o catálogo oferece uma cópia documental auditável, enquanto instalação funcional e atualizações devem vir da origem oficial.

Há uma dependência importante. O ADK Code não pretende operar sozinho. A primeira linha de instrução manda ativar google-agents-cli-workflow. O ZIP local não inclui essa outra Skill, pois misturar duas unidades tornaria a origem menos clara. Para uso funcional, instale a suíte oficial e carregue o workflow antes desta referência.

Instalação recomendada

A rota funcional documentada pelo projeto instala o CLI com uv:

uv tool install "google-agents-cli~=1.4.1"

Depois, confira a instalação e o contexto do diretório:

agents-cli info

Para instalar ou atualizar as Skills da suíte, siga a documentação oficial de início rápido. Não copie somente o ADK Code e suponha que as fases de workflow, scaffold, avaliação e deploy estejam presentes. A Skill foi desenhada como parte de um conjunto.

Se a finalidade for auditoria reproduzível, clone o repositório e fixe o commit:

git clone https://github.com/google/agents-cli.git
cd agents-cli
git checkout 048578a00b0b89fc8acdbfb3501895264640f355

Revise skills/google-agents-cli-adk-code, a Skill de workflow e a licença antes de copiar arquivos. Para acompanhar correções posteriores, compare o commit fixado com a release atual. Não atualize em produção sem reler mudanças de comandos, APIs e requisitos.

Configuração antes do primeiro uso

Comece por uma especificação curta: problema, dados, APIs externas, restrições de segurança e destino pretendido. O workflow oficial determina uma fase de entendimento antes do scaffold. Para um agente simples, algumas perguntas e uma especificação breve podem bastar. Para RAG, memória, OAuth, execução de código ou automação longa, a discussão precisa registrar arquitetura e gates.

Em seguida, consulte references/samples.md. O arquivo não entrega uma receita completa; ele aponta qual projeto oficial estudar. Quando houver correspondência, a instrução exige clonar a receita e ler o AGENTS.md dela antes de implementar. Esse cuidado evita reconstruir de memória um sandbox, uma camada de aprovação ou um armazenamento de credenciais.

Proteja o ambiente. Não apague nem substitua arquivos .env existentes. Não coloque chaves em prompts, Markdown, commits ou logs. Preserve o modelo e outras configurações fora do alvo solicitado. Qualquer mudança de modelo deve ser deliberada e verificada na lista atual do provedor, não inferida de um exemplo antigo.

Primeiro uso seguro

Com a especificação aprovada, verifique se o diretório já é um projeto reconhecido:

agents-cli info

Se não houver projeto, use a Skill de scaffold antes de escrever código. Para um projeto novo, a referência orienta agents-cli scaffold create <nome>. Para código existente, use agents-cli scaffold enhance .. Leia a ajuda da versão instalada antes de confirmar flags.

Ao implementar, comece pelo menor padrão necessário. Uma ferramenta deve ter tipo, descrição clara e retorno serializável. Um output_key pode salvar a resposta no estado. Em tarefas paralelas, cada ramo precisa de uma chave diferente para evitar disputa. Se usar output_schema, observe o alerta da referência: essa opção desativa chamadas de ferramenta e delegação naquele agente.

Faça um smoke test com um prompt controlado e dados não sensíveis. O workflow sugere agents-cli run para uma verificação rápida. Isso não substitui avaliação. Depois, carregue a Skill de avaliação, defina casos e critérios e leia os resultados. Deploy só deve acontecer após os gates e aprovação humana explícita.

Resultado esperado

O primeiro resultado correto não é um agente em produção. É um projeto reconhecido, com estrutura preservada, uma implementação mínima coerente com a especificação e um smoke test que permite localizar falhas. O código deve deixar claro quais ferramentas existem, quais dados entram no estado e qual componente controla o fluxo.

Se a tarefa for sequencial, o resultado pode ser uma cadeia pequena com saídas nomeadas. Se houver paralelismo, os ramos devem escrever em chaves distintas e convergir em um passo explícito. Se houver loop, deve existir limite de iterações ou evento de saída. Em grafo, nós e arestas precisam refletir o processo real, incluindo qualquer pausa para aprovação.

Considere a etapa de construção concluída apenas quando o comportamento tiver sido avaliado em casos representativos. Teste unitário verifica função, tipo e contrato. Avaliação verifica resposta, uso de ferramentas, trajetória e critérios de qualidade. Um único prompt bem-sucedido não demonstra robustez.

Permissões e riscos

O arquivo Markdown não executa nada sozinho, mas orienta comandos capazes de criar arquivos, instalar dependências, chamar modelos, acessar APIs e, em fases posteriores, provisionar infraestrutura. Revise cada comando no contexto do projeto e limite a execução ao diretório autorizado. Não use credenciais pessoais quando uma conta de serviço ou segredo escopado for mais apropriado.

Receitas podem incluir Terraform, filas, bancos, armazenamento, OAuth ou execução de código. Clonar uma receita não concede autorização para provisionar seus recursos. Leia o AGENTS.md, identifique custos, regiões, dados, egress e operações destrutivas. Importe recursos existentes quando houver conflito de estado, em vez de repetir criação.

Modelos e exemplos envelhecem. O código auditado mostra nomes válidos para a release fixada, mas disponibilidade depende de conta, região e data. Liste modelos atuais antes de criar algo novo. Ao modificar projeto existente, preserve o modelo já escolhido, a menos que o usuário peça a troca.

O fluxo também alerta contra deploy automático. Implantação expõe código, dados e custos. Exija aprovação explícita, valide avaliação, autenticação, logs, retenção, observabilidade e rollback. O ZIP do Bastidores não contém infraestrutura e não deve ser tratado como pacote pronto para produção.

Erros comuns

• Carregar só esta Skill: ative primeiro o workflow e use as Skills de scaffold, avaliação e deploy nas fases corretas.
• Escrever código antes da especificação: confirme problema, dados, segurança e destino.
• Ignorar o índice de receitas: leia references/samples.md e o AGENTS.md da receita correspondente.
• Copiar uma receita inteira: estude o padrão e adapte somente o necessário.
• Usar a mesma chave em ramos paralelos: separe output_key para evitar disputa de estado.
• Combinar output_schema com ferramentas: a referência alerta que o schema estruturado desativa chamadas de ferramenta e delegação.
• Testar comportamento com pytest: use testes para código e a avaliação do CLI para comportamento do agente.
• Trocar modelo por conveniência: preserve configurações existentes e verifique disponibilidade atual.
• Expor .env: mantenha chaves fora de prompts, logs, ZIP e repositório.
• Tratar smoke test como aprovação: um prompt não substitui casos de avaliação.
• Executar deploy ao terminar o código: exija revisão e aprovação humana explícita.
• Confundir ZIP com suíte funcional: o download é documental e não contém o CLI nem dependências.

Versão auditada e download local

A curadoria fixou o commit 048578a00b0b89fc8acdbfb3501895264640f355. Em 25/08/2026, o repositório oficial google/agents-cli tinha 5.717 estrelas, não estava arquivado e publicava a release 1.4.1. Estrelas indicam adoção observável, não segurança ou compatibilidade futura.

A licença Apache-2.0 permite redistribuição sob suas condições. O download local auditado tem 30.358 bytes e SHA-256 8a38de9de8cd6685567f01af8285fde4279bec2b6c1b3f0cca0689d2d07cbccf. Ele contém somente LICENSE, ORIGEM.md, SKILL.md e as três referências Markdown.

Resultado esperado e limite final

Google Agents CLI ADK Code é uma boa referência para transformar uma decisão de arquitetura em um padrão Python identificável. O ganho não vem de copiar todos os exemplos, mas de escolher o componente certo, preservar o projeto e estudar uma receita mantida quando o problema já foi resolvido.

Use a Skill quando a especificação estiver aprovada e o scaffold existir. Leia a referência ligada à dúvida, implemente o menor caminho, faça smoke test e siga para avaliação. Separe teste de código, avaliação de comportamento e autorização de deploy. Essa separação é o principal controle de qualidade do fluxo.

O commit fixado torna esta auditoria reproduzível, mas não congela o ecossistema. Antes de executar, releia a documentação atual, o pacote instalado e a ajuda do comando. Confirme versão, modelo, região, autenticação, custo e permissões. Atualize somente depois de comparar mudanças.

Fontes primárias

• Repositório oficial google/agents-cli
• Release oficial v1.4.1
• Pasta da Skill no commit auditado
• SKILL.md oficial fixado
• Índice oficial de receitas
• Referência Python oficial fixada
• Referência oficial de workflows
• Workflow obrigatório da suíte
• Licença Apache-2.0
• Pacote oficial 1.4.1 no PyPI
• Referência oficial do CLI
• Tutorial oficial de primeiro agente