Registrar endpoints

No Agent Registry, um endpoint representa um URL de destino, normalmente uma API REST, que seus agentes acessam. Ao registrar esses destinos como componentes de agente gerenciados no Agent Registry, você pode governar centralmente a quais endpoints externos sua frota de agentes pode se conectar.

Este documento explica como registrar explicitamente endpoints externos no registro.

Antes de começar

Antes de começar, configure o Agent Registry. Você precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da Google Cloud CLI neste documento, verifique se você configurou o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para registrar endpoints no Agent Registry, peça ao administrador para conceder a você o papel do IAM de Editor da API do Agent Registry (roles/agentregistry.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Registrar um endpoint

Como os endpoints são destinos externos personalizados, use o registro manual para adicioná-los ao Agent Registry:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto em que você configurou o Agent Registry.

  3. Selecione a guia Endpoints.

  4. Clique em Adicionar endpoint.

  5. No painel Detalhes do endpoint , insira o nome de exibição, uma descrição, a região geográfica e o URL de destino.

    Opcionalmente, clique em Testar conexão neste painel para testar sua conexão com o URL de destino.

  6. Clique em Salvar.

gcloud

Crie um recurso Service com um endpoint-spec-type de no-spec.

Registre o endpoint e defina os detalhes da conexão de interface:

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

Substitua:

  • ENDPOINT_NAME: o nome que você quer dar ao endpoint, por exemplo, my-external-api.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.
  • DISPLAY_NAME: o nome legível do endpoint.
  • ENDPOINT_URL: o URL de destino, por exemplo, https://api.example.com/v1/data.
  • PROTOCOL: a vinculação de protocolo para a interface. Os valores válidos são http-json, grpc ou jsonrpc.

Depois que o recurso Service é criado, o Agent Registry gera automaticamente um recurso Endpoint somente leitura no lado do consumidor que os agentes e orquestradores podem descobrir e usar.

Terraform

Para registrar um endpoint externo, configure o recurso google_agent_registry_service com o bloco 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
}

Substitua:

  • REGION: a região do registro.
  • ENDPOINT_NAME: o nome exclusivo que você quer dar ao endpoint, por exemplo, my-external-api.
  • DISPLAY_NAME: o nome legível do endpoint.
  • ENDPOINT_URL: o URL de destino, por exemplo, https://api.example.com/v1/data.
  • PROTOCOL: a vinculação de protocolo para a interface. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Registrar um endpoint de APIs compostas do Google

Em uma arquitetura entre projetos, um projeto de governança central hospeda a infraestrutura compartilhada, como o Agent Registry e o Gateway de Agente, e projetos de carga de trabalho individuais hospedam instâncias de computação de agente.

Quando você encaminha o tráfego do agente por Agent Gateway no modo de saída, o tráfego de rede de saída é bloqueado por padrão. Para permitir que os agentes em projetos de carga de trabalho se comuniquem com APIs essenciais Google Cloud , você pode agrupar várias interfaces de API em um único endpoint composto Service no projeto de governança central.

O agrupamento de interfaces em um único endpoint simplifica a administração de políticas, permitindo que você gerencie uma única vinculação de política de IAP para todo o conjunto de APIs principais do Google.

Siga estas etapas para registrar um endpoint de APIs compostas do Google:

gcloud

Registre o endpoint com vários URLs de interface no projeto de governança central:

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

Substitua:

  • SERVICE_NAME: o identificador do serviço, por exemplo, core-gapi-services.
  • CENTRAL_PROJECT_ID: o ID do projeto de governança central que hospeda o Agent Registry e o Gateway de Agente.
  • REGION: a região em que o gateway e o registro residem.
  • DISPLAY_NAME: o nome legível, por exemplo, Core Google APIs.
  • DESCRIPTION: uma breve descrição, por exemplo, Essential Google APIs for agent operations.
  • API_URL: o URL da API principal do Google, como https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: repita a flag --interfaces para cada URL ou variante adicional da API do Google exigida pelos seus agentes, como https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com ou variantes regionais e mTLS, como https://telemetry.mtls.googleapis.com.

Terraform

Para registrar o endpoint de APIs compostas do Google usando o Terraform, defina o recurso google_agent_registry_service com vários blocos 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"
  }
}

Substitua:

  • CENTRAL_PROJECT_ID: o ID do projeto de governança central.
  • REGION: a região do registro.
  • SERVICE_NAME: o ID do serviço.
  • DISPLAY_NAME: o nome legível.
  • DESCRIPTION: a descrição do serviço.
  • API_URL: o URL da API principal do Google, como https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: repita o bloco interfaces para cada URL ou variante adicional da API do Google exigida pelos seus agentes, como https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com ou variantes regionais e mTLS, como https://telemetry.mtls.googleapis.com.

A seguir