Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

CLI de Agents en Agent Platform: Del desarrollo a la producción

1. Descripción general

Qué aprenderás

En este codelab, compilarás, probarás e implementarás un agente de IA listo para producción con la CLI de Agents y el Kit de desarrollo de agentes (ADK). En menos de una hora, pasarás de instalar las herramientas a tener un agente en vivo ejecutándose en el entorno de ejecución del agente de Google Cloud.

Qué compilarás

Un agente de IA de asistencia al cliente que puede hacer lo siguiente:

Responde preguntas con lenguaje natural
Llama a herramientas personalizadas (búsquedas de clima y hora)
Realizar pruebas locales con comentarios instantáneos
Se evalúa automáticamente la calidad.
Ejecuta en producción en Google Cloud

Dos formas de usar la CLI de Agents

La CLI de Agents admite dos flujos de trabajo:

🤖 Con un agente de programación (recomendado para principiantes)

¡Deja que la IA te guíe! Instala habilidades en Gemini CLI, Antigravity, Claude Code, Cursor o cualquier otro agente de programación compatible. Te ayudarán a compilar el agente paso a paso.

👤 Modo manual (para desarrolladores que prefieren el control directo)

Ejecuta comandos por tu cuenta desde la terminal. Escribirás cada comando y verás exactamente lo que sucede.

A lo largo de este codelab, mostraremos ambos enfoques. Elige la que se adapte a tu estilo.

Requisitos

Obligatorio:

Python 3.11 o una versión posterior
Administrador de paquetes uv
Node.js 18 o versiones posteriores (para las habilidades del agente de codificación)
Proyecto de Google Cloud con la facturación habilitada
SDK de Google Cloud instalado

Opcional para el desarrollo solo local:

Clave de API de AI Studio (alternativa a GCP para pruebas locales)

Requisitos previos

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

Usa una terminal o línea de comandos
Conceptos básicos de Python
Conceptos básicos de la consola de Google Cloud

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

2. Antes de comenzar

Configura Google Cloud

Crea o selecciona un proyecto

Ve a la consola de Google Cloud.
Crea un proyecto nuevo o selecciona uno existente
Anota tu ID del proyecto, ya que lo necesitarás más adelante.

Habilita las API obligatorias

Ejecuta estos comandos en tu terminal (o usa Cloud Console):

gcloud services enable aiplatform.googleapis.com \
  run.googleapis.com \
  cloudtrace.googleapis.com \
  cloudbuild.googleapis.com

Esto permite lo siguiente:

Agent Platform: Para el modelo de Gemini y Agent Runtime
Cloud Run: Opción de implementación alternativa
Cloud Trace: Observabilidad y supervisión
Cloud Build: Automatización de compilaciones

Autenticar

gcloud auth login
gcloud auth application-default login

Configura las variables de entorno

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1

Reemplaza YOUR_PROJECT_ID por el ID de tu proyecto.

3. Instala la CLI de Agents

🤖 Con un agente de programación

Si usas Gemini CLI, Antigravity, Claude Code, Cursor o cualquier otro agente de programación compatible, haz lo siguiente:

uvx google-agents-cli setup

Se instala lo siguiente:

La herramienta de CLI de Agents a nivel global
7 habilidades que cualquier agente de programación compatible en tu máquina puede usar para ayudarte a compilar agentes (las habilidades se instalan una vez y las descubre cada agente que las admite)

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

Las habilidades se instalan a través de skills (npx -y skills@latest) en ~/.agents/skills/ y todos los agentes de programación compatibles de tu máquina las detectan automáticamente.

👤 Modo manual

Si prefieres ejecutar comandos directamente, haz lo siguiente:

uv tool install google-agents-cli

Verifica la instalación:

agents-cli --version

Resultado esperado:

agents-cli, version 0.1.2

4. Crea tu proyecto de agente

🤖 Con un agente de programación

Pregúntale a tu agente de programación:

"Crea un nuevo proyecto de agente del ADK llamado customer-support-agent con la plantilla de prototipo".

Tu agente ejecutará el comando de estructura y creará el proyecto por ti.

👤 Modo manual

Usa el modo rápido para crear un proyecto coherente que coincida con este codelab:

agents-cli scaffold create customer-support-agent --prototype --yes

Esto crea al instante un proyecto básico de agente de ADK con todo el código necesario para este codelab.

Resultado esperado:

Agents CLI v0.1.2
> Verifying GCP credentials...
> ✓ Connected to project: YOUR_PROJECT_ID

