Vibe Coding AI Agents: Administración del ciclo de vida del agente con Agents CLI y ADK 2.0

1. Descripción general

En este codelab, aprenderás a usar la CLI de Agents para controlar el ciclo de vida completo del desarrollo local de un agente de IA. Ya sea que estés adaptando modelos de Gemini existentes o creando agentes personalizados desde cero con el Kit de desarrollo de agentes (ADK 2.0), la CLI de Agents proporciona las herramientas para crear la estructura, compilar, verificar y probar tus agentes de forma local.

Qué aprenderás

  • Cómo instalar y configurar agents-cli y sus habilidades asociadas
  • Cómo generar la estructura de un proyecto de agente nuevo
  • Estructura y archivos clave de un proyecto de agente de flujo de trabajo de gráfico de ADK 2.0
  • Cómo ejecutar la limpieza de código y el análisis de código automatizados
  • Cómo iniciar y usar el playground web local para realizar pruebas interactivas con recarga automática

Requisitos

  • Python 3.11 o una versión posterior
  • Administrador de paquetes uv
  • Node.js 18 o versiones posteriores (si usas habilidades de agente de programación)
  • IDE de Antigravity (instálalo y configúralo desde Google Antigravity)

Requisitos previos

En este codelab, se supone que tienes experiencia en lo siguiente:

  • Usar una terminal y una línea de comandos

No se requiere experiencia previa con agentes de IA ni con ADK 2.0.

2. Configura la autenticación y el entorno

Proporciona tus credenciales de autenticación para que el agente pueda llamar a los modelos de Gemini.

Opción 1: Clave de API de Gemini (Google AI Studio)

Si usas una clave de API de Gemini estándar (que puedes obtener en Google AI Studio), expórtala en la sesión de la terminal de tu IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Opción 2: Credenciales predeterminadas de la aplicación de Google Cloud

Si usas Vertex AI en Google Cloud, autentícate con las credenciales predeterminadas de la aplicación (ADC) de Google Cloud y configura tu proyecto activo de Google Cloud:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Configura la CLI y las habilidades de Agents

El primer paso es instalar la herramienta de agents-cli. Esta herramienta se encarga de las tareas más pesadas de la administración de proyectos de agentes.

Con Antigravity instalado, ejecuta el comando de configuración directamente en tu terminal.

👉 Abre una terminal y ejecuta lo siguiente:

uvx google-agents-cli setup

Este comando instala automáticamente lo siguiente:

  1. La herramienta de la CLI de Agents de forma global en tu sistema
  2. Siete habilidades específicas del dominio del asistente de programación que Antigravity puede usar para ayudarte a compilar, estructurar, evaluar e implementar agentes. Estas habilidades se instalan una vez de forma global en ~/.agents/skills/ y Antigravity las descubre automáticamente.

Nota: Las habilidades se instalan en ~/.agents/skills/ y Antigravity las detecta automáticamente. Puedes verificar esto con el comando /skills o la configuración de Antigravity.

Resultado esperado (recortado):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Crea tu proyecto de agente

En esta sección, crearás un directorio de proyecto completamente estructurado con la plantilla de prototipo.

👉 Solicitar Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity ejecuta automáticamente el comando de scaffolding (agents-cli scaffold create customer-support-agent --prototype --yes) y configura los archivos del proyecto por ti.

5. Explora el código del agente

👉 Pídele a Antigravity que explique el código generado:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

En el IDE de Antigravity, los archivos y artefactos del proyecto recién creados se muestran directamente en el panel auxiliar (lado izquierdo). Puedes ver app/agent.py allí o abrirlo desde el explorador de archivos del IDE para explorar el código generado.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Conceptos clave

  • Flujo de trabajo y bordes: En el ADK 2.0, las aplicaciones de agentes se organizan como un grafo con Workflow. La lista edges define el flujo de ejecución, encadenando nodos desde START y habilitando la ramificación condicional según las rutas (p.ej., el enrutamiento a faq_agent en "shipping" o handle_unrelated en "unrelated").
  • LlmAgent: Nodos declarativos que definen tareas potenciadas por LLM con instrucciones, modelos y resultados estructurados específicos (output_schema).
  • Nodos y contexto: Son funciones de Python decoradas con @node (o funciones estándar) que realizan lógica, acceden al estado de ejecución a través de Context y generan objetos Event para pasar datos y señales de enrutamiento a lo largo del gráfico.
  • Modelo: Se usa "gemini-3.1-flash-lite" como el modelo de razonamiento rápido predeterminado.
  • Wrapper de la app: El objeto App de nivel superior encapsula el flujo de trabajo raíz. Las herramientas externas, como el playground local, los arneses de evaluación del ADK y Agent Runtime, descubren y ejecutan tu flujo de trabajo a través de esta interfaz app estandarizada.

