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 la identidad del agente habilitada.

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

Antes de comenzar

  1. Habilita la API de Agent Identity Connector.

    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 directorio del nuevo proyecto del agente (por ejemplo, maps-agent).

    Este comando 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 de tu 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 la identidad del agente, 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 instrucción 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: Es el ID de tu proyecto de Google Cloud .
    • LOCATION: Es 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 Playground del agente en la consola de Google Cloud .

  8. Recupera el ID de SPIFFE (identidad del agente) de tu agente desde la consola deGoogle Cloud :

    1. En la consola de Google Cloud , ve a la página Agent Platform.
    2. Haz clic en la pestaña Deployments y selecciona el 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?