Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Importar un agente de Google ADK

Esta guía paso a paso importa la Agent Config de una aplicación construida sobre el Agent Development Kit (ADK) de Google — un agente que responde a las preguntas de los clientes sobre sus pedidos — y compila la aplicación para Docker Compose. La importación genera como borrador cada archivo que lee la compilación: el agente y su modelo Gemini, la clave que el agente presenta al modelo como referencia a una variable, y las realizaciones de cada uno. Pide una sola vez el único valor que ninguna configuración contiene, la imagen en la que se ejecuta la aplicación. Cada archivo y cada bloque de salida que aparecen a continuación proceden de una ejecución real; la configuración y cada etapa de la guía están en el ejemplo import-google-adk, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos que se conservan allí, y valida y compila lo que escribió la importación.

Generar el ejemplo

Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, que contiene lo que esta página importa y es donde se ejecuta la importación:

Terminal window
cd import-google-adk

La carpeta source del ejemplo generado abierta en Visual Studio Code, mostrando la configuración del agente: support_agent sobre gemini-2.5-flash con la herramienta google_search.

El proyecto

ADK puede declarar los agentes de una aplicación en archivos Agent Config en lugar de en código: adk create --type=config escribe root_agent.yaml, la configuración del agente raíz, y un archivo de entorno junto a él. Este, escrito para esta guía, declara un agente sobre gemini-2.5-flash de Gemini, con la herramienta Google Search que incluye 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

La importación nunca lee el archivo de entorno, que suele contener la clave que la aplicación envía a Gemini, así que el ejemplo no incluye ninguno. En la raíz del proyecto, un .aggrega-config.yaml convierte la carpeta en un espacio de trabajo:

# 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

La importación hace referencia a los Components del catálogo para el agente ADK y el modelo Gemini, y --target genera un borrador de Manifest a partir de sus Recipes. El espacio de trabajo no indica ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar desde el registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que el historial que la importación escribe junto a sus borradores nombra por su resumen criptográfico. Un espacio de trabajo que indica sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS, o bajo workspace.catalog_dirs — importa en cambio a partir de ellas.

Qué pide la importación

Una Agent Config nombra el modelo del agente, nunca la imagen en la que se ejecuta la aplicación: esa imagen la compilas a partir de tu proyecto. El catálogo no contiene ninguna imagen predeterminada para una aplicación construida sobre ADK, así que la importación la pide. En un terminal la pide y escribe la respuesta en los borradores y en el archivo de respuestas, import-answers.yaml, dentro del directorio que importa, support_agent/, de modo que la siguiente importación la lee de ahí y no pregunta nada. Sin terminal — en integración continua o a través de una tubería — no pregunta nada: escribe el archivo con la clave vacía y se detiene, nombrando el archivo. El ejemplo ya contiene el archivo, con la imagen respondida, ghcr.io/example/support-agent:1.0.0, que representa la imagen que compilas:

# 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"

La segunda respuesta es para una compilación para Kubernetes, con --target helm: allí el agente lee la clave de API de Gemini de un Secret de Kubernetes, y la respuesta es el nombre del Secret, google-api-key, nunca la clave. Una compilación para Docker Compose lee en cambio la clave de tu shell, así que esta importación no usa esa respuesta. El archivo de respuestas de la importación describe el archivo, las preguntas y las reglas para la respuesta de un secreto.

aggrega import enumera cada opción que admite el comando, entre ellas --answers, que nombra un archivo de respuestas guardado en otro lugar.

Entra en source:

Terminal window
cd source

Ejecutar la importación

Indica el directorio del agente. La importación lee su root_agent.yaml:

Terminal window
aggrega import support_agent --target compose

En la salida estándar enumera lo que escribió:

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

En la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:

[… 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)