6. Análisis de código automatizado

Antes de ejecutar o probar tu agente, es una buena práctica asegurarte de que tu código esté limpio y con el formato correcto.

👉 Solicitar Antigravity:

Run linting on my agent project to verify its health.

Antigravity ejecutará agents-cli lint tras bambalinas para ejecutar verificaciones preconfiguradas, y verificará las importaciones, la sintaxis y la coherencia del formato en todos tus archivos.

7. Pruebas interactivas con Playground

El playground web local es la forma más rápida de verificar el comportamiento de tu agente. Proporciona una interfaz de chat interactiva en la que puedes chatear con tu agente y, también, inspeccionar las ejecuciones de herramientas en tiempo real.

👉 Solicitar Antigravity:

Launch the local development playground for my agent.

Antigravity iniciará el servidor de desarrollo local (agents-cli playground). Abre la URL proporcionada (por lo general, http://127.0.0.1:8080/dev-ui/?app=app) en tu navegador web y selecciona la carpeta app en el menú desplegable para comenzar a chatear con tu agente.

Comienza a chatear con tu agente en la interfaz web. Intenta hacer una pregunta relacionada con el envío:

How much is standard shipping?

Observa cómo el flujo de trabajo categoriza y enruta correctamente la pregunta a faq_agent para que la responda. También puedes hacer una pregunta no relacionada para verificar que el flujo de trabajo se dirija a handle_unrelated y se niegue a responder correctamente:

What is the weather like?

Prueba la recarga automática en tiempo real

Puedes ver cómo se reflejan en Playground los cambios en tiempo real que realices en tu agente.

  1. Modifica la instrucción faq_agent en app/agent.py pidiéndole a Antigravity que lo haga: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Envía un mensaje nuevo al agente en la zona de pruebas para probar la recarga automática: 
    How much is standard shipping?
    El Playground se vuelve a cargar y ejecuta automáticamente el código actualizado en tiempo real sin necesidad de reiniciar el servidor. Ahora deberías ver algunos emojis en la respuesta.

8. Ejecución de la línea de comandos

Para realizar pruebas rápidas, automatización o secuencias de comandos, puedes pedirle a Antigravity que ejecute tu agente directamente desde la terminal.

👉 Solicitar Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity ejecutará el comando de consulta (agents-cli run "How long does standard delivery take?"). Esto ejecutará una inferencia rápida de un solo turno y mostrará la respuesta final del agente junto con los detalles de ejecución de la herramienta.

9. Limpieza

Para evitar dejar recursos no deseados en tu entorno local, sigue estos pasos de limpieza:

  1. Detén los servidores locales: Si tu servidor agents-cli playground aún se está ejecutando, detenlo en la terminal presionando Ctrl + C.
  2. Remove Local Project Files: Borra el directorio del proyecto del agente generado en tu máquina local.
rm -rf customer-support-agent

10. Resumen y próximos pasos

¡Felicitaciones! Administraste correctamente el ciclo de vida de desarrollo local de extremo a extremo de un agente de IA con la CLI de Agents y el ADK 2.0.

Qué aprendiste

  • Configura tus herramientas: Instalaste la Agents CLI y configuraste habilidades de flujo de trabajo específicas del dominio para Antigravity.
  • Se creó un proyecto con estructura: Se creó un proyecto customer-support-agent completamente estructurado con plantillas estandarizadas.
  • Estructura analizada del ADK 2.0: Se exploraron flujos de trabajo de gráficos, agentes de LLM, nodos, aristas y enrutamiento condicional.
  • Managed Local Health: Se ejecutaron verificaciones automatizadas de la calidad del código con agents-cli lint.
  • Comportamiento verificado: Se probó el agente de forma interactiva con recarga en caliente en tiempo real a través de la zona de pruebas y se ejecutaron pruebas rápidas en la línea de comandos.

¿Qué sigue?

Ahora que dominas el ciclo de desarrollo local, te mostramos cómo puedes expandir y llevar a producción tu agente:

  • Evaluación: Califica tu agente en un conjunto de evaluación con agents-cli eval run para medir la exactitud y encontrar regresiones.
  • Escala de nube empresarial: Implementación y Observabilidad: Empaqueta e implementa tu agente en entornos de producción como Agent Runtime o Cloud Run con agents-cli deploy. Configura la telemetría de producción para transmitir registros y seguimientos de ejecución a Cloud Trace y BigQuery.

Recursos adicionales