Autenticación con la propia autoridad de un agente

Los agentes pueden acceder a Google Cloud APIs y otros recursos con su propia autoridad. Recomendamos este método para los agentes alojados en Google Cloudque interactúan con otros servicios de Google Cloud .

Cuando un agente actúa por su propia autoridad, usa su identidad SPIFFE principal para solicitar tokens de acceso de Google Cloud .

Antes de comenzar

Verifica que hayas elegido el método de autenticación correcto.
Crea e implementa un agente con la identidad del agente habilitada.
Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Para obtener los permisos que necesitas para otorgar acceso de un agente a los servicios de Google Cloud , pídele a tu administrador que te otorgue los siguientes roles de IAM en el recurso de destino:

Para otorgar acceso a un agente:
- Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
- Administrador de seguridad (roles/iam.securityAdmin)
Roles recomendados para la identidad del agente:
- Editor de contexto del agente (roles/aiplatform.agentContextEditor)
- Acceso predeterminado del agente (roles/aiplatform.agentDefaultAccess)
- Usuario de Vertex AI (roles/aiplatform.user)
- Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)
- Navegador (roles/browser)
- Visualizador de objetos de Storage (roles/storage.objectViewer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga acceso a los agentes

Para permitir que tu agente acceda a un servicio Google Cloud , debes otorgarle a la identidad del agente los roles necesarios en el recurso de destino.

En las políticas de permisos de IAM, las identidades de los agentes usan identificadores de principal.

Para otorgar acceso de un agente a un recurso, usa la consola de Google Cloud o gcloud CLI.

Console

En la consola de Google Cloud , ve a la página IAM del recurso al que deseas otorgar acceso.
- En el caso de un proyecto, ve a la página IAM:
  Ir a la página IAM
- Para otros recursos, ve a la página de ese recurso y haz clic en la pestaña Permisos o IAM.
Haz clic en Otorgar acceso.
En el campo Principales nuevas, ingresa el identificador principal que coincida con el nivel de acceso que deseas otorgar:
- Un solo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Todos los agentes de un proyecto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Todos los agentes de una organización: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
En el campo Selecciona un rol, busca y selecciona el rol que deseas otorgar.
Haz clic en Guardar.

Google Cloud CLI

Para otorgar acceso de un agente a un recurso, ejecuta el siguiente comando:

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Reemplaza lo siguiente:

SERVICE: El servicio de Google Cloud (por ejemplo,storage o bigquery).
RESOURCE_NAME: Es el nombre del recurso (por ejemplo, el nombre del bucket o el ID del conjunto de datos).
PRINCIPAL_IDENTIFIER: Es el identificador de la principal que coincide con el nivel de acceso que deseas otorgar:
- Un solo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Todos los agentes de un proyecto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Todos los agentes de una organización: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID: Es el ID de tu organización Google Cloud .
PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
LOCATION: Es la ubicación de tu agente (por ejemplo, us-central1). (Solo se requiere para el acceso de un solo agente).
ENGINE_ID: Es el ID de tu motor de razonamiento. (Solo se requiere para el acceso de un solo agente).
ROLE: Es el rol de IAM que deseas otorgar.

Haz referencia a la identidad del agente en tu código

Las bibliotecas cliente usan automáticamente la identidad del agente cuando este se implementa en un Google Cloud entorno compatible. Google Cloud

En el siguiente fragmento de Python, se muestra cómo usar de forma manual las credenciales de identidad del agente para llamar a la API de Cloud Vision con el Kit de desarrollo de agentes (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Opcional: Inhabilita el Acceso adaptado al contexto

Una política predeterminada de acceso adaptado al contexto administrada por Google ayuda a proteger las credenciales de identidad del agente. Más allá de la puerta de enlace del agente, la política aplica la prueba demostrable de posesión (DPoP) autenticando el token de acceso del agente. La política también exige que se use mTLS para acceder a Agent Gateway. Esto garantiza que los tokens vinculados a certificados solo se puedan usar desde su entorno de ejecución previsto y de confianza (por ejemplo, un contenedor de Cloud Run). Este parámetro de referencia de seguridad hace que las credenciales robadas no se puedan volver a usar, lo que ayuda a proteger contra el robo de credenciales y la apropiación de cuentas (ATO).

En casos excepcionales, como requisitos específicos de uso compartido de tokens entre agentes, si necesitas insertar el token directamente en el encabezado o si tu agente no puede autenticarse con un error 401 UNAUTHENTICATED, puedes inhabilitar la política predeterminada de Context-Aware Access. Si inhabilitas esta opción, se quitará la protección de la vinculación de tokens, lo que hará que estos tokens de acceso de corta duración sean vulnerables a robos o ataques de reproducción. Por lo tanto, no se recomienda inhabilitar esta opción.

Para inhabilitar esta opción, configura la siguiente variable de entorno cuando implementes tu agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Implementa el agente

Cuando implementes tu agente en Google Cloud, asegúrate de que la identidad del agente esté habilitada. Si realizas la implementación en Agent Runtime, usa la marca identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI 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 (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)