La importación ejecutada desde el editor: el Aggregate, la Release y el Manifest en borrador aparecen junto a la configuración del agente, la salida de Aggrega enumera cómo se asignaron el agente y su modelo y los archivos escritos, y una notificación indica que la importación generó 3 archivos en borrador, reconocidos como google-adk.

  • La línea info nombra la respuesta que los borradores de Docker Compose no usan, guardada en el archivo de respuestas para una compilación para Kubernetes.
  • Las líneas mapped indican que el agente es una instancia del agente ADK de la biblioteca estándar, core/ai-agent/google-adk, y que el modelo que nombra es una instancia de core/ai-model/gemini. Su nivel es NONE: la importación de ADK hace referencia a estos Components por lo que nombra la configuración, en lugar de evaluar cada uno frente al catálogo.
  • La línea made no choice indica que para la herramienta Google Search no se genera nada: es una herramienta que incluye ADK y se ejecuta dentro de la aplicación.
  • La línea Pull complete es la importación obteniendo aquello de lo que depende la Release redactada, como hace aggrega pull, en release.lock, para que los borradores se validen y se compilen de inmediato. Con --offline, la importación no obtiene nada e indica el comando aggrega pull que hay que ejecutar.

Lo que escribe

El Aggregate, la Release y el Manifest se llaman imported/support-agent, por el name del agente raíz, support_agent, reducido a support-agent, bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).

aggregate.yaml — el agente, conectado al modelo con la clave que presenta declarada en la conexión, y el modelo, precedidos por comentarios que dicen qué se leyó y qué no:

# 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"

ADK sirve una aplicación desde su agente raíz, así que el borrador contiene una instancia por árbol de agentes, con el nombre de su agente raíz. La instruction del agente no se traslada: la aplicación la lee de su propia configuración, que contiene la imagen.

ADK sirve gemini-2.5-flash a través de su clase Gemini, que envía sus solicitudes a la API de Gemini, así que el borrador conecta el modelo al socket model del agente, que solo admite la API de Gemini. Gemini es un servicio alojado, así que el Component del agente rechaza una conexión hacia él que no lleve ninguna credencial; la conexión declara una, con la clave GOOGLE_API_KEY. Un modelo que ADK sirve de cualquier otra forma —un nombre como gpt-4o que ADK sirve mediante una clase propia, o una cadena de modelo de LiteLLM como openai/gpt-4o— no se conecta a nada: un comentario encima de la instancia lo nombra, y la conexión queda en tus manos, como describe En qué se convierte un árbol de agentes.

release.yaml — el entorno, la imagen, el puerto publicado y de dónde procede la clave:

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: {}

El entorno, development, es un valor predeterminado que escribe la importación porque ninguna configuración nombra uno; cámbialo donde la Release se despliegue en otro lugar. La imagen es la respuesta que la importación leyó de support_agent/import-answers.yaml. published_port es 8000, el puerto en el que escucha la aplicación, así que responde en http://127.0.0.1:8000 en tu máquina; como dice su comentario, cualquier proceso de esta máquina puede alcanzarla ahí y nada más puede, y eliminar la línea mantiene la aplicación solo en la red del stack. La configuración no nombra ninguna variable para la clave, así que la conexión la lee de ${GOOGLE_API_KEY}, la variable que leen las bibliotecas cliente de la API de Gemini, como referencia de variable y nunca como valor.

manifest.yaml — la Recipe de Compose de cada tipo, y la realización que escribe la referencia de variable de la clave tal cual en el archivo Compose:

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, las entidades del catálogo a las que se resolvió la Release, y .aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior.

Validar y compilar

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

La Release en borrador abierta en el editor tras validarla, con la salida de Aggrega y una notificación que indican que no se encontraron problemas.

El build de la Release en borrador: aparece una carpeta dist en el Explorador, la salida de Aggrega enumera el archivo de Docker Compose escrito y una notificación indica que se escribió 1 archivo.

La validación 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)

y la compilación, donde <workspace> representa la carpeta en la que la ejecutaste:

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

La línea notice es informativa: la Feature de secreto acepta su origin desde los values del Aggregate o desde la infra de la Release, y el aviso informa de que una hoja está declarada en ambos. No cambia ningún veredicto.

El servicio del agente en 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

