Usar la identidad del agente con Vertex AI Agent Engine

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta página se describe cómo usar la identidad del agente de Gestión de Identidades y Accesos (IAM) para proporcionar funciones de seguridad y gestión de accesos al usar agentes en el tiempo de ejecución de Vertex AI Agent Engine.

Informació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 convierte a la identidad del agente en una entidad más segura que las cuentas de servicio. Los controles de gestión de acceso actuales a través de la gestión de identidades y accesos admiten la identidad de los agentes para habilitar una gobernanza sólida.

En esta página se tratan los siguientes temas:

• Crear un agente con identidad de agente: crea un agente de forma que reciba automáticamente una identidad única cuando lo despliegues en el tiempo de ejecución de Vertex AI Agent Engine.

• Autorizar el acceso a las APIs mediante la identidad del agente: Google Cloud usa la identidad del agente aprovisionada para conceder o denegar el acceso del agente a las herramientas, las APIs y los recursos propios de Google Cloud. Esto también incluye el acceso a otros agentes alojados en Vertex AI Agent Engine mediante el protocolo Agent2Agent (A2A).

• Acceder a servicios de terceros mediante autoridad delegada con OAuth: configura la autenticación delegada por el usuario en herramientas propias y de terceros con OAuth para que el agente pueda realizar tareas en tu nombre.

• Acceder a servicios de terceros mediante claves de API: conéctate a servicios de terceros mediante claves de API que se almacenan de forma segura y están disponibles durante el tiempo de ejecución.

• Registrar la actividad del agente: consulta la identidad del agente en los registros de los servicios de Google Cloud . En los flujos delegados por el usuario, los registros muestran tanto la identidad del usuario como la del agente.

• List agents and agent identity (Listar agentes e identidades de agentes): consulta la lista de tus agentes y sus identidades en Vertex AI Agent Engine.

Limitaciones

Ten en cuenta las siguientes limitaciones al planificar tu proyecto:

• No se pueden asignar roles de segmento antiguos (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) a identidades de agente en segmentos de Cloud Storage.

• Recomendamos usar la identidad del agente solo en entornos de prueba.

Crear un agente con identidad de agente

Puedes aprovisionar los agentes que despliegues en Vertex AI Agent Engine con una identidad única al crear tu instancia de Agent Engine. La identidad está vinculada al ID de recurso del agente de Vertex AI Agent Engine y es independiente del framework de agente que hayas usado para desarrollar el agente.

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

• Crear una instancia de Agent Engine sin desplegar código de agente: si quieres configurar políticas de IAM antes de desplegar el agente, puedes crear una identidad de agente sin desplegar el código del agente. Para ello, crea una instancia de Agent Engine con solo 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 hayas creado la instancia de Agent Engine con la identidad del agente, podrás añadir código de agente con agent_engine.update(...).

• Crea una instancia de Agent Engine al desplegar el código del agente: si quieres aprovisionar la identidad del agente al desplegar 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",
        },
  )
  

  donde BUCKET_NAME es el nombre de tu segmento 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 de entidad 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 te proporcionan automáticamente como parte de la identidad del agente:

• TRUST_DOMAIN: se te proporciona 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 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 de proyecto con el formato agents.global.project-PROJECT_NUMBER.system.id.goog.

• NAMESPACE: ruta de recurso inmutable del agente.

• AGENT_NAME: el inmutable agent-reasoning-engine-id.

La identidad del agente se basa en SPIFFE. También aprovisionamos y gestionamos automáticamente un certificado x509 en el agente con la misma identidad para una autenticación segura.

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

Nota: Si no se configura la marca de identidad, la instancia de Agent Engine seguirá usando cuentas de servicio. De esta forma, se garantiza la retrocompatibilidad si ya has implementado despliegues basados en Infraestructura como código en tus agentes.

Acceder a Google Cloud APIs y servicios con la identidad del agente

Una vez que hayas creado un agente con identidad de agente, podrás conceder o denegar el acceso del agente a las APIs y los servicios mediante las siguientes políticas de gestión de identidades y accesos: Google Cloud

• Permitir políticas: concede a un agente acceso a un recurso de Google Cloud .

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

