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

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:

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

Depois, 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:

Terminal window
cd import-google-adk

A pasta source do exemplo gerado aberta no Visual Studio Code, a mostrar 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 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.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 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.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, 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:

Terminal window
cd source

Executar a importação

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

Terminal window
aggrega import support_agent --target compose

Na saída padrão, lista o que escreveu:

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

Na 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 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 o seu modelo foram mapeados e os ficheiros escritos, e uma notificação indica que a importação gerou 3 ficheiros em rascunho, reconhecidos como google-adk.

  • A linha info indica a resposta que os rascunhos para Docker Compose não usam, guardada no ficheiro de respostas para uma compilação para Kubernetes.
  • As linhas mapped indicam 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. O escalão de ambas indica NONE: 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 choice indica 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 faz aggrega pull, para release.lock, para que os rascunhos sejam validados e compilados de imediato. Com --offline, a importação não obtém nada e indica o comando aggrega pull a 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/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, 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/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 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/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 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

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 a indicar que não foram encontrados problemas.

A compilação da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista o ficheiro do Docker Compose escrito e uma notificação indica que foi escrito 1 ficheiro.

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

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

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

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

Depois, defina a chave na 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 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:

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

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

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

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

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

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

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