Importar um agente do Google ADK
Este passo a passo importa o Agent Config de uma aplicação construída sobre o Agent Development Kit (ADK) do Google — um agente que responde às perguntas dos clientes sobre seus pedidos — e faz o build da aplicação para Docker Compose. A importação rascunha cada arquivo que o build lê: o agente e seu modelo Gemini, a chave que o agente apresenta ao modelo como uma referência a variável, e as realizações de cada um. Ela pergunta uma única vez pelo único valor que nenhuma configuração contém, a imagem em que a aplicação é executada. Cada arquivo e cada bloco de saída abaixo vêm de uma execução real; a configuração e cada etapa do passo a passo estão no exemplo import-google-adk, onde um script de verificação executa a importação novamente, compara o que ela escreve, o que ela imprime e os blocos que esta página cita com os arquivos mantidos lá, e valida e faz o build do que a importação escreveu.
Gerar o exemplo
Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example import-google-adkEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, que contém o que esta página importa e é onde a importação é executada:
cd import-google-adk
O projeto
O ADK pode declarar os agentes de uma aplicação em arquivos Agent Config em vez de código: adk create --type=config escreve root_agent.yaml, a configuração do agente raiz, e um arquivo de ambiente ao lado dele. Este, escrito para este passo a passo, declara um agente no gemini-2.5-flash do Gemini, com a ferramenta Google Search que acompanha o ADK:
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.jsonname: support_agentmodel: gemini-2.5-flashdescription: Answers a customer's question about their order.instruction: | You answer customers' questions about their orders. When a customer asks where a parcel is, search the web for the tracking page of the company shipping it.tools: - name: google_searchA importação nunca lê o arquivo de ambiente, que costuma conter a chave que a aplicação envia ao Gemini, então o exemplo não contém nenhum. Na raiz do projeto, um .aggrega-config.yaml torna a pasta um espaço de trabalho:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside support_agent/.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiA importação referencia os Components de agente ADK e de modelo Gemini do catálogo, e --target rascunha um Manifest a partir das Recipes desse catálogo. O espaço de trabalho não indica nenhuma pasta de catálogo, então a importação lê o catálogo da biblioteca padrão a partir do registro do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que o histórico que a importação escreve ao lado dos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indica suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa a partir delas em vez disso.
O que a importação pergunta
Um Agent Config nomeia o modelo do agente, nunca a imagem em que a aplicação é executada: você faz o build dessa imagem a partir do seu projeto. O catálogo não contém nenhuma imagem padrão para uma aplicação construída sobre ADK, então a importação pergunta por ela. Em um terminal, ela pergunta e escreve a resposta nos rascunhos e no arquivo de respostas, import-answers.yaml, dentro do diretório que importa, support_agent/, de modo que a próxima importação a lê de lá e não pergunta nada. Sem terminal — em integração contínua ou por meio de um pipe — ela não pergunta nada: escreve o arquivo com a chave vazia e para, nomeando o arquivo. O exemplo já contém o arquivo, com a imagem respondida, ghcr.io/example/support-agent:1.0.0, que representa a imagem cujo build você faz:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # Container image running the application built on ADK, serving its API on infra.port on every # interface. spec.components.support-agent.infra.image: "ghcr.io/example/support-agent:1.0.0" # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin: "google-api-key"A segunda resposta é para um build para Kubernetes, com --target helm: ali o agente lê a chave de API do Gemini de um Secret do Kubernetes, e a resposta é o nome do Secret, google-api-key, nunca a chave. Um build para Docker Compose lê a chave do seu shell em vez disso, então esta importação não usa essa resposta. O arquivo de respostas da importação descreve o arquivo, as perguntas e as regras para a resposta de um segredo.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que nomeia um arquivo de respostas mantido em outro lugar.
Entre em source:
cd sourceExecutar a importação
Indique o diretório do agente. A importação lê o seu root_agent.yaml:
aggrega import support_agent --target composeNa saída padrão, ela lista o que gravou:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> representando a pasta em que você a executou:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the google-adk format, with drafted paths relative to <workspace>info: the answers file <workspace>/support_agent/import-answers.yaml also answers spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not appliedmapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONEmapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONEmade no choice for google_search (tool)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- A linha
infonomeia a resposta que os rascunhos do Docker Compose não usam, mantida no arquivo de respostas para uma compilação para Kubernetes. - As linhas
mappeddizem que o agente é uma instância do agente ADK da biblioteca padrão,core/ai-agent/google-adk, e que o modelo que ele nomeia é uma instância decore/ai-model/gemini. A faixa delas indicaNONE: a importação do ADK referencia esses Components pelo que a configuração nomeia, em vez de comparar cada um com o catálogo. - A linha
made no choicediz que a ferramenta Google Search não se torna nada no rascunho: é uma ferramenta que acompanha o ADK e é executada dentro da aplicação. - A linha
Pull completeé a importação buscando aquilo de que a Release rascunhada depende, como fazaggrega pull, emrelease.lock, para que os rascunhos sejam validados e compilados imediatamente. Com--offline, a importação não busca nada e indica o comandoaggrega pulla executar.
O que a importação grava
O Aggregate, a Release e o Manifest se chamam imported/support-agent, a partir do name do agente raiz, support_agent, reduzido a support-agent, sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).
aggregate.yaml — o agente, ligado ao modelo com a chave que ele apresenta declarada na conexão, e o modelo, começando com comentários que dizem o que foi lido e o que não foi:
# Google ADK agent configurations read:# - root_agent.yaml# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-agent version: 0.1.0 description: Draft Aggregate imported from a source in the google-adk format.spec: components: # The agent tree of root_agent.yaml, served from its root agent support_agent. # Tools ADK ships, which run inside the application, drafted as no Component: google_search. support-agent: type: core/ai-agent/google-adk values: description: "Answers a customer's question about their order." uses: model: gemini-2-5-flash: target: gemini-2-5-flash # For the compose target, the lines below declare credential on gemini-2-5-flash: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. features: credential: type: core/secret-value values: key: GOOGLE_API_KEY # The model gemini-2.5-flash. gemini-2-5-flash: type: core/ai-model/gemini values: model: "gemini-2.5-flash"O ADK serve uma aplicação a partir do seu agente raiz, então o rascunho contém uma instância por árvore de agentes, com o nome do seu agente raiz. A instruction do agente não é levada: a aplicação a lê da sua própria configuração, que a imagem contém.
O ADK serve gemini-2.5-flash por meio da sua classe Gemini, que envia suas requisições à API do Gemini, então o rascunho conecta o modelo ao socket model do agente, que admite apenas a API do Gemini. O Gemini é um serviço hospedado, então o Component do agente recusa uma conexão com ele que não carregue nenhuma credencial; a conexão declara uma, sob a chave GOOGLE_API_KEY. Um modelo que o ADK serve de qualquer outra forma — um nome como gpt-4o que o ADK serve por meio de uma classe própria, ou uma string de modelo do LiteLLM como openai/gpt-4o — não é conectado a nada: um comentário acima da instância o nomeia, e a conexão fica a seu cargo, como descreve No que uma árvore de agentes se torna.
release.yaml — o ambiente, a imagem, a porta publicada e de onde vem a chave:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-agent # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the google-adk format.spec: aggregate: imported/support-agent manifest: imported/support-agent components: support-agent: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations image: "ghcr.io/example/support-agent:1.0.0" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8000 uses: model: gemini-2-5-flash: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential support-agent presents to gemini-2-5-flash on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${GOOGLE_API_KEY}" gemini-2-5-flash: {}O ambiente, development, é um padrão que a importação escreve porque nenhuma configuração nomeia um; altere-o onde a Release for implantada em outro lugar. A imagem é a resposta que a importação leu de support_agent/import-answers.yaml. published_port é 8000, a porta em que a aplicação escuta, então ela responde em http://127.0.0.1:8000 na sua máquina; como diz o comentário, qualquer processo nesta máquina pode alcançá-la ali e nada mais pode, e excluir a linha mantém a aplicação apenas na rede da stack. A configuração não nomeia nenhuma variável para a chave, então a conexão a lê de ${GOOGLE_API_KEY}, a variável que as bibliotecas cliente da API do Gemini leem, como uma referência de variável e nunca como um valor.
manifest.yaml — a Recipe de Compose de cada tipo, e a realização que escreve a referência de variável da chave no arquivo Compose tal como foi escrita:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/support-agent version: 0.1.0spec: mappings: components: type: core/ai-agent/google-adk: compose/google-adk core/ai-model/gemini: compose/gemini features: type: core/secret-value: compose/dotenv-secretrelease.lock registra, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registro do que a importação gravou, que um aggrega import --sync posterior lê.
Validar e compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

