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

Cette page explique comment utiliser l'identité de l'agent Identity and 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é de l'agent pour permettre une gouvernance forte.

Les identifiants de l'identité de l'agent sont sécurisés par défaut grâce à une règle d'accès contextuel (CAA) gérée par Google. Cette règle applique la liaison mTLS pour s'assurer que les identifiants de l'agent sous la forme de jetons liés à un certificat ne peuvent être utilisés que depuis leur environnement d'exécution de confiance prévu (par exemple, un conteneur Cloud Run). Cette référence de sécurité empêche la réutilisation des identifiants volés, ce qui protège contre le vol d'identifiants et le piratage de compte.

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 associé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 le code de l'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.

    Définissez l'agent dans le framework de votre choix :

    from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

    Déployez-le ensuite :

    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
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET _NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

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

L'instance Agent Engine est créée avec une identité d'agent attestée par le système et en lecture seule (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'exécution de l'inférence, des sessions et de la mémoire.

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

  • roles/browser : accordez l'accès aux fonctionnalités de base de Google Cloud .

Des autorisations supplémentaires peuvent être nécessaires si vous utilisez la journalisation, les métriques et le registre des API Cloud, ainsi que pour toute autre ressource que vous souhaitez exposer à votre agent. Vous trouverez d'autres exemples plus loin.

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 compatibles avec 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 complète des rôles prédéfinis, consultez la page 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 .

Accorder l'accès à plusieurs agents

Vous pouvez attribuer un rôle IAM à tous les agents Agent Engine d'un projet spécifique ou de l'ensemble d'une organisation.

Pour attribuer un rôle à tous les agents Agent Engine d'un projet, utilisez l'une des commandes suivantes.

Si votre projet appartient à une organisation :

# 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 votre projet n'appartient à aucune organisation :

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Il peut être plus facile d'accorder des autorisations courantes telles que le quota, la journalisation ou l'accès aux modèles à tous les agents du projet pour simplifier les déploiements. Ensuite, accordez des autorisations spécifiques et limitées à des agents individuels pour les autorisations plus sensibles, comme l'accès aux données. Il est possible d'accorder ces autorisations à tout moment après la première utilisation de la fonctionnalité d'identité de l'agent dans une organisation ou un projet. Vous pouvez donc le faire avant le déploiement de l'agent.

Par exemple, les commandes suivantes accordent des rôles de base à tous les agents d'un projet :

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/aiplatform.expressUser

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

Pour attribuer un rôle à tous les agents Agent Engine d'une organisation :

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

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 autorisation 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 --data-file=oauth-secret

# 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
from google.auth import default

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

Grâce à l'ID client et au code secret du client, vous pouvez désormais 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 AuthCredential et OAuth2Auth lors de la construction de l'outil :

import os
import asyncio

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.5-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=[slack_toolset],
)

Lors de l'exécution, les étapes suivantes se produisent (si vous utilisez ADK en local 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 continue d'exécuter l'outil.

Si vous déployez un agent ADK dans l'environnement d'exécution Vertex AI Agent Engine, vous devez créer une interface utilisateur personnalisée et migrer le code d'authentification ou de redirection ADK-web dans votre interface utilisateur 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

# Access secret is defined in the code blocks above
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é des agents

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.

Désactiver l'accès contextuel

Pour les cas particuliers, tels que les exigences spécifiques de partage de jetons entre les agents, vous pouvez désactiver la règle CAA par défaut. Cette action est fortement déconseillée, car elle rend l'agent vulnérable au vol d'identifiants.

Pour désactiver la règle d'accès contextuel par défaut, définissez la variable d'environnement suivante lorsque vous créez votre instance Agent Engine :

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

Étapes suivantes