Utiliser Agent Identity avec Agent Runtime

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

Présentation

L'identité d'agent fournit une identité par agent qui permet d'appliquer une approche basée sur le principe du moindre privilège. Elle est liée au cycle de vie de l'agent, ce qui en fait un compte principal plus sécurisé que les comptes de service. Les contrôles de gestion des accès existants via IAM sont compatibles avec l'identité d'agent pour permettre une gouvernance forte.

Les identifiants d'identité d'agent sont sécurisés par défaut via une règle d'accès contextuel gérée par Google. Cette règle applique la liaison mTLS pour s'assurer que les identifiants de l'agent sous forme de jetons liés à un certificat ne peuvent être utilisés que dans leur environnement d'exécution prévu et approuvé (par exemple, un conteneur Cloud Run ). Cette base de 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 la prise de contrôle de compte.

Cette page aborde les sujets suivants :

Limites

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

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

Vous pouvez provisionner les agents que vous déployez sur Agent Runtime avec une identité unique lors de la création de 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 de code d'agent : si vous souhaitez configurer des stratégies 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 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={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

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

  • Créer une instance Agent Runtime lors du déploiement du code d'agent : si vous souhaitez provisionner l'identité d'agent lors du déploiement de votre code d'agent, 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.",
)

    Ensuite, déployez-le :

    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 une identité d'agent à l'aide de la commande ADK deploy : configurez 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 une identité d'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 en lecture seule (un identifiant de compte 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 le cadre de l'identité d'agent :

  • TRUST_DOMAIN : un domaine de confiance est provisionné lorsque vous activez l'API Agent Platform :

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

    • Si votre projet ne dispose pas d'organisation, un domaine de confiance 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 : immuable agent-reasoning-engine-id.

L'identité d'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 à sa propre journalisation, ses métriques, son accès au modèle, ses sessions, ses mémoires et ses bacs à sable (aperçu).

Les identités d'agent sont fournies avec les rôles roles/aiplatform.agentContextEditor et roles/aiplatform.agentDefaultAccess par défaut afin que les agents disposent des autorisations de base pour fonctionner.

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

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

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

  • Stratégies d'autorisation : accordez à un agent l'accès à une Google Cloud ressource.

  • Stratégies de refus : refusez à un agent l'accès à une Google Cloud ressource.

Accorder l'accès à un agent

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

  • roles/aiplatform.expressUser: accordez l'accès à l'exécution d'inférences, aux sessions et à 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. Google Cloud

Des autorisations supplémentaires peuvent être nécessaires si vous utilisez la journalisation, les métriques et le registre d'API Cloud, ainsi que pour toute autre ressource que vous souhaitez exposer à votre agent. Pour en savoir plus, consultez les exemples ci-dessous.

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

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

  • ROLE_NAME est le nom du rôle que vous souhaitez accorder. Par 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é d'agent pour authentifier Google Cloud les ressources.

Accorder l'accès à plusieurs agents

Vous pouvez accorder un rôle IAM à tous les agents Agent Runtime d'un projet particulier ou de l'ensemble d'une organisation.

Pour accorder 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 pas à une 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 des autorisations plus sensibles, telles que l'accès aux données. Vous pouvez accorder ces autorisations à tout moment après la première utilisation de la fonctionnalité d'identité d'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 accorder 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 des comptes principaux pour limiter les ressources auxquelles l'agent peut accéder, malgré d'autres autorisations dont il pourrait disposer :

    // 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é de l'agent

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

  • Lorsque l'agent agit pour le compte d'un utilisateur, les journaux affichent à 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 Agent Runtime à l'aide de la Google Cloud console et de la ligne de commande.

Console

  1. Dans la Google Cloud console, accédez à la page Déploiements d'Agent Platform.

    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 Filtre pour filtrer la liste par colonne spécifiée.

  2. Pour chaque agent, l'identité de l'agent 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 d'identité d'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"

Dans des cas particuliers, tels que des exigences spécifiques de partage de jetons entre les agents, vous pouvez désactiver la stratégie d'accès contextuel par défaut. Cette action est fortement déconseillée, car elle rend un agent vulnérable au vol d'identifiants.

Désactivez la stratégie d'accès contextuel par défaut en définissant 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,
  }
}

Étape suivante

Guide

Découvrez comment gérer les agents qui ont été déployés sur l'environnement d'exécution géré d'Agent Platform.

Guide

Utilisez un agent avec Agent Platform Runtime.