Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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:

Terminal window
aggrega scaffold --example import-google-adk

Em 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:

Terminal window
cd import-google-adk

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando a configuração do agente: support_agent no gemini-2.5-flash com a ferramenta google_search.

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.json
name: support_agent
model: gemini-2.5-flash
description: 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_search

A 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.ai

A 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:

Terminal window
cd source

Executar a importação

Indique o diretório do agente. A importação lê o seu root_agent.yaml:

Terminal window
aggrega import support_agent --target compose

Na saída padrão, ela lista o que gravou:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Na 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 applied
mapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONE
mapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONE
made no choice for google_search (tool)
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

A importação executada a partir do editor: o Aggregate, a Release e o Manifest em rascunho aparecem ao lado da configuração do agente, a saída do Aggrega lista como o agente e seu modelo foram mapeados e os arquivos gravados, e uma notificação informa que a importação gerou 3 arquivos em rascunho, reconhecidos como google-adk.

  • A linha info nomeia a resposta que os rascunhos do Docker Compose não usam, mantida no arquivo de respostas para uma compilação para Kubernetes.
  • As linhas mapped dizem 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 de core/ai-model/gemini. A faixa delas indica NONE: 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 choice diz 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 faz aggrega pull, em release.lock, para que os rascunhos sejam validados e compilados imediatamente. Com --offline, a importação não busca nada e indica o comando aggrega pull a 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/v1beta1
kind: Aggregate
metadata:
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/v1beta1
kind: Release
metadata:
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/v1beta1
kind: Manifest
metadata:
name: imported/support-agent
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/google-adk: compose/google-adk
core/ai-model/gemini: compose/gemini
features:
type:
core/secret-value: compose/dotenv-secret

release.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

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

A Release em rascunho aberta no editor depois de validada, com a saída do Aggrega e uma notificação informando que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista o arquivo do Docker Compose gravado, e uma notificação informa que 1 arquivo foi gravado.

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>/dist

A 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:
- compose

A 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-slim
RUN pip install --no-cache-dir google-adk==2.13.0
COPY 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:

Terminal window
docker build -t support-agent:local .
aggrega import support_agent --sync
aggrega build --release release.yaml

Em seguida, defina a chave no seu shell e inicie a stack:

Terminal window
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:

Terminal window
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:

Terminal window
docker compose -p support-agent -f dist/compose/docker-compose.yaml down

No 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:

Terminal window
aggrega import support_agent --target helm --output-dir helm
cd helm
aggrega build --release release.yaml

A 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:

Terminal window
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000

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 informa a mesma recusa da chave placeholder.