Partager un agent

Cette page explique comment partager un seul agent dans votre projet en accordant des autorisations IAM (Identity and Access Management) aux utilisateurs ou aux comptes de service.

Pour partager un agent, vous devez accorder l'autorisation aiplatform.reasoningEngines.query sur la ressource d'agent spécifique.

Quand partager un agent

Le partage d'un agent permet à plusieurs utilisateurs ou systèmes automatisés d'interroger l'agent. Voici quelques scénarios courants de partage d'un agent :

  • Collaboration : partagez un agent avec d'autres membres de votre équipe ou de votre organisation pour qu'ils l'utilisent pour leurs tâches.
  • Intégration d'applications : accordez l'accès à un compte de service afin qu'une application personnalisée, telle qu'un chatbot interne ou un portail d'assistance client, puisse appeler l'agent pour gérer des requêtes utilisateur spécifiques.
  • Communication entre agents : dans un système multi-agent, un agent peut avoir besoin d'appeler un autre agent pour obtenir des informations ou déléguer une sous-tâche.
  • Accès aux informations : fournissez aux utilisateurs un accès contrôlé aux données via une interface conversationnelle sans leur accorder d'accès direct aux sources de données sous-jacentes. Par exemple, partagez un agent connecté à une base de connaissances (comme les règles RH ou la documentation technique) avec tous les employés.

Avant de commencer

  1. Identifiez l'agent que vous souhaitez partager. Vous avez besoin de l'ID du projet et de l'ID du moteur de raisonnement de l'agent.
  2. Identifiez les utilisateurs ou les comptes de service auxquels vous souhaitez accorder l'accès.

Étape 1 : Créez un rôle personnalisé

Pour suivre le principe du moindre privilège, créez un rôle personnalisé contenant uniquement l'autorisation aiplatform.reasoningEngines.query.

gcloud

Pour créer un rôle personnalisé dans le projet, exécutez la commande suivante :

gcloud iam roles create ROLE_ID  --project=PROJECT_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Vous pouvez également créer le rôle pour l'ensemble de l'organisation :

gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Remplacez les éléments suivants :

  • ROLE_ID : ID du rôle, par exemple agentUser.
  • ROLE_TITLE : titre du rôle, par exemple Agent Runtime user.
  • ROLE_DESCRIPTION : brève description du rôle, par exemple Allows querying agents.
  • PROJECT_ID : ID du projet.
  • ORGANIZATION_ID : ID d'organisation.

Terraform

Pour créer le rôle personnalisé à l'aide de Terraform, utilisez la ressource google_project_iam_custom_role :

resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id     = "ROLE_ID"
title       = "ROLE_TITLE"
project     = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}

Remplacez les éléments suivants :

  • ROLE_ID : ID du rôle, par exemple agentUser.
  • ROLE_TITLE : titre du rôle, par exemple Agent Runtime user.
  • PROJECT_ID : ID du projet.

Le nom du rôle personnalisé sera projects/PROJECT_ID/roles/ROLE_ID ou organizations/ORGANIZATION_ID/roles/ROLE_ID.

Étape 2 : Attribuez le rôle à l'agent

Une fois le rôle créé, liez-le à un agent et spécifiez l'utilisateur ou le compte de service auquel accorder l'autorisation.

Python

Pour attribuer le rôle à l'aide de Python, utilisez la bibliothèque google-cloud-aiplatform :

from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient
from google.api_core.client_options import ClientOptions

# Initialize the client
client = ReasoningEngineServiceClient(
  client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com")
)

# Define the resource path
resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

# Get the current IAM policy and add the new binding
policy = client.get_iam_policy(request={"resource": resource})
binding = policy.bindings.add()
binding.role = "projects/PROJECT_ID/roles/ROLE_ID"
binding.members.append("USER_OR_SA")

# Update the IAM policy on the resource
client.set_iam_policy(request={"resource": resource, "policy": policy})

Remplacez les éléments suivants :

  • LOCATION : région où l'agent est déployé, par exemple us-central1.
  • PROJECT_ID : ID du projet.
  • REASONING_ENGINE_ID : ID du moteur de raisonnement de l'agent.
  • ROLE_ID : ID du rôle, par exemple agentUser.
  • USER_OR_SA : adresse e-mail de l'utilisateur ou du compte de service, par exemple user:someone@example.com ou serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Pour attribuer le rôle à l'aide de Terraform, utilisez la ressource google_vertex_ai_reasoning_engine_iam_member :

resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project          = "PROJECT_ID"
region           = "REGION"
reasoning_engine = "REASONING_ENGINE_ID"
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • REGION : région.
  • REASONING_ENGINE_ID : ID du moteur de raisonnement de l'agent.
  • USER_OR_SA : l'utilisateur ou le compte de service.

Points à noter concernant la sécurité

L'octroi de l'accès à l'agent permet d'envoyer directement des messages au point de terminaison de l'agent. Les contrôles de sécurité sont déterminés par le code de l'agent de réception.

  • Interface de confiance : la plupart des agents Agent Development Kit (ADK) par défaut fonctionnent à partir d'une interface de confiance. L'agent fait confiance aux commandes de l'interface, ce qui donne à l'interface un contrôle total sur les sessions et les utilisateurs. Dans ce cas, n'accordez pas d'accès direct à l'agent à des entités non fiables.
  • Agents A2A : d'autres agents, comme les agents Agent2Agent (A2A), peuvent être exposés à des entités non approuvées s'ils implémentent leur propre authentification et autorisation. Agent Runtime sur Gemini Enterprise Agent Platform ne fournit qu'un contrôle des accès approximatif à l'interface de l'agent.

Étapes suivantes