Gestire i binding

In Agent Registry, un'associazione rappresenta una connessione tra un agente di origine e una risorsa di destinazione, ad esempio un altro agente, un server MCP o un endpoint. Creando le associazioni, stabilisci relazioni esplicite che consentono agli agenti orchestratori di interagire con le funzionalità downstream.

Utilizza le associazioni per gestire due scenari:

  • Connessioni alle risorse: puoi collegare un agente di origine a una risorsa di destinazione, ad esempio un altro agente, un server MCP o un endpoint. Questo scenario ti consente di mappare i workflow multi-agente in cui un orchestratore principale delega le attività a strumenti o sub-agenti specializzati.
  • Autorizzazioni delegate: puoi associare un agente a un provider di autenticazione per consentire all'agente di connettersi a destinazioni esterne o strumenti personalizzati utilizzando le proprie credenziali o per conto di un singolo utente. Questa associazione è obbligatoria se l'agente deve eseguire l'autenticazione a server o strumenti MCP remoti utilizzando token OAuth o chiavi API. Con le associazioni, non devi definire manualmente i provider di autenticazione nel codice. Per istruzioni dettagliate, consulta Creare un'associazione di provider di autenticazione in questo documento.

Questo documento descrive come creare, visualizzare, aggiornare ed eliminare le associazioni in Agent Registry.

Prima di iniziare

Prima di poter gestire le associazioni, completa le seguenti operazioni:

  1. Configura Agent Registry.
  2. Registra le risorse di origine e di destinazione. Per ulteriori informazioni, consulta Registrare i servizi.
  3. Se vuoi configurare le associazioni per le autorizzazioni delegate, crea un provider di autenticazione con il gestore di autenticazione di Agent Identity. Per ulteriori informazioni, consulta Eseguire l'autenticazione a strumenti e risorse.
  4. Per utilizzare i comandi gcloud CLI in questo documento, assicurati di aver configurato l'ambiente Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire le associazioni in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creare un'associazione

Crea un'associazione per collegare un agente di origine a una risorsa di destinazione:

gcloud alpha agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --target-identifier="TARGET_ID"

Sostituisci quanto segue:

  • BINDING_NAME: il nome che vuoi assegnare all'associazione, ad esempio my-custom-binding.
  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • DISPLAY_NAME: il nome leggibile che vuoi assegnare all'associazione, ad esempio My Custom Binding.
  • SOURCE_ID: l' identificatore dell'agente di origine nel formato URN (Uniform Resource Name).
  • TARGET_ID: l'identificatore della risorsa di destinazione in formato URN, ad esempio un identificatore del server MCP.

Creare un'associazione di provider di autenticazione

Puoi associare un agente a un provider di autenticazione per le autorizzazioni delegate. Prima di creare questa associazione, devi prima creare il provider di autenticazione con il gestore di autenticazione di Agent Identity. Per ulteriori informazioni, consulta Eseguire l'autenticazione a strumenti e risorse.

Quando specifichi il nome della risorsa --auth-provider, devi utilizzare l'ID progetto:

gcloud alpha agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --auth-provider="projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"

Sostituisci AUTH_PROVIDER_ID con l'ID del tuo provider di autenticazione.

Per esempi di come utilizzare queste associazioni nel codice dell'agente, consulta Risolvere le associazioni nel codice ADK.

Creare un elenco di associazioni

Elenca tutte le associazioni in una località specifica:

gcloud alpha agent-registry bindings list \
  --project=PROJECT_ID \
  --location=REGION

Visualizzare i dettagli dell'associazione

Recupera i dettagli di una singola associazione:

gcloud alpha agent-registry bindings describe BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

Aggiornare un'associazione

Aggiorna i parametri di un'associazione esistente, ad esempio il nome visualizzato o la descrizione, utilizzando i flag gcloud CLI:

gcloud alpha agent-registry bindings update BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="NEW_DISPLAY_NAME"

Eliminare un'associazione

Per rimuovere una connessione tra le risorse, elimina il record di associazione:

gcloud alpha agent-registry bindings delete BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

Passaggi successivi