Utiliser Agent Identity avec Agent Runtime

L'utilisation de l'identité de l'agent sur Agent Runtime fournit une identité sécurisée par agent qui permet une approche du moindre privilège pour la gestion des accès. Ce document explique comment créer des agents avec des identités d'agent, autoriser l'accès aux APIGoogle Cloud et gérer les identifiants pour les services tiers.

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

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.

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

Vous pouvez attribuer une identité unique aux agents que vous déployez sur Agent Runtime lorsque vous créez votre instance Agent Runtime. L'identité est liée à l'ID de ressource de l'agent Agent Runtime 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 Runtime sans déployer le code de l'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 le code de votre agent. Pour ce faire, créez une instance Agent Runtime 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 Runtime 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 Runtime 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 Agent Platform 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 Agent Platform 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.

  • Déployer des agents à l'aide de la CLI Agents : la CLI Agents est idéale pour les apprenants, le prototypage et les tests rapides, car elle offre une solution de déploiement rapide avec des ressources de base pour la surveillance. La commande suivante déploie votre agent :

    agents-cli deploy --agent-identity

  • Déployer des agents avec l'identité de l'agent à l'aide de la commande ADK deploy : configurer votre agent avec ADK. Avant d'exécuter adk deploy, exécutez les commandes suivantes dans le dossier de votre agent pour ajouter un fichier de configuration avec l'identité de l'agent.

    # Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json

L'instance Agent Runtime 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 Agent Platform :

    • 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. Par défaut, l'agent a accès à ses propres journaux, métriques, accès aux modèles, sessions, mémoires et bacs à sable (Preview).

Les identités d'agent sont associées aux rôles roles/aiplatform.agentContextEditor et roles/aiplatform.agentDefaultAccess par défaut, ce qui leur permet de disposer des autorisations de base nécessaires pour fonctionner.

Vous pouvez afficher l'identité via la console et l'API Agent Runtime 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 Agent Platform.

  • 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. D'autres exemples sont disponibles 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 disponibles pour Runtime.

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

  • 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 du SDK Agent Platform utilisent automatiquement l'identité de l'agent pour authentifier les ressourcesGoogle Cloud .

Accorder l'accès à plusieurs agents

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

Pour attribuer un rôle à tous les agents Agent Runtime 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 Runtime 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

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 consulter la liste des identités de vos agents dans Agent Runtime à l'aide de la console Google Cloud et de la ligne de commande.

Console

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    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 Runtime à 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 Runtime 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 Runtime.

Désactiver l'accès contextuel

Par défaut, toute tentative d'utilisation d'un jeton d'accès en dehors de son environnement d'exécution Agent Runtime prévu génère l'erreur suivante :

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

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 Runtime :

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

Étapes suivantes

Guide

Découvrez comment gérer les agents déployés sur le runtime géré Agent Platform.

Guide

Utilisez un agent avec Agent Platform Runtime.