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 la API de Agent Identity.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

  2. Asegúrate de tener el rol de usuario de Vertex AI (roles/aiplatform.user) en tu proyecto.

Crea e implementa el agente

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

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

    pip install google-agents-cli uv
agents-cli setup

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

    agents-cli create AGENT_PROJECT --prototype --yes

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

    Con este comando, se genera la siguiente estructura de directorio del proyecto:

    (Nota: El siguiente árbol destaca los archivos de configuración pertinentes y es posible que no represente todos los archivos de tu directorio).

    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):

    mv app AGENT_NAME

    Luego, 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",
)

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

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

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

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

  6. 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

    Verifica 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.
    2. En la interfaz de chat, envía una pregunta de prueba para verificar la respuesta.

  7. 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 en la que deseas implementar el agente (por ejemplo, us-west1).

    Cuando se complete la implementación, la CLI mostrará un mensaje de confirmación y un vínculo al entorno de pruebas de tu agente en la Google Cloud consola.

  8. Recupera el ID de SPIFFE de tu agente (Agent Identity) desde la Google Cloud consola:

    1. En la Google Cloud consola, ve a la Agent Platform página.
    2. Haz clic en la pestaña Implementaciones y selecciona tu agente implementado.
    3. Copia el valor de Agent Identity (por ejemplo, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

¿Qué sigue?