Usa Agent Identity con Agent Runtime

El uso de la identidad del agente en Agent Runtime proporciona una identidad segura por agente que permite un enfoque de mínimo privilegio para la administración de acceso. En este documento se explica cómo crear agentes con identidades de agente, autorizar el acceso a las Google Cloud APIs y administrar las credenciales de los servicios de terceros.

Descripción general

La identidad del agente proporciona una identidad por agente que permite un enfoque de mínimo privilegio y está vinculada al ciclo de vida del agente, lo que hace que la identidad del agente sea una principal más segura que las cuentas de servicio. Los controles de administración de acceso existentes a través de IAM admiten la identidad del agente para permitir una gobernanza sólida.

Las credenciales de identidad del agente se protegen de forma predeterminada a través de una política de Acceso adaptado al contexto (CAA) administrada por Google. Esta política aplica la vinculación de mTLS para garantizar que las credenciales del agente en forma de tokens vinculados a certificados solo se puedan usar desde su entorno de ejecución confiable y previsto (por ejemplo, un contenedor de Cloud Run ). Esta línea de base de seguridad hace que las credenciales robadas no se puedan reproducir, lo que protege contra el robo de credenciales y la apropiación de cuentas (ATO).

En esta página, se abordan los siguientes temas:

Crear un agente con identidad de agente: Crea un agente de modo que reciba automáticamente una identidad única cuando lo implementes en Agent Runtime.
Autorizar el acceso a las Google Cloud APIs con la identidad del agente: Usa la identidad del agente aprovisionada para otorgar o denegar el acceso del agente a las Google Cloud's herramientas, las APIs y los recursos de primera entidad de. Esto también incluye el acceso a otros agentes alojados en Agent Runtime con el protocolo Agent2Agent (A2A).
Registrar la actividad del agente: Consulta la identidad del agente en los registros de los Google Cloud servicios. En el caso de los flujos delegados por el usuario, los registros muestran la identidad del usuario y la del agente.
**Enumerar agentes y la identidad del agente**: Consulta la lista de tus agentes y sus identidades en Agent Runtime.
Inhabilitar el Acceso adaptado al contexto (no recomendado): Inhabilita la política predeterminada de Acceso adaptado al contexto (CAA).

Limitaciones

Las identidades de agente no pueden recibir roles de bucket heredado (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) en los buckets de Cloud Storage.

Crea un agente con identidad de agente

Puedes aprovisionar los agentes que implementes en Agent Runtime con una identidad única cuando crees tu instancia de Agent Runtime. La identidad está vinculada al ID de recurso del agente de Agent Runtime y es independiente del framework de agente que usaste para desarrollar el agente.

Tienes las siguientes opciones cuando creas una identidad de agente:

Crea una instancia de Agent Runtime sin implementar código de agente: Si deseas configurar las políticas de IAM antes de implementar el agente, puedes crear una identidad de agente sin implementar el código del agente. Para ello, crea una instancia de Agent Runtime solo con el campo identity_type:
```
import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={"identity_type": types.IdentityType.AGENT_IDENTITY}
)
```
Una vez que crees la instancia de Agent Runtime con la identidad del agente, puedes agregar código de agente con agent_engine.update(...).

Crea una instancia de Agent Runtime mientras implementas código de agente: Si deseas aprovisionar la identidad del agente mientras implementas el código del agente, usa el SDK de Agent Platform para Python y la marca identity_type=AGENT_IDENTITY.

Define el agente en tu framework preferido:

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

Luego, impleméntalo:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

donde BUCKET_NAME es el nombre de tu bucket de Cloud Storage.

Implementa agentes con la CLI de Agents: La CLI de Agents es ideal para estudiantes, creación de prototipos y pruebas rápidas, ya que ofrece una solución de implementación rápida con recursos fundamentales para la supervisión. El siguiente comando implementa tu agente:
```
agents-cli deploy --agent-identity
```
Implementa agentes con identidad de agente mediante la implementación del ADK: Configura tu agente con el ADK. Antes de ejecutar adk deploy, ejecuta los siguientes comandos en la carpeta de tu agente para agregar un archivo de configuración con la identidad del agente.
```
# Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
```

La instancia de Agent Runtime se crea con una identidad de agente atestiguada por el sistema y de solo lectura (un identificador principal):

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

Las siguientes partes se aprovisionan automáticamente como parte de la identidad del agente:

TRUST_DOMAIN: Se aprovisiona un dominio de confianza cuando habilitas la API de Agent Platform:
- Si tienes una organización, el dominio de confianza se crea a nivel de la organización con el formato agents.global.org-ORGANIZATION_ID.system.id.goog.
- Si tu proyecto no tiene una organización, se crea un dominio de confianza a nivel del proyecto con el formato agents.global.project-PROJECT_NUMBER.system.id.goog.
NAMESPACE: Es la ruta de acceso de recurso inmutable del agente.
AGENT_NAME: El agent-reasoning-engine-id inmutable.

La identidad del agente se basa en SPIFFE. También aprovisionamos y administramos automáticamente un certificado x509 en el agente con la misma identidad para la autenticación segura. De forma predeterminada, el agente obtiene acceso a sus propios registros, métricas, acceso al modelo, sesiones, memorias y entornos de pruebas (versión preliminar).