✅ Success! Your agent project is ready.

📖 Documentation
   README:    cat customer-support-agent/README.md

💡 Tip
   Add a deployment target later with: agents-cli scaffold enhance

🚀 Get Started
   cd customer-support-agent && agents-cli install && agents-cli playground

Alternativa: Modo interactivo

Si quieres explorar otros tipos de agentes, ejecuta el comando sin marcas:

agents-cli scaffold create customer-support-agent

Verás las siguientes opciones:

adk: Agente ReAct simple (elige esta opción para el codelab)
adk_a2a: Comunicación de agente a agente
agentic_rag: Preguntas y respuestas sobre documentos basadas en RAG

¿Qué se creó?

customer-support-agent/
├── app/
│   ├── agent.py              # Your agent code (main file)
│   ├── fast_api_app.py       # Development server (replaced when you add a deployment target)
│   └── app_utils/            # Utilities (telemetry, etc.)
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── eval/                 # Evalsets and rubric config for `adk eval`
├── Dockerfile                # Container image (removed when you switch to Agent Runtime)
├── GEMINI.md                 # Coding-agent context for this project
├── pyproject.toml            # Project config & dependencies
├── README.md                 # Project documentation
└── .gitignore

5. Explora el código del agente

Navega a tu proyecto

cd customer-support-agent

Examina el agente

Abre app/agent.py, donde se define tu agente:

import datetime
from zoneinfo import ZoneInfo

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"


def get_weather(query: str) -> str:
    """Simulates a web search. Use it get information on weather.

    Args:
        query: A string containing the location to get weather information for.

    Returns:
        A string with the simulated weather information for the queried location.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."


def get_current_time(query: str) -> str:
    """Simulates getting the current time for a city.

    Args:
        city: The name of the city to get the current time for.

    Returns:
        A string with the current time information.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        tz_identifier = "America/Los_Angeles"
    else:
        return f"Sorry, I don't have timezone information for query: {query}."

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return f"The current time for query {query} is {now.strftime('%Y-%m-%d %H:%M:%S %Z%z')}"


root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-flash-latest",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather, get_current_time],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Conceptos clave

Herramientas: Son las funciones de Python que tu agente puede llamar.

get_weather(query): Devuelve el clima simulado (neblina y 15 °C para SF, soleado y 32 °C para el resto).
get_current_time(query): Devuelve la hora actual (solo San Francisco en este fragmento).

Modelo: gemini-flash-latest es un alias que hace un seguimiento automático de la versión estable más reciente de Gemini Flash, por lo que este código sigue funcionando a medida que Google lanza nuevas versiones. Para fijar un modelo específico, reemplázalo por algo como gemini-2.5-flash (estable) o gemini-3-flash-preview (vista previa).

App / root_agent: Los proyectos del ADK exponen un App de nivel superior que contiene un root_agent. La zona de pruebas, adk eval y Agent Runtime descubren el agente a través de este objeto app.

Ubicación =

"global": Algunos modelos de la versión preliminar de Gemini solo se entregan desde el extremo global, por lo que el código de ejemplo lo establece de forma explícita.

Instruction: Es la instrucción del sistema que define el comportamiento del agente.

6. Realiza pruebas locales con la zona de pruebas

La zona de pruebas proporciona una interfaz de chat interactiva para realizar pruebas.

🤖 Con un agente de programación

Pregúntale a tu agente:

"Inicia el Playground para mi agente"

👤 Modo manual

Primero, instala las dependencias

agents-cli install

Esto ejecuta uv sync en segundo plano, resuelve e instala las dependencias del agente en un .venv local.

Cómo iniciar el área de juegos

agents-cli playground

Resultado esperado:

╭──────────────────────────────────────────────────────────────────────────────╮
│ Starting your agent playground...                                            │
│                                                                              │
│ Will be available at:  http://127.0.0.1:8080/dev-ui/?app=app                 │
╰──────────────────────────────────────────────────────────────────────────────╯
  ▸ uv run adk web . --host 127.0.0.1 --port 8080 --reload_agents
INFO:     Started server process
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080

Probar

Abre http://127.0.0.1:8080/dev-ui/?app=app en tu navegador.
Prueba estas instrucciones:
- "¿Cómo está el clima en San Francisco?"
- "¿Cómo está el clima en Tokio?"
- "¿Qué hora es en San Francisco?"

Mira cómo el agente:

Llama a la herramienta get_weather
Llama a la herramienta get_current_time
Combina los resultados en respuestas naturales

7. Ejecuta desde la línea de comandos

