Utiliser l'identité de l'agent avec Vertex AI Agent Engine

Cette page explique comment utiliser l'identité de l'agent Identity Access Management (IAM) pour fournir des fonctionnalités de sécurité et de gestion des accès lorsque vous utilisez des agents sur Vertex AI Agent Engine Runtime.

Présentation

L'identité de l'agent fournit une identité par agent qui permet une approche de moindre privilège et est liée au cycle de vie de l'agent. L'identité de l'agent est donc un compte principal plus sécurisé que les comptes de service. Les contrôles de gestion des accès existants via IAM prennent en charge l'identité des agents pour permettre une gouvernance forte.

Cette page aborde les sujets suivants :

Limites

Tenez compte des limites suivantes lorsque vous planifiez votre projet :

  • Les identités d'agent ne peuvent pas se voir attribuer les anciens rôles de bucket (storage.legacyBucketReader, storage.legacyBucketWriter ou storage.legacyBucketOwner) sur les buckets Cloud Storage.

  • Nous vous recommandons d'utiliser l'identité de l'agent uniquement dans les environnements de test.

Créer un agent avec une identité d'agent

Vous pouvez provisionner les agents que vous déployez sur Vertex AI Agent Engine avec une identité unique lorsque vous créez votre instance Agent Engine. L'identité est liée à l'ID de ressource de l'agent Vertex AI Agent Engine et est indépendante du framework d'agent que vous avez utilisé pour développer l'agent.

Vous disposez des options suivantes lorsque vous créez une identité d'agent :

  • Créer une instance Agent Engine sans déployer de code d'agent : si vous souhaitez configurer des règles IAM avant de déployer l'agent, vous pouvez créer une identité d'agent sans déployer votre code d'agent. Pour ce faire, créez une instance Agent Engine avec uniquement le champ 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}
)

    Une fois que vous avez créé l'instance Agent Engine avec l'identité de l'agent, vous pouvez ajouter du code d'agent à l'aide de agent_engine.update(...).

  • Créer une instance Agent Engine lors du déploiement du code de l'agent : si vous souhaitez provisionner l'identité de l'agent lors du déploiement de son code, utilisez le SDK Vertex AI pour Python et l'indicateur 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",
      },
)

    où BUCKET_NAME est le nom de votre bucket Cloud Storage.

L'instance Agent Engine est créée avec une identité d'agent en lecture seule et attestée par le système (un identifiant 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

Les éléments suivants sont provisionnés automatiquement dans l'identité de l'agent :

  • TRUST_DOMAIN : un domaine de confiance est provisionné pour vous lorsque vous activez l'API Vertex AI :

    • Si vous disposez d'une organisation, le domaine approuvé est créé au niveau de l'organisation au format agents.global.org-ORGANIZATION_ID.system.id.goog.

    • Si votre projet n'est pas associé à une organisation, un domaine approuvé est créé au niveau du projet au format agents.global.project-PROJECT_NUMBER.system.id.goog.

  • NAMESPACE : chemin d'accès immuable à la ressource de l'agent.

  • AGENT_NAME : agent-reasoning-engine-id immuable.

L'identité de l'agent est basée sur SPIFFE. Nous provisionnons et gérons également automatiquement un certificat x509 sur l'agent avec la même identité pour une authentification sécurisée.

Vous pouvez afficher l'identité via la console et l'API Vertex AI Agent Engine Google Cloud .

Accéder aux API et aux services à l'aide de l'identité de l'agent Google Cloud

Une fois que vous avez créé un agent avec une identité d'agent, vous pouvez lui accorder ou lui refuser l'accès aux API et services Google Cloud à l'aide des stratégies IAM suivantes :

  • Règles d'autorisation : accordent à un agent l'accès à une ressource Google Cloud .

  • Règles de refus : refusez l'accès d'un agent à une ressource Google Cloud .

Accorder l'accès à un agent

Accordez des autorisations IAM à l'identité de l'agent. Nous vous recommandons les rôles suivants :

  • roles/aiplatform.expressUser : accorde l'accès à l'inférence, aux sessions et à la mémoire en cours d'exécution.

  • roles/serviceusage.serviceUsageConsumer : accordez à l'agent l'autorisation d'utiliser le quota du projet et le SDK Vertex AI.

Créez une stratégie d'autorisation IAM pour accorder un rôle IAM à un agent :

  # 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" \

Remplacez les éléments suivants :

  • ORGANIZATION_ID : ID de votre organisation.

  • PROJECT_NUMBER : numéro de votre projet.

  • LOCATION : votre région. Consultez les régions disponibles pour Vertex AI Agent Engine.

  • AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.

  • ROLE_NAME : nom du rôle que vous souhaitez attribuer. Exemple : roles/vision.user. Pour obtenir la liste des rôles prédéfinis, consultez Comprendre les rôles.

Une fois IAM configuré, les identifiants par défaut de l'application de Google Cloud SDK utilisent automatiquement l'identité de l'agent pour s'authentifier auprès des ressourcesGoogle Cloud .

Refuser l'accès à un agent

Pour refuser l'accès d'un agent aux ressources, vous pouvez utiliser la stratégie de refus IAM ou configurer une stratégie de limite d'accès des comptes principaux.

  • Refusez l'accès de l'agent à certaines ressources à l'aide de la stratégie de refus 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"
      ]
    }
  }
]
}

  • Configurez une limite d'accès de compte principal pour limiter les ressources auxquelles l'agent peut accéder, malgré les autres autorisations dont il dispose :

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

