Condividere un agente

Questa pagina descrive come condividere un singolo agente nel tuo progetto concedendo autorizzazioni Identity and Access Management (IAM) a utenti o account di servizio.

Per condividere un agente, concedi l'autorizzazione aiplatform.reasoningEngines.query sulla risorsa dell'agente specifica.

Quando condividere un agente

La condivisione di un agente consente a più utenti o sistemi automatizzati di eseguire query sull'agente. Gli scenari comuni per la condivisione di un agente includono i seguenti:

  • Collaborazione: condividi un agente con altri membri del tuo team o della tua organizzazione per utilizzarlo per le loro attività.
  • Integrazione delle applicazioni: concedi l'accesso a un account di servizio in modo che un' applicazione personalizzata, ad esempio un chatbot interno o un portale di assistenza clienti, possa chiamare l'agente per gestire richieste utente specifiche.
  • Comunicazione da agente ad agente: in un sistema multi-agente, un agente potrebbe dover chiamare un altro agente per informazioni o per delegare una sottoattività.
  • Accesso alle informazioni: fornisci agli utenti un accesso controllato ai dati tramite un'interfaccia conversazionale senza concedere loro l'accesso diretto alle origini dati sottostanti. Ad esempio, condividi un agente connesso a una knowledge base (ad esempio policy RU o documentazione tecnica) con tutti i dipendenti.

Prima di iniziare

  1. Identifica l'agente che vuoi condividere. Ti servono l'ID progetto e l'ID motore di ragionamento dell'agente.
  2. Identifica gli utenti o gli account di servizio a cui vuoi concedere l'accesso.

Passaggio 1: crea un ruolo personalizzato

Per seguire il principio del privilegio minimo, crea un ruolo personalizzato che contenga solo l'autorizzazione aiplatform.reasoningEngines.query.

gcloud

Per creare un ruolo personalizzato nel progetto, esegui questo comando:

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

In alternativa, per creare il ruolo per l'intera organizzazione:

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

Sostituisci quanto segue:

  • ROLE_ID: l'ID del ruolo, ad esempio agentUser.
  • ROLE_TITLE: un titolo per il ruolo, ad esempio Agent Runtime user.
  • ROLE_DESCRIPTION: una breve descrizione del ruolo, ad esempio Allows querying agents.
  • PROJECT_ID: l'ID progetto.
  • ORGANIZATION_ID: l'ID organizzazione.

Terraform

Per creare il ruolo personalizzato utilizzando Terraform, utilizza la risorsa 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"]
}

Sostituisci quanto segue:

  • ROLE_ID: l'ID del ruolo, ad esempio agentUser.
  • ROLE_TITLE: un titolo per il ruolo, ad esempio Agent Runtime user.
  • PROJECT_ID: l'ID progetto.

Il nome del ruolo personalizzato sarà projects/PROJECT_ID/roles/ROLE_ID o organizations/ORGANIZATION_ID/roles/ROLE_ID.

Passaggio 2: concedi il ruolo all'agente

Dopo aver creato il ruolo, associa il ruolo a un agente e specifica l'utente o account di servizio a cui concedere l'autorizzazione.

Python

Per concedere il ruolo utilizzando Python, utilizza la libreria 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})

Sostituisci quanto segue:

  • LOCATION: la regione in cui è stato eseguito il deployment dell'agente, ad esempio us-central1.
  • PROJECT_ID: l'ID progetto.
  • REASONING_ENGINE_ID: l'ID motore di ragionamento dell'agente.
  • ROLE_ID: l'ID del ruolo, ad esempio agentUser.
  • USER_OR_SA: l'email dell'utente o il account di servizio, ad esempio user:someone@example.com o serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Per concedere il ruolo utilizzando Terraform, utilizza la risorsa 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"
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione.
  • USER_OR_SA: l'utente o l'account di servizio.

Considerazioni sulla sicurezza

La concessione dell'accesso all'agente fornisce l'accesso diretto all'invio di messaggi all'endpoint dell'agente. I controlli di sicurezza sono determinati dal codice dell'agente ricevente.

  • Frontend attendibile: la maggior parte degli agenti predefiniti di Agent Development Kit (ADK) opera da un frontend attendibile. L'agente considera attendibili i comandi del frontend, che gli conferiscono il controllo completo di sessioni e utenti. In questi casi, non concedere l'accesso diretto all'agente a entità non attendibili.
  • Agenti A2A: altri agenti, come gli agenti Agent2Agent (A2A), possono essere esposti a entità non attendibili se implementano la propria autenticazione e autorizzazione. Agent Runtime fornisce solo un controllo dell'accesso grossolano all'interfaccia dell'agente.