Registra endpoint

In Agent Registry, un endpoint rappresenta un URL di destinazione, in genere un'API REST, a cui accedono gli agenti. Registrando queste destinazioni come componenti agentici gestiti in Agent Registry, puoi controllare centralmente a quali endpoint esterni può connettersi la tua flotta di agenti.

Questo documento spiega come registrare esplicitamente gli endpoint esterni nel registro.

Prima di iniziare

Prima di iniziare, configura Agent Registry. Per eseguire queste attività, devi avere l'ID progetto.

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

Registrare un endpoint

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

Console

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

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto 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.

    (Facoltativo) Fai clic su Verifica connessione in questo riquadro per verificare la connessione all'URL di destinazione.

  6. Fai clic su Salva.

gcloud

Crea una risorsa Service con un endpoint-spec-type di no-spec.

Registra l'endpoint e definisci i dettagli della connessione dell'interfaccia:

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 all'endpoint, ad esempio my-external-api.
  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • DISPLAY_NAME: il nome dell'endpoint leggibile da una persona.
  • 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 aver creato la risorsa Service, Agent Registry genera automaticamente una risorsa Endpoint di sola lettura sul lato consumer che gli agenti e gli orchestratori possono rilevare e utilizzare.

Terraform

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 registro.
  • ENDPOINT_NAME: il nome univoco che vuoi assegnare all'endpoint, ad esempio my-external-api.
  • DISPLAY_NAME: il nome dell'endpoint leggibile da una persona.
  • 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.

Registrare 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 i singoli progetti di carico di lavoro ospitano le istanze di calcolo degli agenti.

Quando instradi il traffico degli agenti tramite Agent Gateway in modalità in uscita, il traffico di rete in uscita viene bloccato per impostazione predefinita. Per consentire agli agenti nei progetti di carico di lavoro di comunicare con le API essenziali Google Cloud , puoi raggruppare più interfacce API in un singolo endpoint Service composito nel progetto di governance centrale.

Il raggruppamento delle interfacce in un singolo endpoint semplifica l'amministrazione delle policy, consentendoti di gestire una singola associazione di policy IAP per l'intera suite di API di Google di base.

Per registrare un endpoint API di Google composito:

gcloud

Registra l'endpoint con più URL di interfaccia nel progetto di governance centrale:

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.
  • CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale che ospita Agent Registry e Agent Gateway.
  • REGION: la regione in cui risiedono il gateway e il registro.
  • DISPLAY_NAME: il nome leggibile da una persona, ad esempio Core Google APIs.
  • DESCRIPTION: una breve descrizione, ad esempio Essential Google APIs for agent operations.
  • API_URL: l'URL dell'API Google principale, ad esempio https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: ripeti il flag --interfaces per ogni URL o variante API 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 registro.
  • SERVICE_NAME: l'ID servizio.
  • DISPLAY_NAME: il nome leggibile da una persona.
  • DESCRIPTION: la descrizione del servizio.
  • API_URL: l'URL dell'API Google principale, ad esempio https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: ripeti il blocco interfaces per ogni URL o variante API 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.

Passaggi successivi