Partager un agent

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

Pour partager un agent, vous accordez 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 organisation pour qu'ils l'utilisent dans 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 traiter 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é qui ne contient que 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 de l'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 : Accordez le rôle sur 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 accorder 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 dans laquelle 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 compte de service, par exemple user:someone@example.com ou serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Pour accorder 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 : utilisateur ou compte de service.

Points à noter concernant la sécurité

L'octroi de l'accès à l'agent fournit un accès direct pour envoyer 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 récepteur.

  • Interface de premier plan de confiance : la plupart des agents par défaut d'Agent Development Kit (ADK) fonctionnent à partir d'une interface de premier plan de confiance. L'agent approuve les commandes de l'interface de premier plan, ce qui lui donne 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, tels que les agents Agent2Agent (A2A), peuvent être exposés à des entités non fiables s'ils implémentent leur propre authentification et autorisation. Agent Runtime ne fournit qu'un contrôle des accès grossier à l'interface de l'agent.

Étape suivante