Accéder à des services tiers avec une autorité déléguée à l'aide d'OAuth

L'identité de l'agent peut lui permettre d'accéder à des services tiers en votre nom en s'intégrant à Secret Manager.

Pour configurer l'intégration à Secret Manager, vous devez d'abord stocker les identifiants auxiliaires (ID client ou code secret du client) permettant d'accéder aux services tiers dans Secret Manager (dans le projet consommateur où l'agent est géré au niveau du cycle de vie) en suivant les étapes suivantes :

  1. Créez un conteneur dans Secret Manager.

  2. Obtenez l'ID client ou le code secret du client auprès du fournisseur de l'application tierce.

  3. Ajoutez l'ID client ou le code secret du client à Secret Manager.

  4. Restreignez l'accès à ces identifiants en fonction de l'ID d'agent (un identifiant 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" \

Une fois le secret stocké, l'agent peut accéder à ces identifiants lors de l'exécution à l'aide de son identifiant principal et de la bibliothèque d'authentificationGoogle Cloud standard automatiquement dans le cadre des identifiants par défaut de l'application.

# 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

Avec l'ID client et le code secret du client, vous pouvez maintenant créer votre outil et configurer l'authentification basée sur OAuth.

L'exemple suivant utilise un agent développé par Agent Development Kit (ADK). L'authentification basée sur OAuth est encapsulée dans les méthodes authenticationScheme et authCredential dans le cadre de la construction de l'outil :

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(),
)

Lors de l'exécution, les événements suivants se produisent (si vous utilisez ADK localement via le Web ADK, les étapes sont automatisées dans le Web ADK et le backend ADK) :

  1. Vous accédez à l'agent, qui décide qu'il doit appeler l'outil (par exemple, Slack).

  2. Les outils programmés dans ADK (avec auth_scheme et auth_credential) renvoient un objet authConfig au frontend (qui inclut l'URI de redirection et l'ID client).

  3. L'interface analyse l'objet authConfig et vous êtes redirigé vers la page d'autorisation tierce. Une fois connecté, vous êtes redirigé vers l'interface utilisateur de l'agent, et le code d'autorisation est envoyé au backend de l'ADK.

  4. Le backend utilise le code d'autorisation pour obtenir un jeton d'accès au service tiers et poursuit l'exécution de l'outil.

Si vous déployez un agent ADK dans Vertex AI Agent Engine Runtime, vous devez créer une interface personnalisée et migrer l'authentification ADK-Web ou le code de redirection dans votre interface pour effectuer la même intégration OAuth.

Accéder à des services tiers à l'aide de clés API

L'identité de l'agent peut lui permettre d'accéder à des services tiers et d'agir en votre nom à l'aide de clés API. Vous devez d'abord stocker les clés API pour accéder aux services tiers dans Secret Manager, puis récupérer ces identifiants à partir 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,
)

Enregistrer l'activité de l'agent

Si vous activez Cloud Logging, vous pouvez afficher les journaux des agents et des utilisateurs qui ont accédé à une ressource Google Cloud .

  • Lorsque l'agent agit au nom d'un utilisateur, les journaux indiquent à la fois l'identité de l'agent et celle de l'utilisateur.

  • Lorsque l'agent agit de sa propre autorité, les journaux n'affichent que son identité.

Lister les agents et leurs identités

Vous pouvez afficher la liste des identités de vos agents dans Vertex AI Agent Engine à l'aide de la console Google Cloud et de la ligne de commande.

Console

  1. Dans la console Google Cloud , accédez à la page Vertex AI Agent Engine.

    Accéder à Agent Engine

    Les agents déployés qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

  2. Pour chaque agent, son identité est indiquée dans la colonne Identité.

API REST

Vous pouvez récupérer l'identité de l'agent lorsque vous obtenez une instance Agent Engine à l'aide de l'API REST.

La réponse inclut l'identité de l'agent au format suivant :

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

Pour les instances Agent Engine qui n'utilisent pas l'identité de l'agent, le champ effectiveIdentity contient le nom de l'agent de service ou du compte de service associé à l'instance Agent Engine.

Étapes suivantes