Probar tu agente sin abrir un navegador

🤖 Con un agente de programación

Pregúntale a tu agente:

"Ejecuta el agente con la búsqueda "¿Cómo está el clima en París?"".

👤 Modo manual

agents-cli run "What's the weather in San Francisco?"

Resultado esperado:

Using project root directory: /path/to/customer-support-agent
Local server started on port 18080 (PID 30008)
  Stop with: agents-cli run --stop-server
[user]: What's the weather in San Francisco?
[root_agent]:
[tool_call: get_weather({"query": "San Francisco"})]
[tool_response: get_weather -> {"result": "It's 60 degrees and foggy."}]The weather in San Francisco is 60 degrees and foggy.

Session: fb30f7f7-147e-4697-8aaa-706d604589fa (resume with --session-id)

Tras bambalinas, run inicia un adk api_server en segundo plano (que se mantiene activo durante unos 30 minutos) para que las llamadas posteriores sean rápidas. Detenlo de forma explícita con agents-cli run --stop-server. Reanuda una conversación de varios turnos con --session-id .

El comando run es ideal para lo siguiente:

Pruebas rápidas durante el desarrollo
Escritura de secuencias de comandos y automatización
Canalizaciones de CI/CD

8. Evalúa tu agente

Las evaluaciones del ADK validan dos aspectos independientes:

Trayectoria de la herramienta: ¿El agente llamó a las herramientas correctas con los argumentos correctos? Es determinístico y de concordancia exacta.
Calidad de la respuesta: ¿La respuesta final es pertinente, útil y se basa en los resultados de la herramienta? Un LLM que actúa como juez califica la respuesta.

Necesitas ambos. La puntuación de la rúbrica por sí sola podría aprobar una respuesta alucinada que se lea bien; la trayectoria por sí sola no puede indicar si el usuario recibió una respuesta útil. El conjunto de evaluación del codelab ejercita ambos.

Estos se basan en dos archivos:

tests/eval/evalsets/basic.evalset.json: Son las conversaciones que se reproducirán, además de las llamadas a herramientas esperadas.
tests/eval/eval_config.json: Qué métricas se deben calificar, sus umbrales y la rúbrica para el evaluador de LLM

Edita el conjunto de evaluación para incluir las llamadas a herramientas esperadas

Reemplaza el contenido de tests/eval/evalsets/basic.evalset.json con lo siguiente:

{
  "eval_set_id": "basic_eval",
  "name": "Basic Agent Evaluation",
  "description": "Validates that the agent calls the right tools AND produces a quality response.",
  "eval_cases": [
    {
      "eval_id": "weather_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather like in San Francisco?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in San Francisco is 60 degrees and foggy."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "weather_tokyo",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather in Tokyo?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in Tokyo is 90 degrees and sunny."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "Tokyo"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "time_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What time is it in San Francisco?"}], "role": "user"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_current_time", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    }
  ]
}

El bloque intermediate_data.tool_uses es la trayectoria esperada, es decir, qué herramientas debería llamar el agente y con qué argumentos. La métrica de trayectoria compara este valor con lo que realmente sucedió durante el tiempo de ejecución.

Edita la rúbrica para calificar ambas métricas

Reemplaza tests/eval/eval_config.json por lo siguiente:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "rubric_based_final_response_quality_v1": {
      "threshold": 0.8,
      "judgeModelOptions": {"judgeModel": "gemini-flash-latest", "numSamples": 1},
      "rubrics": [
        {"rubricId": "relevance",     "rubricContent": {"textProperty": "The response directly addresses the user's query."}},
        {"rubricId": "helpfulness",   "rubricContent": {"textProperty": "The response is helpful and provides useful information."}},
        {"rubricId": "tool_grounded", "rubricContent": {"textProperty": "The response is grounded in the values returned by the tools (e.g. the exact temperature and weather condition) and does not invent details."}}
      ]
    }
  }
}

Qué hace cada línea:

tool_trajectory_avg_score: 1.0: Agrega la métrica de trayectoria con un umbral estricto de 1.0 (cada llamada a herramienta esperada debe coincidir exactamente). La puntuación se calcula de forma determinística comparando los eventos function_call reales del agente con intermediate_data.tool_uses.
rubric_based_final_response_quality_v1: Ejecuta un LLM como juez (gemini-flash-latest aquí) que califica la respuesta final según cada rúbrica en una escala de 0 a 1 y, luego, calcula el promedio. El caso se aprueba cuando el promedio cumple con threshold (0.8). La rúbrica tool_grounded le pide explícitamente al juez que penalice las respuestas que contradigan o inventen información sobre el resultado de la herramienta, lo que constituye una defensa contra la alucinación que se agrega a la verificación de la trayectoria.

🤖 Con un agente de programación

Pregúntale a tu agente:

"Ejecuta las evaluaciones de mi agente"

👤 Modo manual

agents-cli eval run --all

--all se ejecuta cada *.evalset.json en tests/eval/evalsets/. Para segmentar anuncios para uno, usa --evalset tests/eval/evalsets/basic.evalset.json.

Resultado esperado (recortado):

  ▸ uv run adk eval ./app tests/eval/evalsets/basic.evalset.json --config_file_path tests/eval/eval_config.json
INFO - google_llm.py - Sending out request, model: gemini-flash-latest, backend: GoogleLLMVariant.VERTEX_AI
INFO - local_eval_set_results_manager.py - Writing eval result to file: app/.adk/eval_history/app_basic_eval_<ts>.evalset_result.json
Using evaluation criteria: criteria={'tool_trajectory_avg_score': 1.0, 'rubric_based_final_response_quality_v1': BaseCriterion(threshold=0.8, ...)}
*********************************************************************
Eval Run Summary
basic_eval:
  Tests passed: 3
  Tests failed: 0

Los resultados por caso se escriben en app/.adk/eval_history/. Cada archivo de resultados enumera las puntuaciones por métrica para que puedas ver exactamente qué verificación se aprobó o falló.

Cómo leer un archivo de resultados

Un caso de aprobación en app/.adk/eval_history/app_basic_eval_.evalset_result.json se ve de la siguiente manera:

{
  "eval_id": "weather_san_francisco",
  "final_eval_status": 1,
  "overall_eval_metric_results": [
    {"metric_name": "tool_trajectory_avg_score",            "score": 1.0, "threshold": 1.0, "eval_status": 1},
    {"metric_name": "rubric_based_final_response_quality_v1","score": 1.0, "threshold": 0.8, "eval_status": 1}
  ]
}

Si el agente hubiera alucinado y llamado a la herramienta incorrecta (o a ninguna herramienta), tool_trajectory_avg_score disminuiría a 0.0 y el caso fallaría, incluso si el texto final se leyera de forma plausible. Esa es la propiedad que la rúbrica por sí sola no puede brindarte.

Otras métricas disponibles

El ADK incluye varios evaluadores integrados que puedes agregar a criteria:

Métrica	Qué verifica
`tool_trajectory_avg_score`	Llamadas a herramientas de coincidencia exacta en comparación con la trayectoria esperada
`rubric_based_final_response_quality_v1`	El juez de LLM en comparación con tu rúbrica (respuesta final)
`rubric_based_tool_use_quality_v1`	LLM Judge según la rúbrica (uso de herramientas)
`final_response_match_v2`	Juez de LLM: ¿La respuesta final es semánticamente equivalente a la esperada?
`response_match_score`	ROUGE-1 entre la respuesta final real y la esperada
`safety_v1`	Juez de LLM: Seguridad de la respuesta
`hallucinations_v1`	El juez del LLM: La respuesta se basa en el contexto proporcionado

9. Agrega la implementación de Agent Runtime

Agent Runtime es el entorno de ejecución administrado y sin servidores de Google Cloud para los agentes del ADK. Se encarga del escalamiento, la infraestructura y la observabilidad de forma automática.

🤖 Con un agente de programación

Pregúntale a tu agente:

"Agrega la implementación de Agent Runtime a mi proyecto"

👤 Modo manual

agents-cli scaffold enhance --deployment-target agent_runtime --yes

Resultado esperado:

Agents CLI v0.1.2
Resolved project root to: /home/user/customer-support-agent

Generating templates for comparison...
  - Original template...
  - Enhanced template...

Comparing files...

Will auto-update (unchanged by you):
  ✓ README.md
  ✓ app/app_utils/telemetry.py

Skipping (your code):
  - app/agent.py

Files to add:
  + app/agent_runtime_app.py
  + deployment_metadata.json
  + tests/integration/test_agent_runtime_app.py

Files to remove:
  - Dockerfile
  - app/fast_api_app.py
  - tests/integration/test_server_e2e.py

Dependency changes:
  + Add: google-cloud-aiplatform[evaluation,agent-engines]>=1.130.0
  + Add: protobuf>=6.31.1,<7.0.0

📦 Creating backup before modification...
Backup created: /home/user/.agents-cli/backups/customer-support-agent_20260430_001940

  Updated: 2 files
  Added: 3 files
  Removed: 3 files

✅ Enhance complete!

¿Qué cambió?

Agregadas

app/agent_runtime_app.py: Wrapper de Agent Runtime
deployment_metadata.json: Seguimiento de la implementación
Pruebas específicas de Agent Runtime

Se quitó:

Dockerfile: No es necesario (se administra Agent Runtime)
fast_api_app.py: Se reemplazó por la app de Agent Runtime

Conservado:

app/agent.py: Es el código de tu agente (sin modificar).

10. Implementa en Agent Runtime

Implementa tu agente en la infraestructura administrada de Google Cloud.

Actualiza las dependencias

uv lock

🤖 Con un agente de programación

Pregúntale a tu agente:

"Implementa mi agente en Agent Runtime en el proyecto YOUR_PROJECT_ID, región us-central1".

👤 Modo manual

agents-cli deploy --project YOUR_PROJECT_ID --region us-central1

Resultado esperado:

Using project root directory: /home/user/customer-support-agent
  📦 Auto-generated requirements: app/app_utils/.requirements.txt

    ╔═══════════════════════════════════════════════════════════╗
    ║                                                           ║
    ║   🤖 DEPLOYING AGENT TO VERTEX AI AGENT ENGINE 🤖         ║
    ║                                                           ║
    ╚═══════════════════════════════════════════════════════════╝

📋 Deployment Parameters:
  Project: YOUR_PROJECT_ID
  Location: us-central1
  Display Name: customer-support-agent
  Min Instances: 1
  Max Instances: 10
  CPU: 4
  Memory: 8Gi
  Container Concurrency: 9

🌍 Environment Variables:
  AGENT_VERSION: 0.1.0
  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: true
  GOOGLE_CLOUD_REGION: us-central1
  NUM_WORKERS: 1
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: true

INFO:root:Introspecting app.agent_runtime_app.agent_runtime via subprocess

🚀 Creating agent: customer-support-agent (this can take 5-10 minutes)...
INFO:vertexai_genai.agentengines:Using agent framework: google-adk
   Operation: projects/.../locations/us-central1/reasoningEngines/.../operations/...

[... deployment in progress for ~5–10 minutes ...]

INFO:root:Agent Runtime ID written to deployment_metadata.json

✅ Deployment successful!
Agent Runtime ID: projects/.../locations/us-central1/reasoningEngines/XXXXXXXXXXXXXXXXXX
Service Account: service-XXXXXXXXX@gcp-sa-aiplatform-re.iam.gserviceaccount.com

📊 Open Console Playground: https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/us-central1/agent-engines/XXXXXXXXXXXXXXXXXX/playground?project=YOUR_PROJECT_ID

¿Qué pasó?

Agent Runtime:

Se empaquetó tu código automáticamente
Se subió a Google Cloud
Infraestructura administrada aprovisionada (4 CPU, 8 Gi de memoria)
Ajuste de escala automático configurado (de 1 a 10 instancias)
Telemetría y observabilidad habilitadas

Tiempo de implementación: Entre 5 y 10 minutos (configuración única; las reimplementaciones posteriores son más rápidas)

11. Prueba y supervisa tu agente implementado

Tu agente ahora se ejecuta en Agent Runtime. Probémoslo y exploremos la supervisión integrada.

Prueba tu agente

Opción 1: Consola de Playground (la más sencilla)

El resultado de agents-cli deploy imprime un vínculo a Console Playground con el siguiente formato:

https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/<REGION>/agent-engines/<RUNTIME_ID>/playground?project=<PROJECT_ID>

(Agent Runtime es el nombre comercial; el recurso subyacente de GCP es un Vertex AI Agent Engine, por lo que la ruta de URL incluye vertex-ai/agents/agent-engines). Haz clic en el vínculo para realizar las siguientes acciones:

Accede a la consola de Google Cloud
Cómo ver tu agente implementado con una IU de chat interactiva
Preguntas de prueba, como "¿Cómo está el clima en San Francisco?"
Visualiza las llamadas y respuestas de herramientas en tiempo real

Console Playground es la forma más sencilla de verificar tu implementación.

Opción 2: agents-cli run –url

El mismo comando de agents-cli run que usaste de forma local también consulta los agentes implementados:

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
agents-cli run \
  --url "https://us-central1-aiplatform.googleapis.com/v1/${RUNTIME_ID}" \
  --mode adk \
  "What's the weather in San Francisco?"

