Registra endpoint

Agent Registry ti consente di registrare manualmente gli URL di destinazione, ad esempio le API REST esterne, come endpoint gestiti, in modo da poter controllare centralmente a quali destinazioni può connettersi il tuo parco risorse di agenti.

La registrazione degli endpoint non è supportata nelle località multiregionali us e eu; devi utilizzare una regione supportata o la località global. Per saperne di più, consulta Località di Agent Registry.

Prima di iniziare

  1. Configura Agent Registry.

  2. Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per registrare gli endpoint in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Agent Registry API Editor (roles/agentregistry.editor) 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.

Registra un endpoint

Poiché gli endpoint sono destinazioni esterne personalizzate, utilizza la registrazione manuale per aggiungerli ad Agent Registry:

Console

  1. Nella console Google Cloud , vai a Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

  4. Fai clic su Aggiungi endpoint.

  5. Nel riquadro Dettagli endpoint, inserisci il nome visualizzato, una descrizione, la regione geografica e l'URL di destinazione.

    Facoltativamente, fai clic su Prova connessione in questo riquadro per testare la connessione all'URL di destinazione.

  6. Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano la raccolta di risorse a cui appartiene il componente. Per una mappatura completa dei flag alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

Per aggiungere l'endpoint ad Agent Registry, crea una risorsa Service con il comando gcloud agent-registry services create e il flag --endpoint-spec-type impostato su no-spec:

gcloud agent-registry services create ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Sostituisci quanto segue:

  • ENDPOINT_NAME: il nome che vuoi assegnare al tuo endpoint, ad esempio my-external-api. Il nome deve contenere da 4 a 63 caratteri e può contenere solo lettere minuscole, numeri e trattini.
  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.
  • DISPLAY_NAME: il nome leggibile dell'endpoint, ad esempio My External API.
  • ENDPOINT_URL: l'URL di destinazione, ad esempio https://api.example.com/v1/data.
  • PROTOCOL: l'associazione del protocollo per l'interfaccia. I valori validi sono http-json, grpc o jsonrpc.

Dopo la creazione della risorsa Service, Agent Registry genera automaticamente una risorsa Endpoint di sola lettura che gli agenti e gli orchestratori possono scoprire e utilizzare.

Terraform

Il blocco di specifica che configuri determina la raccolta di risorse a cui appartiene il componente. Per una mappatura completa delle specifiche alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

Per registrare un endpoint esterno, configura la risorsa google_agent_registry_service con il blocco endpoint_spec:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • ENDPOINT_NAME: il nome univoco che vuoi assegnare al tuo endpoint, ad esempio my-external-api. Il nome deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
  • DISPLAY_NAME: il nome leggibile dell'endpoint, ad esempio My External API.
  • ENDPOINT_URL: l'URL di destinazione, ad esempio https://api.example.com/v1/data.
  • PROTOCOL: l'associazione del protocollo per l'interfaccia. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Registra un endpoint API di Google composito

In un'architettura tra progetti, un progetto di governance centrale ospita l'infrastruttura condivisa, come Agent Registry e Agent Gateway, mentre progetti Google Cloud separati ospitano le istanze di computing degli agenti.

Quando instradi il traffico dell'agente tramite Agent Gateway in modalità in uscita, il traffico di rete in uscita viene bloccato per impostazione predefinita. Per consentire agli agenti in progetti Google Cloud separati di comunicare con le APIGoogle Cloud essenziali, puoi raggruppare più interfacce API in un'unica risorsa Service composita nel progetto di governance centrale.

Il raggruppamento delle interfacce in un unico endpoint semplifica l'amministrazione delle policy consentendoti di gestire un'unica associazione delle policy di Identity-Aware Proxy (IAP) per l'intera suite di API di Google principali.

Per registrare un endpoint API di Google composito, segui questi passaggi:

gcloud

Registra l'endpoint con più URL di interfaccia nel progetto di governance centrale utilizzando il comando gcloud agent-registry services create:

gcloud agent-registry services create SERVICE_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --endpoint-spec-type=no-spec \
    --interfaces=protocolBinding=jsonrpc,url=API_URL \
    --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

Sostituisci quanto segue:

  • SERVICE_NAME: l'identificatore del servizio, ad esempio core-gapi-services. Il nome deve essere composto da 4 a 63 caratteri e può contenere solo lettere minuscole, numeri e trattini.
  • CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale che ospita Agent Registry e Agent Gateway.
  • REGION: la regione in cui si trovano il gateway e il registry.
  • DISPLAY_NAME: il nome leggibile, ad esempio Core Google APIs.
  • DESCRIPTION: una breve descrizione, ad esempio Essential Google APIs for agent operations.
  • API_URL: l'URL dell'API di Google principale, ad esempio https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: ripeti il flag --interfaces per ogni URL o variante dell'API di Google aggiuntivo richiesto dagli agenti, ad esempio https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com o varianti regionali e mTLS come https://telemetry.mtls.googleapis.com.

Terraform

Per registrare l'endpoint API di Google composito utilizzando Terraform, definisci la risorsa google_agent_registry_service con più blocchi interfaces:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

Sostituisci quanto segue:

  • CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale.
  • REGION: la regione del registry.
  • SERVICE_NAME: l'ID servizio, ad esempio core-gapi-services. Il nome deve essere composto da 4 a 63 caratteri e può contenere solo lettere minuscole, numeri e trattini.
  • DISPLAY_NAME: il nome leggibile, ad esempio Core Google APIs.
  • DESCRIPTION: la descrizione dell'endpoint.
  • API_URL: l'URL dell'API di Google principale, ad esempio https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: ripeti il blocco interfaces per ogni URL o variante aggiuntiva dell'API di Google richiesto dai tuoi agenti, ad esempio https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com o varianti regionali e mTLS come https://telemetry.mtls.googleapis.com.

Passaggi successivi