Gestire i binding

Nel registry degli agenti, 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 nel registry degli agenti.

Prima di iniziare

Prima di poter gestire le associazioni, completa i seguenti passaggi:

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire le associazioni nel registry degli agenti, 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 

gcloud 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 registry.
  • 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.

Terraform

Per creare un'associazione tra un agente di origine e una risorsa di destinazione, configura una risorsa google_agent_registry_binding. Un'associazione richiede il blocco target:

resource "google_agent_registry_binding" "agent_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Connects a source agent to a target resource."

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • BINDING_NAME: il nome univoco che vuoi assegnare all'associazione.
  • DISPLAY_NAME: il nome leggibile dell'associazione.
  • SOURCE_AGENT_NAME: il nome dell'agente di origine.
  • TARGET_RESOURCE_NAME: il nome della risorsa di destinazione, ad esempio un server MCP o un endpoint.

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 dell'identità dell'agente. 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 

gcloud 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.

Terraform

Per configurare un'associazione di provider di autenticazione in Terraform, specifica il blocco auth_provider_binding con il percorso completo della risorsa del provider di autenticazione del connettore, insieme agli ambiti e all'URI di continuazione:

resource "google_agent_registry_binding" "auth_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"
    scopes        = [SCOPES]
    continue_uri  = "CONTINUE_URI"
  }
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • BINDING_NAME: il nome univoco che vuoi assegnare all'associazione.
  • DISPLAY_NAME: il nome leggibile dell'associazione.
  • SOURCE_AGENT_NAME: il nome dell'agente di origine.
  • TARGET_RESOURCE_NAME: il nome della risorsa di destinazione, ad esempio un server MCP o un endpoint.
  • PROJECT_ID: l'ID progetto.
  • AUTH_PROVIDER_ID: l'ID del provider di autenticazione del connettore.
  • SCOPES: un elenco separato da virgole di ambiti OAuth2, ad esempio "https://www.googleapis.com/auth/cloud-platform".
  • CONTINUE_URI: l'URI di continuazione del provider di autenticazione, ad esempio https://example.com/continue.

Per esempi di come utilizzare queste associazioni nel codice dell'agente, consulta Risolvere le associazioni nel codice dell'Agent Development Kit (ADK).

Creare un elenco di associazioni

Elenca tutte le associazioni in una località specifica:

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

Visualizzare i dettagli dell'associazione

Recupera i dettagli di una singola associazione:

gcloud 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 

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

Terraform

Per aggiornare il nome visualizzato o la descrizione di un'associazione utilizzando Terraform, modifica la risorsa google_agent_registry_binding esistente nella configurazione ed esegui terraform apply.

Eliminare un'associazione

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

gcloud 

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

Terraform

Rimuovi la risorsa google_agent_registry_binding che rappresenta l'associazione dalla configurazione di Terraform, quindi esegui terraform apply.

Passaggi successivi