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

En este documento, se muestra cómo crear, evaluar e implementar un prototipo de agente de IA con el Kit de desarrollo de agentes (ADK) y la CLI de agentes en Agent Platform. El ADK es un framework de código abierto y centrado en el código para crear agentes de IA sofisticados. La CLI de agentes proporciona una interfaz unificada y legible por máquinas para que las herramientas de desarrollo de IA interactúen con el ADK, lo que permite administrar el ciclo de vida de los agentes 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 para desarrolladores potenciada por IA preferida, como Gemini CLI, Claude Code o Codex, puedes usar instrucciones de lenguaje natural para definir, probar de forma local e implementar un agente prototipo en un entorno de ejecución deGoogle Cloud .

En este instructivo, se te guiará para crear un agente de "compresor de cavernícola", que transforma el texto detallado en resúmenes concisos, inspirado en cavernícola.

Antes de comenzar

Completa los siguientes requisitos previos:

  1. Asegúrate de tener un proyecto de Google Cloud 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 para desarrolladores 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 Agents CLI con uvx (incluido en uv). Este es el único comando de Agents CLI que ejecutas directamente:

    uvx google-agents-cli setup

  3. Abre tu herramienta para desarrolladores de IA, como Antigravity.

Proyecto de Scaffold

Indícale 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 para desarrolladores de IA activa las habilidades de google-agents-cli-workflow y google-agents-cli-scaffold. Con él, se realizan las siguientes acciones:

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

  • Crea la estructura del proyecto:

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

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

Crear agente

Tu herramienta para desarrolladores 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-3.5-flash"),
   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 realiza 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. Ship."

Evaluar agente

Para evaluar el agente, indica a tu herramienta para desarrolladores de IA la siguiente instrucción:

Write evaluations for the caveman agent and run them.

Tu herramienta para desarrolladores de IA activa la habilidad google-agents-cli-eval y realiza estas tareas:

  • Crea tests/eval/evalsets/caveman.evalset.json con casos de prueba que abarcan la calidad de la compresión, la preservació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 los casos de prueba fallan, 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 alcanza la calidad deseada.

Implementar 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 para desarrolladores de IA activa la habilidad de 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 está implementado en Cloud Run. El resultado incluye la URL del servicio, que usas para acceder al agente.

Observa al agente

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 a LLM y las ejecuciones de herramientas.

Para habilitar una observabilidad más detallada, indícale a tu herramienta para desarrolladores de IA lo siguiente:

Set up observability infrastructure for my agent.

Tu herramienta para desarrolladores 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 para desarrolladores de IA:

Instrucción 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.
"Implementa esto en Cloud Run" Agrega la configuración del destino de implementación y, luego, implementa 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 Agents CLI proporcionan el contexto necesario para que tu herramienta de desarrollo de IA use patrones de ADK adecuados, estructure evaluaciones y configure implementaciones.

¿Qué sigue?

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

  • Agrega herramientas: "Integra una herramienta de la 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 según nuestra documentación con la plantilla agentic_rag".

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