Dar acceso a un agente

Concede permisos de gestión de identidades y accesos a la identidad del agente. Te recomendamos los siguientes roles:

• roles/aiplatform.expressUser: concede acceso para ejecutar inferencias, sesiones y memoria.

• roles/serviceusage.serviceUsageConsumer: concede al agente permiso para usar la cuota del proyecto y el SDK de Vertex AI.

Crea una política de gestión de identidades y accesos de permiso para asignar un rol de gestión de identidades y accesos 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" \

Haz los cambios siguientes:

• ORGANIZATION_ID: el ID de tu organización.

• PROJECT_NUMBER: tu número de proyecto.

• LOCATION: tu región. Consulta las regiones admitidas de Vertex AI Agent Engine.

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

• ROLE_NAME es el nombre del rol que quieres conceder. Por ejemplo, roles/vision.user. Si quieres ver una lista de los roles predefinidos, consulta el artículo Descripción de los roles.

Una vez configurada la gestión de identidades y accesos, las credenciales predeterminadas de aplicación del SDK de Google Cloud usan automáticamente la identidad del agente para autenticarse en los recursos deGoogle Cloud .

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ímites de acceso de principales.

• Denegar el acceso del agente a determinados recursos mediante la política de denegación de gestión de identidades y accesos.

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

Acceder a servicios de terceros mediante autoridad delegada con OAuth

La identidad del agente permite que este acceda a servicios de terceros en tu nombre mediante la integración con Secret Manager.

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

1. Crea un contenedor en Secret Manager.

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

3. Añade el ID de cliente o el secreto de cliente a Secret Manager.

4. Restringe el acceso a estas credenciales en función del ID de 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 mediante su identificador principal y la biblioteca de autenticación Google 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 de cliente, ahora puedes crear tu herramienta y configurar la autenticación basada en OAuth.

En el siguiente ejemplo, se usa un agente desarrollado con Agent Development Kit (ADK). La autenticación basada en OAuth se incluye en los métodos authenticationScheme y authCredential como parte de la creació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, ocurre lo siguiente (si usas ADK de forma local a través de ADK web, los pasos se automatizan en ADK web y en el backend de ADK):

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

2. Las herramientas programadas en ADK (con auth_scheme y auth_credential) devuelven un objeto authConfig al frontend (que incluye el URI de redirección y el ID de cliente).

3. El frontend analiza el objeto authConfig y se te redirige a la página de autorización de terceros. Después de iniciar sesión, se te redirigirá al frontend del agente y el código de autorización se enviará al backend del ADK.

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

Si despliegas un agente de ADK en el tiempo de ejecución de Vertex AI Agent Engine, debes crear un frontend personalizado y migrar la autenticación web de ADK o el código de redirección a tu frontend para realizar la misma integración de OAuth.

Acceder a servicios de terceros mediante claves de API

La identidad del agente permite que este acceda a servicios de terceros y actúe en tu nombre mediante claves de API. Primero debes almacenar las claves de API para acceder a los servicios de terceros en Secret Manager y, a continuación, 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,
)

Registrar la actividad del agente

Si habilitas Cloud Logging, puedes ver los registros de qué agente y qué usuarios han accedido a un recurso de Google Cloud .

• Cuando el agente actúa en nombre de un usuario, los registros muestran tanto la identidad del agente como la del usuario.

• Cuando el agente actúa por su propia autoridad, los registros solo muestran la identidad del agente.

List agents and their identities

Puedes ver la lista de tus identidades de agente en Vertex AI Agent Engine mediante la Google Cloud consola y la línea de comandos.

Consola

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

   Ir a Agent Engine

   En la lista se muestran los agentes implementados que forman parte del proyecto seleccionado. Puede usar el campo Filtrar para filtrar la lista por la columna que haya especificado.

2. La identidad de cada agente se indica en la columna Identidad.

API REST

Puedes recuperar la identidad del agente cuando obtengas una instancia de Agent Engine mediante la API 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 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 a la instancia de Agent Engine.

Siguientes pasos

• Usa el agente.
• Gestionar agentes implementados.
• Solucionar problemas al implementar un agente
• Obtener asistencia