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 agente, autorizar el acceso a las APIs deGoogle Cloud y administrar credenciales para servicios de terceros.

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:

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-identity
    
  • Implementa 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-id inmutable.

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 otorgar roles/secretmanager.secretAccessor al 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, projects o organizations).

  • 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.

  1. Crea un rol personalizado agentInvoker con los permisos necesarios:

    gcloud iam roles create agentInvoker --project=PROJECT_ID \
      --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
      --stage=GA
    
  2. Vincula 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"
    
  3. 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, .delete y .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.effectiveIdentity de 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 gcloud con 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_engine implementado 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 principalSets con alcance de proyecto para los permisos de referencia: Debido a que las vinculaciones de principalSet se 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) al principalSet de todo el proyecto en lugar de a los principales de agentes individuales. Limita las vinculaciones individuales de principal:// 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

  1. En la consola de Google Cloud , 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 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 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?

Guía

Aprende a administrar agentes que se implementaron en el entorno de ejecución administrado de Agent Platform.

Guía

Usar un agente con Agent Platform Runtime