Descripción general
La identidad de agente proporciona una identidad por agente que habilita un enfoque de privilegio mínimo y está vinculada al ciclo de vida del agente, lo que hace que la identidad de agente sea una entidad de seguridad 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 habilitar una administración 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 al certificado solo se puedan usar desde su entorno de ejecución confiable previsto (por ejemplo, un contenedor de Cloud Run). Esta base 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:
Crea un agente con identidad de agente: Crea un agente de modo que reciba automáticamente una identidad única cuando lo implementes en Agent Runtime.
Autoriza el acceso a las APIs de Google Cloud con la identidad del agente: Usa la identidad del agente aprovisionada para otorgarle o denegarle acceso a las herramientas, las APIs y los recursos propios de Google Cloud. Esto también incluye el acceso a otros agentes alojados en Agent Runtime con el protocolo Agent2Agent (A2A).
Registra la actividad del agente de Logging: Consulta la identidad del agente en los registros de los servicios de Google Cloud . En los flujos delegados por el usuario, los registros muestran la identidad del usuario y la del agente.
Enumera los agentes y su identidad: 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
No se pueden otorgar roles de bucket heredados
(storage.legacyBucketReader, storage.legacyBucketWriter o
storage.legacyBucketOwner) a las identidades de agentes en los buckets de Cloud Storage.
Crea un agente con identidad de agente
Puedes aprovisionar los agentes que implementas en Agent Runtime con una identidad única cuando creas tu instancia de Agent Runtime. La identidad está vinculada al ID del recurso del agente de Agent Runtime y es independiente del framework del agente que usaste para desarrollarlo.
Tienes las siguientes opciones cuando creas una identidad de agente:
Crea una instancia de Agent Runtime sin implementar el código del agente: Si quieres configurar 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 agentplatform from agentplatform import types client = agentplatform.Client( project=PROJECT_ID, location=LOCATION, http_options=dict(api_version="v1beta1") ) remote_app = client.runtimes.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, podrás agregar código de agente con
client.runtimes.update(...).Crea una instancia de Agent Runtime mientras implementas el código del agente: Si quieres aprovisionar la identidad del agente mientras implementas su código, 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éntala:
import agentplatform from agentplatform import types from agentplatform.frameworks import AdkApp # Initialize the Agent Platform client with v1beta1 API for agent identity support client = agentplatform.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.runtimes.create( agent=app, config={ "display_name": "running-agent-with-identity", "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": ["google-cloud-agentplatform[adk,runtimes]"], "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 del 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. Con el siguiente comando, se implementa tu agente:
agents-cli deploy --agent-identityImplementa agentes con la identidad del agente con la implementación de ADK: Configura tu agente con 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 certificada por el sistema (un identificador de 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 para ti 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.proj-PROJECT_NUMBER.system.id.goog.
NAMESPACE: Es la ruta de acceso inmutable del recurso del agente.
AGENT_NAME: Es el
agent-reasoning-engine-idinmutable.
La identidad del agente se basa en SPIFFE. También aprovisionamos y administramos de forma automática 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 a modelos, sesiones, memorias y entornos 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 de Google Cloud con la identidad del agente
Una vez que creas 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 a 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 .
Otorgar acceso a un agente
Otorgar permisos de IAM a la identidad del agente
Recomendamos los siguientes roles:
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 .roles/secretmanager.secretAccessor: Otorga al agente acceso a los secretos en Secret Manager. Si haces referencia a secretos como variables de entorno, también debes otorgarroles/secretmanager.secretAccessoral agente de servicio de Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) para que pueda recuperar los valores de los secretos durante la implementación.
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 adelante para ver 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:
RESOURCE_TYPE: Es el tipo de recurso (por ejemplo,
projectsoorganizations).RESOURCE_ID: Es el ID del recurso al que deseas otorgar acceso.
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 el entorno de ejecución.
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 Información sobre 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 .
Otorga acceso para la delegación de agente a agente (A2A)
Cuando diseñas un sistema multiagente en el que un agente superior invoca un agente secundario remoto registrado en el Registro de agentes, la identidad del agente superior debe tener permisos para descubrir el agente secundario en el Registro de agentes y para invocar su extremo.
Para garantizar que la identidad del agente superior tenga los permisos necesarios para descubrir e invocar un agente secundario remoto, pídele a tu administrador que otorgue los siguientes roles de IAM a la identidad del agente superior:
-
Permite que el agente superior busque el extremo del agente secundario en el entorno de ejecución:
Visualizador de la API de Agent Registry (
roles/agentregistry.viewer) en el proyecto superior o el recurso de registro -
Permite que el agente superior envíe mensajes al agente secundario:
Usuario de Agent Platform (
roles/aiplatform.user) en el recurso del motor de razonamiento del agente secundario de destino
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Es posible que tu administrador también pueda otorgar a la identidad del agente superior los permisos necesarios a través de roles personalizados o de otros roles predefinidos.
Por ejemplo, para otorgar el rol roles/agentregistry.viewer en el proyecto, puedes
usar el siguiente comando de Google Cloud CLI:
gcloud projects add-iam-policy-binding PROJECT_NUMBER \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
--role="roles/agentregistry.viewer"
Reemplaza lo siguiente:
ORGANIZATION_ID: Es el ID de tu organización.PROJECT_NUMBER: Es el número de tu proyecto.LOCATION: Es la región en la que se implementa tu agente superior.PARENT_AGENT_ENGINE_ID: Es el ID del recurso de la instancia de Agent Runtime de tu agente superior.
Cómo otorgar 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, 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.proj-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 los 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 estos 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/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"
Otorga acceso para las llamadas de agente a agente (A2A)
Si un agente (agente A) necesita invocar a otro agente (agente B), no otorgues permisos para todo el proyecto. En su lugar, otorga un rol personalizado que solo contenga aiplatform.reasoningEngines.query y aiplatform.reasoningEngines.get, vinculado a la ruta de acceso del recurso del agente B.
Crea un rol personalizado
agentInvokercon los permisos necesarios:gcloud iam roles create agentInvoker --project=PROJECT_ID \ --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \ --stage=GAVincula el rol personalizado al recurso del agente B para otorgar acceso a la identidad del agente A:
gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \ --region=LOCATION \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \ --role="projects/PROJECT_ID/roles/agentInvoker"Para evitar que las identidades de los agentes realicen operaciones de administración sensibles en otros agentes, crea una política de denegación de IAM para
reasoningEngines.create,.deletey.update:deniedPrincipals: - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/* deniedPermissions: - aiplatform.googleapis.com/reasoningEngines.create - aiplatform.googleapis.com/reasoningEngines.delete - aiplatform.googleapis.com/reasoningEngines.update
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 las principales.
Denegar 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 entidad para restringir los recursos a los que puede acceder el agente, independientemente 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
Guía de CI/CD y automatización
Las canalizaciones de implementación automatizadas que borran y vuelven a crear agentes (como
las implementaciones azul-verde, los entornos de pruebas efímeros o los flujos de trabajo de Terraform)
pueden experimentar una pérdida de acceso al entorno de ejecución silenciosa. Debido a que cada nueva implementación crea un
recurso reasoningEngines nuevo con un ID único, el agente recibe un identificador
principal nuevo. Los permisos de IAM otorgados al
principal anterior no se heredan al principal nuevo.
Para administrar los permisos en las canalizaciones automatizadas, usa las siguientes estrategias:
Recupera el nuevo ID de principal de forma dinámica: Captura el valor
spec.effectiveIdentityde la respuesta de implementación o consulta la API de REST después de la implementación para obtener la identidad activa del agente. Aplica las vinculaciones de IAM necesarias a esta nueva principal como un paso posterior a la implementación.Por ejemplo, puedes consultar la identidad activa con
gcloudcon el siguiente comando:gcloud ai reasoning-engines describe RESOURCE_ID \ --project=PROJECT_ID \ --location=LOCATION \ --format="value(spec.effectiveIdentity)"En Terraform, puedes construir de forma dinámica la principal de identidad del agente a partir del ID del recurso
google_vertex_ai_reasoning_engineimplementado y hacer referencia a ella en las vinculaciones de IAM:resource "google_vertex_ai_reasoning_engine" "reasoning_engine" { provider = google-beta project = var.project_id region = var.region display_name = var.display_name description = var.agent_description spec { agent_framework = "google-adk" identity_type = "AGENT_IDENTITY" source_code_spec { inline_source { source_archive = filebase64(data.archive_file.agent_tarball.output_path) } python_spec { entrypoint_module = var.agent_python_spec.entrypoint_module entrypoint_object = var.agent_python_spec.entrypoint_object requirements_file = var.agent_python_spec.requirements_path version = var.agent_python_spec.version } } deployment_spec { env { name = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY" value = "true" } env { name = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT" value = "true" } } } } locals { agent_resource_id = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1) agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}" }Usa
principalSetscon alcance de proyecto para los permisos de referencia: Debido a que las vinculaciones deprincipalSetse orientan a todos los agentes de un proyecto, sobreviven a la eliminación y recreación de agentes. Otorga roles comunes y no sensibles (como el uso de servicios, el registro y la inferencia de modelos generales) alprincipalSetde todo el proyecto en lugar de a los principales de agentes individuales. Limita las vinculaciones individuales deprincipal://a fuentes de datos muy sensibles.
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 con su propia autoridad, los registros solo muestran la identidad del agente.
Enumera los agentes y sus identidades
Puedes ver la lista de identidades de tus agentes en Agent Runtime con la consola de Google Cloud y la línea de comandos.
Console
- En la consola de Google Cloud , ve a la página Implementaciones de Agent Platform.
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.
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 asociada con la
instancia de Agent Runtime.
Inhabilitar el Acceso adaptado al contexto (CAA)
De forma predeterminada, intentar usar un token de acceso fuera de su entorno de ejecución de Agent Runtime previsto genera 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 de CAA predeterminada. No se recomienda esta acción, ya que deja al agente vulnerable al robo de credenciales.
Inhabilita la política predeterminada de Acceso adaptado al contexto (CAA) configurando la siguiente variable de entorno cuando creas tu instancia de Agent Runtime:
config={
"env_vars": {
"GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
}
}
¿Qué sigue?
Administrar agentes implementados
Aprende a administrar agentes que se implementaron en el entorno de ejecución administrado de Agent Platform.