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 encapsulando 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, compilar, analizar y probar tus agentes de forma local.

Qué aprenderás

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

Requisitos

  • Python 3.11 o versiones posteriores
  • uv
  • Node.js 18+ (si usas habilidades de agente de codificación)
  • IDE de Antigravity (instala y configura desde Google Antigravity)

Requisitos previos

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

  • Usar una terminal y una línea de comandos

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

2. Configura la autenticación y el entorno

Proporciona tus credenciales de autenticación para que el agente llame 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 de Google AI Studio), expórtala en la sesión de la terminal del 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, autentica 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 de Agents y las habilidades

El primer paso es instalar la herramienta agents-cli. Esta herramienta se encarga de la mayor parte 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 CLI de Agents de forma global en tu sistema
  2. Siete habilidades de asistente de codificación específicas del dominio que Antigravity puede usar para ayudarte a compilar, crear, 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 selecciona 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.

👉 Solicita a Antigravity lo siguiente:

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 andamiaje (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 creado.

# 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 gráfico con Workflow. La lista edges define el flujo de ejecución, encadena nodos desde START y habilita la bifurcació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: 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 producen objetos Event para pasar datos y señales de enrutamiento a lo largo del gráfico.
  • Modelo: `gemini-3.1-flash-lite' se usa 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 entorno de pruebas local, los arneses de evaluación del ADK y el entorno de ejecución de agentes, descubren y ejecutan tu flujo de trabajo a través de esta interfaz app estandarizada.

6. Análisis automatizado

Antes de ejecutar o probar tu agente, es una práctica recomendada asegurarte de que tu código esté limpio y formateado correctamente.

👉 Solicita a Antigravity lo siguiente:

Run linting on my agent project to verify its health.

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

7. Pruebas interactivas con el entorno de pruebas

El entorno de pruebas 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 examinar las ejecuciones de herramientas en tiempo real.

👉 Solicita a Antigravity lo siguiente:

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, 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 clasifica y enruta correctamente a faq_agent para responder. También intenta hacer una pregunta no relacionada para verificar que el flujo de trabajo se enrute 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 el entorno de pruebas las ediciones en tiempo real de tu agente.

  1. Para ello, pídele a Antigravity que modifique la instrucción faq_agent en app/agent.py: 
    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 el entorno de pruebas para probar la recarga automática: 
    How much is standard shipping?
    El entorno de pruebas 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.

👉 Solicita a Antigravity lo siguiente:

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 ejecuta una inferencia rápida de un solo turno y muestra 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. Quita los archivos del proyecto local: Borra el directorio del proyecto de agente creado de 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

  • Configurar tus herramientas: Instalaste la CLI de Agents y configuraste habilidades de flujo de trabajo específicas del dominio para Antigravity.
  • Crear un proyecto: Creaste un proyecto customer-support-agent completamente estructurado con plantillas estandarizadas.
  • Analizar la estructura del ADK 2.0: Exploraste flujos de trabajo de gráficos, agentes de LLM, nodos, bordes y enrutamiento condicional.
  • Administrar el estado local: Ejecutaste verificaciones automatizadas de calidad del código con agents-cli lint.
  • Comportamiento verificado: Probaste el agente de forma interactiva con la recarga activa en tiempo real a través del entorno de pruebas y ejecutaste pruebas rápidas en la línea de comandos.

¿Qué sigue?

Ahora que dominas el ciclo de desarrollo local, puedes expandir y producir tu agente de la siguiente manera:

  • 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 la nube empresarial: Implementación & 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