A validação imprime:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)e o build, com <workspace> representando a pasta em que você o executou:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distA linha notice é apenas informativa: a Feature de segredo aceita seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.
O serviço do agente em dist/compose/docker-compose.yaml:
services: support-agent: image: ghcr.io/example/support-agent:1.0.0 environment: PORT: "8000" GOOGLE_API_KEY: ${GOOGLE_API_KEY} ports: - 127.0.0.1:8000:8000 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - composeA aplicação recebe a porta em que seu servidor escuta como PORT, e a chave como GOOGLE_API_KEY, que o cliente Gemini do ADK envia para a API do Gemini. O modelo não recebe nenhum serviço próprio: o cliente envia suas requisições para o próprio endereço da API do Gemini e não lê nenhum outro do seu ambiente. A chave é uma referência de variável, preenchida a partir do seu shell quando a stack é iniciada. A Recipe do Compose do agente ADK publica uma porta na sua máquina apenas onde a Release define published_port no infra do agente, e nesse caso somente no endereço de loopback, 127.0.0.1; sem isso, o serviço só é acessível na rede da stack.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `import-google-adk`, chame uma vez a ferramenta `scaffold` com `example` definido como `import-google-adk` e sem `dir`: ela grava o exemplo em uma nova pasta `import-google-adk`, cuja pasta `source` contém o que esta página importa. Depois chame a ferramenta `import` com `workspace_root` definido como `import-google-adk/source`, `source` definido como `support_agent` e `target` definido como `compose`: ela lê as respostas de que precisa em `import-answers.yaml`, dentro da pasta `support_agent`, grava seus rascunhos em `import-google-adk/source` e faz o pull do que eles precisam. Depois chame a ferramenta `validate` com `workspace_root` definido como `import-google-adk/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-google-adk/source`, `release` definido como `release.yaml` e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `import-google-adk/source/dist/`.Abra no VS Code
Com a extensão do Aggrega para o Visual Studio Code instalada, abra no VS Code a pasta import-google-adk/source, onde a importação gravou seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as conexões entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um também é um botão no painel Commands da visualização Aggrega na barra de atividades; Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.
Execução
O Docker Compose executa sua imagem como o serviço renderizado acima, incluindo PORT. A imagem deve escutar nessa porta em todas as interfaces, não em 127.0.0.1, o endereço padrão do servidor de API do ADK. O próprio servidor de API do ADK, adk api_server, serve o diretório de configuração como está, então a imagem não precisa de nenhum código seu. Um Dockerfile na raiz do projeto, ao lado de support_agent/:
FROM python:3.12-slimRUN pip install --no-cache-dir google-adk==2.13.0COPY support_agent/ /app/agents/support_agent/CMD ["sh", "-c", "exec adk api_server --host 0.0.0.0 --port \"$PORT\" --auto_create_session /app/agents"]adk api_server serve os diretórios de agentes da pasta que ele indica, e o comando passa PORT para ele. --auto_create_session abre uma sessão na primeira vez que uma requisição para /run a nomeia, de modo que uma única requisição chega ao agente. Construa a imagem, escreva o nome dela no lugar de ghcr.io/example/support-agent:1.0.0 em support_agent/import-answers.yaml e importe novamente com --sync, que escreve a nova resposta nos rascunhos e faz o pull novamente; depois faça o build:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlEm seguida, defina a chave no seu shell e inicie a stack:
export GOOGLE_API_KEY='your Gemini API key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p dá nome ao projeto, como explica a etapa de execução de Como uma importação é executada. --wait retorna assim que o contêiner está em execução, já que o build não dá ao serviço nenhuma verificação de integridade, e o servidor responde um momento depois, então repita uma requisição que ele recusar.
Teste
Envie ao agente uma mensagem em http://127.0.0.1:8000, o endereço que published_port publica. A requisição indica um usuário e uma sessão, e /run abre a sessão na primeira mensagem:
curl -sS -X POST http://127.0.0.1:8000/run -H 'Content-Type: application/json' \ -d '{"app_name": "support_agent", "user_id": "u1", "session_id": "s1", "new_message": {"role": "user", "parts": [{"text": "Where is my order 1234? Answer in one short sentence."}]}}'A resposta, a do Gemini, volta como uma lista dos eventos que o turno adicionou à sessão. A execução usou um placeholder para a chave, então o Gemini a recusou: a requisição respondeu HTTP 500, Internal Server Error, e o log do serviço, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, informa o motivo:
google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'API key not valid. Please pass a valid API key.', 'status': 'INVALID_ARGUMENT', [… omitted: the error's details]}}curl -sS http://127.0.0.1:8000/list-apps responde ["support_agent"], os agentes que o servidor contém.
Pare a stack com:
docker compose -p support-agent -f dist/compose/docker-compose.yaml downNo Kubernetes
O mesmo agente é importado para Kubernetes com --target helm. Um cluster obtém suas imagens de um registry, então envie a imagem que você construiu para um que o seu cluster leia e escreva o nome dela no lugar da imagem dada como resposta em support_agent/import-answers.yaml; a execução a enviou para um registry na própria máquina do cluster, como localhost:5000/support-agent:1.0.0. A segunda resposta ali nomeia o Secret do qual o agente lê a chave de API do Gemini, google-api-key. Os rascunhos para Docker Compose já estão em source, então gere estes em uma pasta própria e compile a partir dela:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlA compilação grava manifestos simples do Kubernetes em dist/helm/ na raiz do workspace, source, que a partir de helm é ../dist/helm/. Crie o Secret google-api-key no namespace ao qual você aplica, contendo a chave sob a chave de dados value, e aplique a pasta como explica a etapa de execução de Como uma importação é executada. O Service do agente é support-agent-default: encaminhe uma porta local para ele e deixe o comando em execução:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000De outro terminal, a mensagem acima chega ao agente no mesmo endereço, sem alterações. A execução obteve o mesmo Internal Server Error, e kubectl logs -n <namespace> deploy/support-agent informa a mesma recusa da chave placeholder.