Crea un agente con el ADK y la CLI de Agents en Agent Platform

En este documento, se muestra cómo compilar, evaluar e implementar un prototipo de agente de IA con el Kit de desarrollo de agentes (ADK) y la CLI de Agents en Agent Platform. El ADK es un framework de código abierto centrado en el código para crear agentes de IA sofisticados. La CLI de Agents proporciona una interfaz unificada y legible por máquina para que las herramientas de desarrollo de IA interactúen con el ADK, lo que permite la administración del ciclo de vida del agente de extremo a extremo. Encapsula el conocimiento experto del ADK, la evaluación de agentes y la implementación en Google Cloud, lo que permite que las herramientas de desarrollo de IA realicen acciones complejas a partir de instrucciones en lenguaje natural.

Si usas Agents CLI con tu herramienta de desarrollo potenciada por IA preferida, como Gemini CLI, Claude Code o Codex, puedes usar instrucciones de lenguaje natural para definir, probar de forma local y, luego, implementar un agente de prototipo en un entorno de ejecución deGoogle Cloud .

En este instructivo, se explica cómo crear un agente de "compresor cavernícola", que transforma texto detallado en resúmenes concisos, inspirado en caveman.

Antes de comenzar

Completa los siguientes requisitos previos:

  1. Asegúrate de tener un Google Cloud proyecto y de haber habilitado la API de Agent Platform. De lo contrario, completa una de las siguientes guías de inicio rápido:

  2. Instala una herramienta de desarrollo potenciada por IA, como Antigravity, Gemini CLI, Claude Code o Codex. Esta herramienta es necesaria para interactuar con la CLI de Agents.

Configuración

  1. Instala uv, un instalador de paquetes de Python. Para obtener instrucciones, consulta la guía de instalación de uv.

  2. Ejecuta el comando de configuración de la CLI de Agents con uvx (incluido con uv). Este es el único comando de la CLI de Agents que ejecutas directamente:

    uvx google-agents-cli setup

  3. Abre tu herramienta de desarrollo de IA, como Antigravity.

Proyecto de Scaffold

Dale a tu herramienta de desarrollo de IA la siguiente instrucción:

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

Tu herramienta de desarrollo de IA activa las habilidades google-agents-cli-workflow y google-agents-cli-scaffold. Con él, se realizan las siguientes acciones:

  • Hace preguntas aclaratorias, como el objetivo de implementación y las restricciones de seguridad.
  • Escribe un archivo DESIGN_SPEC.md que captura el propósito del agente.

  • Crea el proyecto:

    agents-cli create caveman-agent --prototype --yes
cd caveman-agent && agents-cli install

Este proceso crea un proyecto con código de agente de plantilla, pruebas y conjuntos de evaluación.

Crear agente

Tu herramienta de desarrollo de IA edita app/agent.py y reemplaza el agente predeterminado por la lógica del compresor de cavernícola. Utiliza la habilidad google-agents-cli-adk-code para los patrones de diseño del ADK.

La definición del agente resultante se parece a la siguiente:

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-flash-latest"),
   instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules:
   - Omit articles, filler words, and politeness.
   - Use short sentences and simple words.
   - Preserve technical terms.
   - The tone should be abrupt and funny, but the core meaning must be retained.

   Example input:  "I would like to deploy the application to production environment."
   Example output: "Me deploy. Production. Now."
   """,
)

Luego, tu herramienta de desarrollo de IA realizará una prueba de funcionalidad básica:

agents-cli run "Please help me understand the deployment options available for my project"

Este es el resultado esperado de esa prueba:

"Opciones de implementación: Agent Runtime, Cloud Run, GKE. Elige una. Envía".

Evaluar agente

Para evaluar el agente, dale a tu herramienta de desarrollo de IA la siguiente instrucción:

Write evaluations for the caveman agent and run them.

Tu herramienta de desarrollo de IA activa la habilidad google-agents-cli-eval y realiza las siguientes tareas:

  • Crea tests/eval/evalsets/caveman.evalset.json con casos de prueba que abarcan la calidad de la compresión, la conservación de términos técnicos y el tono.
  • Configura los criterios de LLM como juez en tests/eval/eval_config.json.

  • Ejecuta la evaluación:

    agents-cli eval run

Si fallan los casos de prueba, proporciona comentarios correctivos a tu herramienta de desarrollo de IA. Por ejemplo:

La respuesta a la prueba de saludo es demasiado cortés. Hazlo más brusco.

Tu herramienta de desarrollo de IA ajusta las instrucciones del agente, vuelve a ejecutar agents-cli eval run y realiza iteraciones hasta que se logra la calidad deseada.

Implementa el agente

Para implementar y ejecutar el agente en Google Cloud, indica a tu herramienta de desarrollo de IA lo siguiente:

Deploy this agent to Cloud Run.

Tu herramienta de desarrollo de IA activa la habilidad google-agents-cli-deploy y hace lo siguiente:

  • Agrega la configuración de infraestructura de implementación necesaria:

    agents-cli scaffold enhance --deployment-target cloud_run

  • Implementa el agente:

    agents-cli deploy

El agente ahora se implementó en Cloud Run. El resultado incluye la URL del servicio, que usas para acceder al agente.

Agente de observación

Cloud Trace está habilitado de forma predeterminada. Para ver los seguimientos, abre el Explorador de Cloud Trace en la consola de Google Cloud y envía solicitudes a tu agente implementado. Verás intervalos para las llamadas de LLM y las ejecuciones de herramientas.

Para habilitar una observabilidad más detallada, indica a tu herramienta de desarrollo de IA lo siguiente:

Set up observability infrastructure for my agent.

Tu herramienta de desarrollo de IA aprovisiona una cuenta de servicio, un bucket de Cloud Storage y un conjunto de datos de BigQuery, y actualiza el servicio implementado para usar estos recursos. Consulta la Guía de observabilidad para obtener más detalles.

Resumen de acciones

En esta tabla, se resumen las instrucciones y las acciones correspondientes que realiza tu herramienta de desarrollo de IA:

Instrucciones para el usuario Acciones de tu herramienta de desarrollo de IA
"Crea un agente de compresión de cavernícola" Crea la estructura del proyecto, escribe el código del agente y realiza pruebas de forma local.
"Escribe evaluaciones y ejecútalas" Crea un conjunto de evaluación, configura el LLM como juez y ejecuta agents-cli eval run.
"Implementar esto en Cloud Run" Agrega la configuración del destino de implementación y realiza la implementación en Cloud Run.
"Configura la observabilidad" Aprovisiona la cuenta de servicio, el bucket de Cloud Storage y el conjunto de datos de BigQuery.

Las habilidades de la CLI de Agents proporcionan el contexto necesario para que tu herramienta de desarrollo de IA use patrones del ADK adecuados, evalúe la estructura y configure las implementaciones.

¿Qué sigue?

Explora diseños de agentes más complejos con estas instrucciones:

  • Agregar herramientas: "Integra una herramienta de Búsqueda de Google para que el agente pueda acceder a información actual".
  • Sistemas multiagente: "Crea un agente que pueda interactuar con otros agentes usando la plantilla adk_a2a".
  • RAG: "Crea un agente que responda preguntas basadas en nuestra documentación con la plantilla agentic_rag".

Obtén más información sobre Agent Platform: