Crea e implementa un agente con la CLI de Agent y la identidad del agente

En esta guía, se muestra cómo crear e implementar un agente en Agent Runtime en Gemini Enterprise Agent Platform con Agent Identity habilitado.

Agent Identity asigna una identidad SPIFFE segura a tu agente implementado. El agente usa esta identidad para autenticarse en los Google Cloud servicios y recuperar credenciales del administrador de autenticación de Agent Identity.

Antes de comenzar

  1. Habilita las APIs de Agent Identity, Agent Platform, Agent Registry y App Hub.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar las API

  2. Asegúrate de tener el rol Usuario de Agent Platform (roles/aiplatform.user) en tu proyecto.

Crea e implementa el agente

Crea un agente de muestra con google-agents-cli y, luego, impleméntalo con Agent Identity:

  1. Instala uv y, luego, ejecuta la configuración de google-agents-cli:

    pip install uv
uvx google-agents-cli setup

  2. Crea un proyecto de agente con la plantilla de prototipo:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Reemplaza AGENT_PROJECT por el nombre del nuevo directorio del proyecto del agente (por ejemplo, maps-agent).

    Este comando genera la siguiente estructura de directorio del proyecto:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. Cambia el nombre de la carpeta de la aplicación predeterminada (app) para que coincida con el nombre del agente (AGENT_NAME, por ejemplo, maps_agent). Los nombres de los agentes deben ser un identificador de Python válido: deben comenzar con una letra y contener solo letras, números y guiones bajos.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Actualiza el archivo de configuración agent.py para reflejar el nombre nuevo:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. Elige un modelo para usar, según su disponibilidad regional. Actualiza el valor de MODEL en agent.py para que coincida con el modelo elegido.

    Solución alternativa para los modelos que solo están disponibles en la global región

    Para usar un modelo que solo está disponible en la global región, debes modificar agent.py para que tu agente pueda acceder a él.

    1. Agrega las siguientes importaciones:

      from functools import cached_property
from google.genai import Client

    2. Agrega la siguiente subclase después de las importaciones:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Busca el siguiente código:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Cámbialo para hacer referencia a la subclase nueva:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Para habilitar Agent Identity, crea un archivo de configuración:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. Crea un archivo requirements.txt para las dependencias de implementación:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Verifica la estructura del directorio del proyecto:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. Prueba tu agente de forma local:

    uv run adk web . --port 8501 --reload_agents

    Para validar tu agente, haz lo siguiente:

    1. Ve a http://localhost:8501. Como alternativa, si usas Cloud Shell, haz clic en el vínculo que proporciona el resultado del servidor web.

    2. En la interfaz de chat, envía una instrucción de prueba para verificar la respuesta.

  10. Finaliza el servidor con CTRL+C.

  11. Implementa tu agente en Google Cloud:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Reemplaza lo siguiente:

    • PROJECT_ID: Tu Google Cloud proyecto ID.

    • LOCATION: La región admitida en la que deseas implementar el agente (por ejemplo, us-west1).

    La implementación puede tardar unos minutos en completarse. Una vez que finaliza, la CLI genera un mensaje de confirmación y un vínculo al entorno de pruebas de tu agente en la Google Cloud consola.

  12. Recupera el ID de SPIFFE de tu agente (Agent Identity):

    1. En la Google Cloud consola, ve a la página Implementaciones.

      Ir a Implementaciones

    2. Para copiar el ID de SPIFFE de tu agente al portapapeles, busca la fila en la que se encuentra el agente implementado y, en la columna Identidad de esa fila, haz clic en Copiar al portapapeles. La identidad se ve similar a la siguiente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

¿Qué sigue?