Gestire i binding

In Agent Registry, le associazioni consentono agli agenti orchestratori di connettersi ad agenti downstream, server MCP ed endpoint senza impostare come hardcoded i dettagli di connessione o autenticazione nel codice. Puoi creare, visualizzare, aggiornare ed eliminare le associazioni in Agent Registry per gestire le connessioni alle risorse e le autorizzazioni delegate.

Prima di iniziare

  1. Configura Agent Registry.

  2. Per una configurazione con un singolo progetto, recupera l'ID progetto del progetto di governance in cui è abilitato Agent Registry. Se hai configurato un confine di gestione per più progetti, utilizza l'ID del progetto di gestione per il rilevamento e la registrazione a livello di confine oppure specifica l'ID di un progetto membro per le operazioni su un singolo progetto.

  3. Registra i componenti di origine e di destinazione. Per saperne di più, consulta Modelli di registrazione.

  4. Se vuoi configurare le associazioni per le autorizzazioni delegate, crea un provider di autenticazione con il gestore di autenticazione di Agent Identity. Per saperne di più, consulta Esegui l'autenticazione in strumenti e risorse.

  5. Per utilizzare i comandi di Google Cloud CLI in questo documento, configura l'ambiente gcloud CLI.

Ruoli obbligatori

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

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.

Scenari di associazione

Puoi utilizzare le associazioni per connettere le risorse e delegare le autorizzazioni. Ad esempio, puoi utilizzare le associazioni nei seguenti scenari:

  • Connessioni alle risorse: collega 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 workflow multi-agente in cui un orchestratore principale delega le attività a subagenti o strumenti specializzati.
  • Autorizzazioni delegate: associa un agente a un provider di autenticazione per consentirgli di connettersi a target esterni o strumenti personalizzati utilizzando le proprie credenziali o per conto di un singolo utente. Questa associazione è obbligatoria se l'agente deve autenticarsi su 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 Crea un'associazione del provider di autenticazione in questo documento.

Crea un'associazione

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

gcloud

Esegui il comando gcloud agent-registry bindings create:

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:

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 = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }
}

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_ID: l'identificatore dell'agente di origine in formato URN.
  • TARGET_ID: l'identificatore del registry della risorsa di destinazione in formato URN.

Crea un'associazione del provider di autenticazione

Puoi associare un agente a un provider di autenticazione per le autorizzazioni delegate. Prima di creare questa associazione, devi creare il provider di autenticazione con il gestore di autenticazione. Per saperne di più, consulta Esegui l'autenticazione in strumenti e risorse.

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

gcloud

Esegui il comando gcloud agent-registry bindings create con il flag --auth-provider-binding:

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

Sostituisci quanto segue:

  • BINDING_NAME: il nome univoco che vuoi assegnare all'associazione.
  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.
  • DISPLAY_NAME: il nome leggibile dell'associazione.
  • SOURCE_ID: l'identificatore dell'agente di origine in formato URN.
  • TARGET_ID: l'identificatore del registry della risorsa di destinazione in formato URN.
  • AUTH_PROVIDER_ID: l'ID del provider di autenticazione.

Terraform

Per configurare un'associazione del provider di autenticazione in Terraform, specifica il blocco auth_provider_binding con il nome della risorsa del provider di autenticazione, insieme ai relativi 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 = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/authProviders/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_ID: l'identificatore dell'agente di origine in formato URN.
  • TARGET_ID: l'identificatore del registry della risorsa di destinazione in formato URN.
  • PROJECT_ID: l'ID progetto
  • AUTH_PROVIDER_ID: l'ID del provider di autenticazione.
  • SCOPES: un elenco separato da virgole di ambiti OAuth 2.0, 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 questi binding nel codice dell'agente, consulta Risolvi i binding nel codice dell'Agent Development Kit (ADK).

Crea un elenco di associazioni

Elenca tutte le associazioni in una località specifica eseguendo il comando gcloud agent-registry bindings list:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.

Visualizza i dettagli dell'associazione

Recupera i dettagli di una singola associazione eseguendo il comando gcloud agent-registry bindings describe:

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

Sostituisci quanto segue:

  • BINDING_NAME: il nome dell'associazione.
  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.

Aggiorna un'associazione

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

gcloud

Esegui il comando gcloud agent-registry bindings update:

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

Sostituisci quanto segue:

  • BINDING_NAME: il nome dell'associazione che vuoi aggiornare.
  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.
  • NEW_DISPLAY_NAME: il nuovo nome leggibile per l'associazione.

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.

Elimina un'associazione

Per rimuovere una connessione tra le risorse, elimina l'associazione:

gcloud

Esegui il comando gcloud agent-registry bindings delete:

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

Sostituisci quanto segue:

  • BINDING_NAME: il nome dell'associazione che vuoi eliminare.
  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.

Terraform

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

Passaggi successivi