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

Agent Identity te permite aprovisionar una identidad administrada para los agentes que creas e implementas en Agent Runtime en Gemini Enterprise Agent Platform con la CLI de Agent y el Kit de desarrollo de agentes (ADK). Luego, el agente implementado puede autenticarse en los servicios deGoogle Cloud y recuperar las credenciales del administrador de autenticación de Agent Identity sin administrar las credenciales de forma manual.

Antes de comenzar

  1. Habilita las APIs de Agent Identity, Agent Platform, Agent Registry y App Hub, si aún no están habilitadas.

    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 de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

  2. Asegúrate de tener el rol de 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 la identidad del agente:

  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 directorio de tu nuevo proyecto de 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 de tu 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 tu archivo de configuración agent.py para que refleje 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 que elegiste.

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

    Para usar un modelo que solo está disponible en la región global, 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 que haga referencia a la nueva subclase:

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

  6. Habilita la identidad del agente creando 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: Es el ID del proyecto de Google Cloud .

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

    La implementación puede tardar unos minutos en completarse. Cuando finalice, la CLI mostrará un mensaje de confirmación y un vínculo al entorno de pruebas de tu agente en la consola de Google Cloud .

  12. Recupera el ID de SPIFFE de tu agente (identidad del agente):

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

      Ir a Implementaciones

    2. Para copiar el ID de SPIFFE de tu agente en el 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 es 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?