Compilar un agente con Google ADK

En esta guía, puede aprender a compilar y ejecutar un agente con el Google Agent Development Kit (ADK). El paquete agent-engine-sdk-adk es un adaptador entre ADK y el MongoDB Atlas agente motor. El adaptador traduce los agentes de ADK, los nodos de flujo de trabajo y llamar de herramientas en operaciones que el motor de orquestación de la plataforma ejecuta y registra.

El adaptador es durable, por lo que los agentes de ADK se ejecutan en moda de flujo de trabajo durable. El Orchestration motor, no ADK, almacena el estado de cada sesión. La plataforma también almacena los resultados de cada llamada al modelo y llamada a la herramienta. Una ejecución reanudada reproduce los resultados registrados en lugar de repetir las acciones de ejecución.

Consideraciones de Google ADK

Cuando compile un agente ADK en Atlas Agent motor, tenga en cuenta los siguientes puntos clave:

El SDK de Google ADK solo está disponible para Python. Para compilar un agente en Typescript, consulte la guía del SDK de Typescript.
Su agente debe establecer el valor features.durable_workflow en true en el archivo agent.yaml. Si omite este campo o lo establece en false, la primera invocación fallará. Para aprender más sobre los campos disponibles en el archivo agent.yaml, consulte el esquema de agent.yaml.
El paquete agent-engine-sdk-adk acepta un BaseAgent de ADK o un 2 Workflow de ADK como raíz de su agente.

Requisitos previos

Asegúrese de tener los siguientes requisitos previos antes de empezar:

Python 3.11 o posterior.
uv administrador de paquetes.
CLI agentengine instalado y autenticado. Para aprender cómo hacerlo, consulte Crear un proyecto.
Google ADK versión 2.9.0 o posterior. Para aprender a instalar ADK, consulte la documentación de instalación de ADK.
Clave de API para su proveedor de LLM. El comando agentengine create solicita la clave y la guarda en su archivo .env como LLM_API_KEY.

Pasos

Cree un Proyecto a partir de una plantilla de inicio de ADK.

Ejecute el comando agentengine create con una de las plantillas de ADK:

agentengine create --template hello-world-agent-adk

La plantilla hello-world-agent-adk crea un agente mínimo. La plantilla insurance-agent-adk crea un agente para el sector de los seguros. Para aprender sobre todas las plantillas disponibles y las opciones de comando agentengine create, consulte Plantillas admitidas.

Revisión el código de la plantilla.

Abre el módulo de punto de entrada en tu Proyecto. La plantilla ya registra una herramienta y compila el agente. El módulo utiliza las siguientes funcionalidad de SDK:

@app.tool(): Registra una función como herramienta en la plataforma. El decorador no expone automáticamente la herramienta a su agente.
@app.entrypoint: Marca la función que devuelve tu agente ADK.
app.llm(): Envuelve una instancia de ADK BaseLlm para que la plataforma pueda auditar cada llamar al modelo.
app.tools(): Devuelve sus herramientas registradas con el contenedor seguro de la plataforma aplicado.

Importante

Pasa las herramientas que devuelve la función app.tools() a tu agente, no las funciones que decoras con @app.tool().

Ejecutar el agente localmente.

Desde el directorio de su agente, ejecute el siguiente comando para iniciar el entorno de desarrollo local:

agentengine dev up

Para aprender sobre la recarga en caliente y las modas aisladas, consulte Ejecutar y probar su agente localmente.

Implementar el agente.

Ejecute el siguiente comando para compilar e implementar su agente en un solo paso:

agentengine deploy --auto

El agente implementado también requiere su clave de API de LLM. Para aprender a proporcionar secretos a un agente implementado, consulte Provision nube Secrets.

Para aprender a compilar e implementar como pasos separados, consulte Compilar la imagen del agente y Implementar su compilación.

Añadir revisión humana a una herramienta

Para pausar una ejecución hasta que una persona apruebe una llamar de herramienta, envuelva una función de herramienta llamable en la clase FunctionTool de ADK y pase la opción require_confirmation=True al constructor. Para pausar una ejecución y recopilar información que no sea una aprobación, utilice la clase LongRunningFunctionTool de ADK. Envuelva las funciones de herramienta llamables que devuelve app.tools(), no las funciones sin procesar que decora con @app.tool().

