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 privilegio mínimo para la administración de accesos. En este documento, se explica cómo crear agentes con identidades de agentes, autorizar el acceso a las APIs deGoogle Cloud 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 privilegio mínimo 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 la identidad del agente de IAM admiten 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 de confianza previsto (por ejemplo, un contenedor de Cloud Run). Este concepto básico de seguridad hace que las credenciales robadas no se puedan volver a usar, lo que protege contra el robo de credenciales y la apropiación de cuentas (ATO).

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

Limitaciones

No se pueden otorgar roles de bucket heredado (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) a identidades de agentes en 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 del recurso del agente del entorno de ejecución del agente y es independiente del framework de agentes que usaste para desarrollar el agente.

Cuando creas una identidad del agente, tienes las siguientes opciones:

  • Crea una instancia de Agent Runtime sin implementar código del agente: Si deseas configurar políticas de IAM antes de implementar el agente, puedes crear una identidad del 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={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

    Una vez que crees la instancia de Agent Runtime con la identidad del agente, puedes agregar código del agente con agent_engine.update(...).

  • Crea una instancia de Agent Runtime mientras implementas el código del 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}")

    En el ejemplo anterior, 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 básicos para la supervisión. El siguiente comando implementa tu agente:

    agents-cli deploy --agent-identity

  • Implementa agentes con la identidad del agente usando ADK deploy: 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 de solo lectura y certificada por el sistema (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 te 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 inmutable del recurso del agente.

  • AGENT_NAME: Es 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 zonas de pruebas (versión preliminar).

Las identidades de los agentes incluyen roles predeterminados de roles/aiplatform.agentContextEditor y roles/aiplatform.agentDefaultAccess 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 APIs y los servicios con la identidad del agente Google Cloud

Una vez que crees un agente con identidad de agente, puedes otorgarle o denegarle acceso a las APIs y los servicios de Google Cloud con las siguientes políticas de IAM:

  • Políticas de permisos: Otorgan acceso de un agente a un recurso de Google Cloud .

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

Cómo otorgar acceso a un agente

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

  • roles/aiplatform.expressUser: Otorga acceso a la ejecución de inferencias, sesiones y memoria.

  • roles/serviceusage.serviceUsageConsumer: Otorga permiso al agente para usar la cuota del proyecto y el SDK de Agent Platform.

  • roles/browser: Otorga acceso a las funciones básicas de Google Cloud .

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

Crea una política de permisos de IAM para otorgarle 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: Tu región. Consulta las regiones admitidas para 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 deGoogle Cloud .

Cómo otorgar acceso a varios agentes

Puedes otorgar un rol de IAM a todos los agentes de Agent Runtime en un proyecto específico 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, haz lo siguiente:

# 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, haz lo siguiente:

# 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 cuotas, registro o acceso a modelos, a todos los agentes del proyecto para simplificar las implementaciones. Luego, otorga permisos específicos y limitados a los agentes individuales para los permisos más sensibles, como el acceso a los datos. Se pueden otorgar estos permisos en cualquier momento después del primer uso de la función de identidad del agente en una organización o 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, haz lo siguiente:

# 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"

Cómo denegar 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 los registros de qué agente y usuarios accedieron a un recurso de Google Cloud .

  • 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 identidades de tu agente en el entorno de ejecución de agentes con la consola de Google Cloud y la línea de comandos.

Console

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

    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 según la columna que especifiques.

  2. Para cada agente, la identidad se indica 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 nombre del agente de servicio o de la cuenta de servicio asociados con la instancia de Agent Runtime.

Cómo inhabilitar el Acceso adaptado al contexto (CAA)

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

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

En casos excepcionales, como requisitos específicos de uso compartido de tokens entre agentes, puedes inhabilitar la política de CAA predeterminada. No se recomienda realizar esta acción, ya que deja al agente vulnerable al robo de credenciales.

Para inhabilitar la política predeterminada de Acceso adaptado al contexto (CAA), configura 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

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

Guía

Usar un agente con el entorno de ejecución de Agent Platform