Las identidades de agente incluyen los roles roles/aiplatform.agentContextEditor y roles/aiplatform.agentDefaultAccess predeterminados para que los agentes tengan permisos básicos para operar.

Puedes ver la identidad a través de la consola y la API de Agent Runtime Google Cloud .

Accede a las Google Cloud APIs y los servicios con la identidad del agente

Una vez que creas un agente con identidad de agente, puedes otorgar o denegar el acceso del agente a las Google Cloud APIs y los servicios con las siguientes políticas de IAM:

Políticas de permisos: Otorga acceso de un agente a un Google Cloud recurso.
Políticas de denegación: Deniega el acceso de un agente a un Google Cloud recurso.

Otorga acceso a un agente

Otorga permisos de IAM a la identidad del agente. Recomendamos los siguientes roles:

roles/aiplatform.expressUser: Otorga acceso a la ejecución de inferencias, sesiones y memoria.
roles/serviceusage.serviceUsageConsumer: Otorga al agente permiso para usar la cuota del proyecto y el SDK de Agent Platform.
roles/browser: Otorga acceso a las funcionalidades básicas. Google Cloud

Es posible que se necesiten permisos adicionales si usas registros, métricas y el registro de la API de Cloud, y para cualquier otro recurso que desees exponer a tu agente. Consulta más adelante para obtener más ejemplos.

Crea una política de permisos de IAM para otorgar un rol de IAM a un agente:

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

Reemplaza lo siguiente:

ORGANIZATION_ID: Es el ID de tu organización.
PROJECT_NUMBER: Es el número de tu proyecto.
LOCATION: Es tu región. Consulta las regiones compatibles con Runtime.
AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Runtime.
ROLE_NAME es el nombre del rol que deseas otorgar. Por ejemplo, roles/vision.user. Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

Una vez que se configura IAM, las credenciales predeterminadas de la aplicación del SDK de Agent Platform usan automáticamente la identidad del agente para realizar la autenticación en los recursos.Google Cloud

Otorga acceso a varios agentes

Puedes otorgar un rol de IAM a todos los agentes de Agent Runtime en un proyecto en particular o en toda una organización.

Para otorgar un rol a todos los agentes de Agent Runtime en un proyecto, usa uno de los siguientes comandos.

Si tu proyecto pertenece a una organización, usa este comando:

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Si tu proyecto no pertenece a una organización, usa este comando:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Puede ser más fácil otorgar permisos comunes, como cuota, registro o acceso a modelos, a todos los agentes del proyecto para simplificar las implementaciones. Luego, otorga permisos específicos y limitados a agentes individuales para permisos más sensibles, como el acceso a los datos. Es posible otorgar esos permisos en cualquier momento después del primer uso de la función de identidad del agente dentro de una organización o un proyecto, por lo que se puede realizar antes de la implementación del agente.

Por ejemplo, los siguientes comandos otorgan roles básicos a todos los agentes de un proyecto:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/aiplatform.expressUser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

Para otorgar un rol a todos los agentes de Agent Runtime en una organización, usa este comando:

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

Deniega el acceso a un agente

Para denegar el acceso de un agente a los recursos, puedes usar la política de denegación de IAM o configurar una política de límite de acceso de la principal.

Deniega el acceso del agente a ciertos recursos con la política de denegación de IAM.

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

Configura el límite de acceso de la principal para limitar los recursos a los que puede acceder el agente, a pesar de otros permisos que pueda tener:

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

Registra la actividad del agente

Si habilitas Cloud Logging, puedes ver registros de los agentes y usuarios que accedieron a un Google Cloud recurso.

Cuando el agente actúa en nombre de un usuario, los registros muestran las identidades del agente y del usuario.
Cuando el agente actúa por su propia autoridad, los registros solo muestran la identidad del agente.

Enumera los agentes y sus identidades

Puedes ver la lista de las identidades de tus agentes en Agent Runtime con la Google Cloud consola y la línea de comandos.

Console

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

Ir a Implementaciones

Los agentes implementados que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista por la columna especificada.
Para cada agente, la identidad del agente aparece en la columna Identidad.

API de REST

Puedes recuperar la identidad del agente cuando obtienes una instancia de Agent Runtime con la API de REST.

La respuesta incluye la identidad del agente en el siguiente formato:

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

En el caso de las instancias de Agent Runtime que no usan la identidad del agente, el campo effectiveIdentity contiene el agente de servicio o el nombre de la cuenta de servicio asociado con la instancia de Agent Runtime.

Inhabilita el Acceso adaptado al contexto (CAA)

De forma predeterminada, si intentas usar un token de acceso fuera de su entorno de ejecución de Agent Runtime previsto, se produce el siguiente error:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

En casos extremos, como requisitos específicos de uso compartido de tokens entre agentes, puedes inhabilitar la política predeterminada de CAA. Esta acción no se recomienda, ya que deja a un agente vulnerable al robo de credenciales.

Para inhabilitar la política predeterminada de Acceso adaptado al contexto (CAA), establece la siguiente variable de entorno cuando crees tu instancia de Agent Runtime:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

¿Qué sigue?

Guía

Administra los agentes implementados

Obtén información para administrar los agentes que se implementaron en el entorno de ejecución administrado de Agent Platform.