--mode adk habla el protocolo SSE del ADK (el agente implementado expone :streamQuery). agents-cli adjunta automáticamente un token de acceso de Google desde tus credenciales activas de gcloud.

Opción 3: SDK de Agent Engine (Python)

Para acceder de forma programática desde Python, usa el módulo Agent Engine del SDK de Vertex AI (vertexai.agent_engines):

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# remote_agent_runtime_id from deployment_metadata.json (full resource name)
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

session = remote_agent.create_session(user_id="user-1")
for event in remote_agent.stream_query(
    user_id="user-1",
    session_id=session["id"],
    message="What's the weather in San Francisco?",
):
    print(event)

Supervisa tu agente

Agent Runtime incluye observabilidad integrada a través de las herramientas de supervisión de Google Cloud:

Cloud Trace: Seguimiento de solicitudes

Navega a Consola de Cloud > Explorador de Trace.
Selecciona tu proyecto
Filtrar intervalos por atributo service.name = customer-support-agent
Analiza un registro para ver la inferencia del modelo, las llamadas a herramientas y la latencia de extremo a extremo

Cloud Logging: Registros de la aplicación

Navega a Consola de Cloud > Explorador de registros.
Usar consulta: resource.type="aiplatform.googleapis.com/ReasoningEngine"
Agrega resource.labels.reasoning_engine_id="" al alcance de este agente
Visualiza las solicitudes, las respuestas, la ejecución de herramientas y los errores del agente

Cloud Monitoring: Métricas y paneles

Navega a Cloud Console > Explorador de métricas.
Filtrar por tipo de recurso aiplatform.googleapis.com/ReasoningEngine
Métricas útiles: request_count, request_latencies, instance_count

12. Opcional: Publica en Gemini Enterprise

Haz que tu agente esté disponible en Gemini Enterprise para tu organización.

🤖 Con un agente de programación

Pregúntale a tu agente:

"Publica mi agente en Gemini Enterprise".

👤 Modo manual

Enumera las apps de Gemini Enterprise en tu proyecto para tener un ID de app al que segmentar:

agents-cli publish gemini-enterprise --list

Luego, registra el agente implementado. El comando lee automáticamente el ID del entorno de ejecución del agente de deployment_metadata.json:

agents-cli publish gemini-enterprise \
  --gemini-enterprise-app-id "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/YOUR_APP_ID" \
  --display-name "Customer Support Agent" \
  --description "Answers weather and time questions" \
  --tool-description "Use this tool to ask the customer support agent."

Esto hace que tu agente esté disponible de las siguientes maneras:

En el mercado de agentes de Gemini Enterprise
A los usuarios de tu organización
Con administración y administración centralizadas

Para obtener más detalles, consulta la documentación sobre la publicación.

13. Limpia

Para evitar cargos, limpia los recursos que creaste.

Borra el agente

Obtén el nombre del recurso de Agent Runtime desde deployment_metadata.json:

jq -r .remote_agent_runtime_id deployment_metadata.json

Borra con el SDK de Agent Engine (Python)

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# Full resource name from deployment_metadata.json
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

# force=True also deletes any child sessions
remote_agent.delete(force=True)
print("✅ Deleted successfully")

O bien a través de la API de REST (curl):

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"

14. ¡Felicitaciones!

🎉 ¡Lo lograste! Creaste, probaste e implementaste correctamente un agente de IA desde cero.

Qué aprendiste

Dos formas de usar la CLI de Agents (con un agente de codificación o de forma manual)
Cómo crear proyectos de agentes con agents-cli scaffold
Crea agentes con herramientas personalizadas
Pruebas locales con Playground
Cómo ejecutar evaluaciones automatizadas
Implementación en Agent Runtime (infraestructura administrada)
Supervisión con Cloud Trace y Logging
Prácticas recomendadas de producción

Qué compilaste

Un agente de IA listo para producción con las siguientes características:

Comprensión del lenguaje natural (Gemini)
Integración de herramientas personalizadas
Evaluaciones de calidad
Implementación con ajuste de escala automático
Observabilidad integrada

Próximos pasos

Extiende tu agente:

Agregar más herramientas (consultas de bases de datos, llamadas a la API)
Implementa RAG con la búsqueda de vectores
Cómo agregar conversaciones de varios turnos
Habilita la comunicación A2A (de agente a agente)

Obtenga más información:

Únete a la comunidad:

Problemas de GitHub
Stack Overflow
Correo electrónico: agents-cli@google.com
Comparte lo que creaste.