Usa la identidad del agente con Vertex AI Agent Engine

En esta página, se describe cómo usar la identidad del agente de Identity and Access Management (IAM) para proporcionar funciones de seguridad y administración de acceso cuando se usan agentes en el entorno de ejecución de Vertex AI Agent Engine.

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.

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

Limitaciones

Ten en cuenta las siguientes limitaciones cuando planifiques tu proyecto:

  • No se pueden otorgar roles de Legacy Bucket (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) a identidades de agentes en buckets de Cloud Storage.

  • Te recomendamos que uses la identidad del agente solo en entornos de prueba.

Crea un agente con identidad de agente

Puedes aprovisionar los agentes que implementes en Agent Engine de Vertex AI con una identidad única cuando crees tu instancia de Agent Engine. La identidad está vinculada al ID del recurso del agente de Vertex AI Agent Engine 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 Engine 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 Engine 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 Engine con la identidad del agente, puedes agregar código del agente con agent_engine.update(...).

  • Crea una instancia de Agent Engine 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 Vertex AI para Python y la marca identity_type=AGENT_IDENTITY:

    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(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

    En el ejemplo anterior, BUCKET_NAME es el nombre de tu bucket de Cloud Storage.

La instancia de Agent Engine 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 aprovisiona un dominio de confianza cuando habilitas la API de Vertex AI:

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

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

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

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 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 Vertex AI.

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

  # 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 Vertex AI Agent Engine.

  • AGENT_ENGINE_ID: Es el ID de recurso de tu instancia de Agent Engine.

  • 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 Google Cloud usan automáticamente la identidad del agente para realizar la autenticación en los recursos deGoogle Cloud .

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.

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

Accede a servicios de terceros con autoridad delegada a través de OAuth

La identidad del agente puede permitir que este acceda a servicios de terceros en tu nombre integrándose con Secret Manager.

Para configurar la integración con Secret Manager, primero debes almacenar las credenciales auxiliares (ID de cliente o secreto del cliente) para acceder a los servicios de terceros en Secret Manager (en el proyecto del consumidor en el que se administra el ciclo de vida del agente) siguiendo estos pasos:

  1. Crea un contenedor nuevo en Secret Manager.

  2. Obtén el ID de cliente o el secreto del cliente del proveedor de la app de terceros.

  3. Agrega el ID de cliente o el secreto del cliente a Secret Manager.

  4. Restringe el acceso a estas credenciales según el ID del agente (un identificador principal):

    # Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret "gcp-client-secret-1a2b3c4d"

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

Una vez que se almacena el secreto, el agente puede acceder a estas credenciales durante el tiempo de ejecución con su identificador principal y la biblioteca de autenticaciónGoogle Cloud estándar automáticamente como parte de las credenciales predeterminadas de la aplicación.

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:

      # Application default credential automatically gets token from MDS using agent identity
      agent_identity_credentials = default()

       # Create the Secret Manager client.
       client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

       # Build the resource name of the secret version.
       name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

       # Access the secret version.
       response = client.access_secret_version(request={"name": name})

       # Decode the payload to get the secret string.
       secret_value = response.payload.data.decode("UTF-8")
       return secret_value

Con el ID de cliente y el secreto del cliente, ahora puedes compilar tu herramienta y configurar la autenticación basada en OAuth.

En el siguiente ejemplo, se usa un agente desarrollado por el Kit de desarrollo de agentes (ADK). La autenticación basada en OAuth se incluye en los métodos authenticationScheme y authCredential como parte de la construcción de la herramienta:

import os

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
   authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
   token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
   scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
 auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
 oauth2=OAuth2Auth(
   client_id=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_id'),
   client_secret=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_secret'),
 )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---

with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

Durante el tiempo de ejecución, sucede lo siguiente (si usas el ADK de forma local a través de la Web del ADK, los pasos se automatizan dentro de la Web del ADK y el backend del ADK):

  1. Accedes al agente, y este decide que debe invocar la herramienta (por ejemplo, Slack).

  2. Las herramientas programadas dentro del ADK (con auth_scheme y auth_credential) devuelven un objeto authConfig al frontend (que incluye el URI de redireccionamiento y el ID de cliente).

  3. El frontend analiza el objeto authConfig y se te redirecciona a la página de autorización de terceros. Después de acceder, se te redirecciona al frontend del agente y se envía el código de autorización al backend del ADK.

  4. El backend usa el código de autorización para obtener un token de acceso para el servicio de terceros y continúa ejecutando la herramienta.

Si implementas un agente de ADK en el entorno de ejecución de Vertex AI Agent Engine, debes compilar un frontend personalizado y migrar la autenticación web del ADK o el código de redireccionamiento a tu frontend para realizar la misma integración de OAuth.

Accede a servicios de terceros con claves de API

La identidad del agente puede permitirle acceder a servicios de terceros y actuar en tu nombre con claves de API. Primero, debes almacenar las claves de API para acceder a los servicios de terceros en Secret Manager y, luego, recuperar estas credenciales de Secret Manager.

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

WEATHER_DOT_COM_API_KEY = access_secret(project_id: 'foo', secret_id: 'weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
   "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
   spec_str="...",
   spec_str_type="yaml",
   auth_scheme=auth_scheme,
   auth_credential=auth_credential,
)

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 Vertex AI Agent Engine con la consola y la línea de comandos. Google Cloud

Console

  1. En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.

    Ir a Agent Engine

    En la lista, aparecen los agentes implementados que forman parte del proyecto seleccionado. 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 Engine 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 Engine 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 Engine.

¿Qué sigue?