Condividere un agente

Questa pagina descrive come condividere un singolo agente nel tuo progetto concedendo autorizzazioni Identity and Access Management a utenti o service account.

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

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:

  • Collaborazione: condividi un agente con altri membri del tuo team o della tua organizzazione per utilizzarlo per le loro attività.
  • Integrazione dell'applicazione: concedi l'accesso a un account di servizio in modo che un'applicazione personalizzata, come un chatbot interno o un portale di assistenza clienti, possa chiamare l'agente per gestire richieste specifiche degli utenti.
  • Comunicazione tra agenti: in un sistema multi-agente, un agente potrebbe dover chiamare un altro agente per informazioni o per delegare una sotto-attività.
  • 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 (come le normeRUR o la documentazione tecnica) con tutti i dipendenti.

Prima di iniziare

  1. Identifica l'agente che vuoi condividere. Devi disporre dell'ID progetto e dell'ID motore di ragionamento dell'agente.
  2. Identifica gli utenti o i service account 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, associalo a un agente e specifica l'utente o ilaccount di serviziot 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 viene eseguito il deployment dell'agente, ad esempio us-central1.
  • PROJECT_ID: l'ID progetto.
  • REASONING_ENGINE_ID: l'ID del motore di ragionamento dell'agente.
  • ROLE_ID: l'ID del ruolo, ad esempio agentUser.
  • USER_OR_SA: l'email 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 il account di servizio.

Considerazioni sulla sicurezza

La concessione dell'accesso all'agente fornisce l'accesso diretto all'invio di messaggi all'endpoint FastAPI dell'agente. Le garanzie di sicurezza sono determinate dal codice dell'agente ricevente.

  • Frontend attendibile: la maggior parte degli agenti ADK predefiniti opera da un frontend attendibile. L'agente considera attendibili i comandi frontend, il che conferisce al frontend 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. L'ambiente di runtime dell'agente fornisce solo ucontrollo dell'accessolo dell'accesso grossolano all'interfaccia dell'agente.