Importar um agente do Google ADK
Este guia importa o Agent Config de uma aplicação construída sobre o Agent Development Kit (ADK) da Google — um agente que responde às perguntas dos clientes sobre as suas encomendas — e compila a aplicação para Docker Compose. A importação rascunha todos os ficheiros que a compilação lê: o agente e o seu modelo Gemini, a chave que o agente apresenta ao modelo como referência a uma variável, e as realizações de cada um. Pergunta uma única vez pelo único valor que nenhuma configuração contém, a imagem em que a aplicação é executada. Cada ficheiro e cada bloco de saída abaixo provêm de uma execução real; a configuração e cada etapa do guia estão no exemplo import-google-adk, onde um script de verificação volta a executar a importação, compara o que ela escreve, o que ela imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.
Gerar o exemplo
É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example import-google-adkDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, 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 ficheiros Agent Config em vez de código: adk create --type=config escreve root_agent.yaml, a configuração do agente raiz, e um ficheiro de ambiente ao lado dele. Este, escrito para este guia, declara um agente no gemini-2.5-flash do Gemini, com a ferramenta Google Search incluída no 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 ficheiro de ambiente, que normalmente contém a chave que a aplicação envia ao Gemini, pelo que o exemplo não contém nenhum. Na raiz do projeto, um .aggrega-config.yaml faz da 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, pelo que a importação lê o catálogo da biblioteca padrão a partir do registry de onde obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que o registo que a importação escreve junto aos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indique as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa antes com base nessas pastas.
O que a importação pergunta
Um Agent Config indica o modelo do agente, nunca a imagem em que a aplicação é executada: essa imagem é compilada a partir do seu projeto. O catálogo não contém nenhuma imagem predefinida para uma aplicação construída sobre ADK, pelo que a importação pergunta por ela. Num terminal, pergunta e escreve a resposta nos rascunhos e no ficheiro de respostas, import-answers.yaml, dentro do diretório que importa, support_agent/, para que a importação seguinte a leia daí e não pergunte nada. Sem terminal — em integração contínua ou através de um pipe — não pergunta nada: escreve o ficheiro com a chave vazia e para, indicando o ficheiro. O exemplo já contém o ficheiro, com a imagem respondida, ghcr.io/example/support-agent:1.0.0, que representa a imagem que compila:
# 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 destina-se a uma compilação para Kubernetes, com --target helm: aí, o agente lê a chave de API do Gemini a partir de um Secret do Kubernetes, e a resposta é o nome do Secret, google-api-key, nunca a chave. Uma compilação para Docker Compose lê antes a chave a partir da sua shell, pelo que esta importação não usa essa resposta. O ficheiro de respostas da importação descreve o ficheiro, 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 indica um ficheiro de respostas guardado noutro local.
Entre em source:
cd sourceExecutar a importação
Indique o diretório do agente. A importação lê o respetivo root_agent.yaml:
aggrega import support_agent --target composeNa saída padrão, lista o que escreveu:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> a representar a pasta em que 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
infoindica a resposta que os rascunhos para Docker Compose não usam, guardada no ficheiro de respostas para uma compilação para Kubernetes. - As linhas
mappedindicam 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. O escalão de ambas indicaNONE: a importação do ADK referencia estes Components pelo que a configuração nomeia, em vez de comparar cada um com o catálogo. - A linha
made no choiceindica que a ferramenta Google Search não dá origem a nada no rascunho: é uma ferramenta incluída no ADK e é executada dentro da aplicação. - A linha
Pull completeé a importação a obter aquilo de que a Release rascunhada depende, como fazaggrega pull, pararelease.lock, para que os rascunhos sejam validados e compilados de imediato. Com--offline, a importação não obtém nada e indica o comandoaggrega pulla executar.
O que a importação escreve
O Aggregate, a Release e o Manifest chamam-se imported/support-agent, a partir do name do agente raiz, support_agent, reduzido a support-agent, no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definições).
aggregate.yaml — o agente, ligado ao modelo com a chave que apresenta declarada na ligação, e o modelo, a começar com comentários que indicam 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, pelo que o rascunho contém uma instância por árvore de agentes, com o nome do respetivo agente raiz. A instruction do agente não é transportada: a aplicação lê-a da sua própria configuração, que está na imagem.
O ADK serve gemini-2.5-flash através da sua classe Gemini, que envia os seus pedidos à API do Gemini, pelo que o rascunho liga o modelo ao socket model do agente, que admite apenas a API do Gemini. O Gemini é um serviço alojado, pelo que o Component do agente recusa uma ligação a ele que não transporte qualquer credencial; a ligaçã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 através de uma classe própria, ou uma cadeia de modelo do LiteLLM como openai/gpt-4o — não fica ligado a nada: um comentário acima da instância indica-o, e a ligação fica a cargo do utilizador, como descreve Em que se torna uma árvore de agentes.
release.yaml — o ambiente, a imagem, a porta publicada e a origem da 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 valor predefinido que a importação escreve porque nenhuma configuração indica um; altere-o onde a Release for implementada noutro local. 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, pelo que 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 aí e nada mais pode, e eliminar a linha mantém a aplicação apenas na rede da stack. A configuração não indica nenhuma variável para a chave, pelo que a ligação a lê de ${GOOGLE_API_KEY}, a variável que as bibliotecas cliente da API do Gemini leem, como referência de variável e nunca como 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 ficheiro Compose tal como está 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 regista, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registo do que a importação escreveu, 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> a representar a pasta onde 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 o seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Não altera nenhum veredicto.
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 o 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 os seus pedidos 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 da sua shell quando a stack arranca. 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 apenas 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 nele este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. 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`: escreve o exemplo numa 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`: lê as respostas de que precisa de `import-answers.yaml`, dentro da pasta `support_agent`, escreve os seus rascunhos em `import-google-adk/source` e obtém aquilo de que 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 que ficheiros a compilação escreveu; ficam em `import-google-adk/source/dist/`.Abrir 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 escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as ligaçõ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 vista Aggrega na barra de atividades; Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code cobre o resto.
Execução
O Docker Compose executa a imagem como o serviço renderizado acima, incluindo PORT. A imagem tem de escutar nessa porta em todas as interfaces, e não em 127.0.0.1, o endereço predefinido do servidor de API do ADK. O próprio servidor de API do ADK, adk api_server, serve o diretório de configuração tal como está, pelo que a imagem não precisa de código da sua autoria. 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 indica, e o comando passa-lhe PORT. --auto_create_session abre uma sessão da primeira vez que um pedido a /run a indica, de modo que um único pedido 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 volte a importar com --sync, que escreve a nova resposta nos rascunhos e volta a fazer o pull; depois faça o build:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlDepois, defina a chave na 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 o passo de execução de Como decorre uma importação. --wait retorna assim que o contentor está em execução, uma vez que o build não atribui ao serviço nenhuma verificação de estado, e o servidor responde um momento depois, pelo que se deve repetir um pedido que ele recuse.
Testar
Envie ao agente uma mensagem em http://127.0.0.1:8000, o endereço que published_port publica. O pedido indica um utilizador 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, regressa como uma lista dos eventos que o turno acrescentou à sessão. A execução usou um marcador de posição para a chave, pelo que o Gemini a recusou: o pedido respondeu HTTP 500, Internal Server Error, e o registo do serviço, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, indica 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 importa-se para Kubernetes com --target helm. Um cluster obtém as suas imagens de um registo, pelo que deve enviar a imagem que construiu para um registo que o seu cluster leia e escrever o nome dela no lugar da imagem dada como resposta em support_agent/import-answers.yaml; a execução enviou-a para um registo na própria máquina do cluster, como localhost:5000/support-agent:1.0.0. A segunda resposta desse ficheiro indica 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, pelo que deve gerar estes numa pasta própria e compilar a partir dela:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlA compilação escreve manifestos simples do Kubernetes em dist/helm/ na raiz do espaço de trabalho, source, que a partir de helm é ../dist/helm/. Crie o Secret google-api-key no namespace ao qual se aplica, com a chave na chave de dados value, e aplique a pasta como explica o passo de execução de Como decorre uma importação. O Service do agente é support-agent-default: reencaminhe uma porta local para ele e deixe o comando em execução:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000A partir de 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 indica a mesma recusa da chave de marcador de posição.