El siguiente ejemplo envuelve cada herramienta que se puede llamar que app.tools() devuelve en la clase FunctionTool, de modo que cada llamada de herramienta espera la aprobación humana antes de ejecutar:

import os
from google.adk.agents import LlmAgentfrom google.adk.models.lite_llm import LiteLlmfrom google.adk.tools.function_tool import FunctionTool
@app.entrypointdef build_agent():    return LlmAgent(        name="daily",        instruction="You are a helpful assistant.",        model=app.llm(            LiteLlm(                model="<model-name>",                api_key=os.environ["LLM_API_KEY"],            )        ),        tools=[            FunctionTool(tool, require_confirmation=True)            for tool in app.tools()        ],    )

Nota

Las herramientas MCP remotas que devuelve app.tools() son objeto BaseTool de ADK, no llamables simples, por lo que no puede envolverlas con la clase FunctionTool. La plataforma rige las llamar de herramientas MCP a través de la política y las barandillas de Orchestration motor.

Responder a solicitudes de herramientas

Una respuesta de confirmación tiene la sintaxis de objeto ADK {confirmed: true|false}. La plataforma realiza un registro de cada pausa como una actividad de Orchestration motor y utiliza el ID de actividad como ID de interrupción.

Para reanudar una ejecución pausada, envíe una solicitud al endpoint de invocación en la misma sesión. En la solicitud, incluya un objeto resume_map que asigne el ID de cada pausa pendiente a su respuesta. Debe dar respuesta a todas las pausas pendientes en la misma solicitud. Para encontrar los ID, lea la lista suspend_context.interrupts de la ejecución pausada. Para aprender más, consulte API de invocación.

El siguiente ejemplo de cuerpo de solicitud responde a dos pausas pendientes. La primera respuesta aprueba una llamar de herramienta que requiere confirmación. La segunda respuesta devuelve la entrada que solicitó una herramienta pausada diferente.

{  "resume_map": {    "<activity-id-1>": { "confirmed": true },    "<activity-id-2>": "us-east-1"  }}

Para reanudar desde la CLI, utilice las opciones --session y --resume del comando agentengine invoke. Para obtener más información, consulte Invocar a un agente desde la CLI.

Nota

Los agentes de ADK se ejecutan en moda de flujo de trabajo durable, por lo que los reanuda con una solicitud resume_map y no con el cuerpo de solicitud decision descrito en la guía Human-in-the-Loop.

Estructuras de agente compatibles

El paquete agent-engine-sdk-adk requiere la estructura completa de Workflow y del agente cuando se inicia el agente. La plataforma hace un registro de cada paso por su ruta en esa estructura. La siguiente tabla enumera la funcionalidad de ADK que admite el paquete agent-engine-sdk-adk:

Funcionalidad de ADK	Soporte
Raíz simple `BaseAgent`	Admitido
`Workflow` nodos configurados estáticamente, incluidos grafos seriales y paralelos anidados	Admitido
Parámetro `sub_agents` configurado, donde el modelo selecciona el agente secundario que se va a ejecutar llamando a la función `transfer_to_agent`	Admitido
Nodos de agente de flujo de trabajo con transferencias configuradas	Compatible cuando el agente utiliza `mode="chat"`
Agentes envueltos con la clase `AgentTool`	Rechazado antes de la ejecución. Utiliza `sub_agents` configurado en su lugar.
`NodeTool` y los nodos pasados a `run_node()` en tiempo de ejecución	Rechazado con un error antes de que se inicie el agente o nodo anidado.

Añadir otra funcionalidad de la plataforma

Las siguientes funcionalidades de la plataforma funcionan con agentes de ADK:

Servidores MCP remotos que declara en el campo mcp del archivo agent.yaml. La plataforma descubre las herramientas al inicio y las devuelve desde app.tools(). Para aprender más, consulte Usar servidores MCP remotos.
Revisión de la salida de guardrail. Un guardrail llm_output con la acción require_review pausa llamar al modelo hasta que un revisor aprueba o deniega la salida. Revise la salida a través de la solicitud resume_map.

Obtén más información

Volver

Compila un agente profundo