La aplicación recibe el puerto en el que escucha su servidor como PORT, y la clave como GOOGLE_API_KEY, que el cliente de Gemini de ADK envía a la API de Gemini. El modelo no tiene un servicio propio: el cliente envía sus solicitudes a la dirección propia de la API de Gemini y no lee ninguna otra de su entorno. La clave es una referencia de variable, que se rellena desde tu shell cuando arranca el stack. La Recipe de Compose del agente ADK publica un puerto en tu máquina solo donde la Release establece published_port en el infra del agente, y en ese caso solo en la dirección de loopback, 127.0.0.1; sin ello, el servicio solo es accesible en la red del stack.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `import-google-adk`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-google-adk` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-google-adk`, cuya carpeta `source` contiene lo que esta página importa. Luego llama a la herramienta `import` con `workspace_root` establecido en `import-google-adk/source`, `source` establecido en `support_agent` y `target` establecido en `compose`: lee las respuestas que necesita de `import-answers.yaml`, dentro de la carpeta `support_agent`, escribe sus borradores en `import-google-adk/source` y descarga lo que necesitan. Luego llama a la herramienta `validate` con `workspace_root` establecido en `import-google-adk/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-google-adk/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió el build; están en `import-google-adk/source/dist/`.

Ábrelo en VS Code

Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-google-adk/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividad; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.

Ejecución

Docker Compose ejecuta tu imagen como el servicio renderizado arriba, PORT incluido. La imagen debe escuchar en ese puerto en todas las interfaces, no en 127.0.0.1, la dirección predeterminada del servidor de API de ADK. El propio servidor de API de ADK, adk api_server, sirve el directorio de configuración tal como está, así que la imagen no necesita código tuyo. Un Dockerfile en la raíz del proyecto, junto a 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 sirve los directorios de agentes de la carpeta que indica, y el comando le pasa PORT. --auto_create_session abre una sesión la primera vez que una solicitud a /run la nombra, de modo que una sola solicitud llega al agente. Construye la imagen, escribe su nombre en lugar de ghcr.io/example/support-agent:1.0.0 en support_agent/import-answers.yaml y vuelve a importar con --sync, que escribe la nueva respuesta en los borradores y vuelve a hacer el pull; después ejecuta el build:

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

Después establece la clave en tu shell e inicia el 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 da nombre al proyecto, como explica el paso de ejecución de Cómo se ejecuta una importación. --wait regresa en cuanto el contenedor se ejecuta, ya que el build no asigna al servicio ninguna comprobación de estado, y el servidor responde un momento después, así que repite una solicitud que rechace.

Probarlo

Envía al agente un mensaje en http://127.0.0.1:8000, la dirección que publica published_port. La solicitud indica un usuario y una sesión, y /run abre la sesión con su primer mensaje:

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."}]}}'

La respuesta, la de Gemini, vuelve como una lista de los eventos que el turno añadió a la sesión. La ejecución usó un marcador de posición para la clave, así que Gemini la rechazó: la solicitud respondió HTTP 500, Internal Server Error, y el registro del servicio, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, indica el 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"], los agentes que contiene el servidor.

Detén el stack con:

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

En Kubernetes

El mismo agente se importa para Kubernetes con --target helm. Un clúster obtiene sus imágenes de un registro, así que sube la imagen que construiste a uno que lea tu clúster y escribe su nombre en lugar de la imagen dada como respuesta en support_agent/import-answers.yaml; la ejecución la subió a un registro en la propia máquina del clúster, como localhost:5000/support-agent:1.0.0. La segunda respuesta de ese archivo nombra el Secret del que el agente lee la clave de API de Gemini, google-api-key. Los borradores para Docker Compose ya están en source, así que genera estos en una carpeta propia y compila desde ella:

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

La compilación escribe manifiestos simples de Kubernetes en dist/helm/ en la raíz del espacio de trabajo, source, que desde helm es ../dist/helm/. Crea el Secret google-api-key en el namespace al que aplicas, con la clave bajo la clave de datos value, y aplica la carpeta como explica el paso de ejecución de Cómo se ejecuta una importación. El Service del agente es support-agent-default: reenvía a él un puerto local y deja el comando en ejecución:

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

Desde otra terminal, el mensaje anterior llega al agente en la misma dirección, sin cambios. La ejecución obtuvo el mismo Internal Server Error, y kubectl logs -n <namespace> deploy/support-agent indica el mismo rechazo de la clave de marcador de posición.