Partager un agent

Cette page explique comment partager un seul agent dans votre projet en accordant des autorisations Identity and Access Management à des utilisateurs ou des 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 puissent l'utiliser 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 traiter des demandes utilisateur spécifiques.
• Communication entre agents : dans un système multi-agents, 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 : permettez aux utilisateurs d'accéder aux données de manière contrôlée via une interface conversationnelle, sans leur accorder un 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, tel que 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, tel que 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 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 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, tel que agentUser.
• USER_OR_SA : adresse e-mail de l'utilisateur ou du compte de service, par exemple user:[e-mail] ou serviceAccount:[e-mail].

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 = google_vertex_ai_reasoning_engine.my_engine.name
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.
• USER_OR_SA : compte utilisateur ou compte de service.

Points à noter concernant la sécurité

L'accès à l'agent permet d'envoyer directement des messages au point de terminaison FastAPI de l'agent. Les garanties de sécurité sont déterminées par le code de l'agent destinataire.

• Interface utilisateur de confiance : la plupart des agents ADK par défaut fonctionnent à partir d'une interface utilisateur de confiance. L'agent fait confiance aux commandes de l'interface utilisateur, ce qui donne à l'interface utilisateur 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. L'environnement d'exécution de l'agent ne fournit qu'un contrôle des accès approximatif à l'interface de l'agent.