Registrar endpoints

O Agent Registry permite registrar manualmente URLs de destino, como APIs REST externas, como endpoints gerenciados, para que você possa controlar de forma centralizada os destinos aos quais sua frota de agentes pode se conectar.

É possível registrar endpoints em uma região com disponibilidade compatível, em uma multirregião compatível ou no local global. Para mais informações sobre os locais compatíveis, consulte Locais do Agent Registry.

Antes de começar

  1. Configure o Agent Registry.

  2. Para uma configuração de projeto único, use o ID do projeto do projeto de governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações de projeto único.

  3. Para usar os comandos da Google Cloud CLI neste documento, configure 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 Agent Registry (roles/agentregistry.editor) no projeto de governança em que o Agent Registry está ativado. 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 usando 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 console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto do Google Cloud 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.

    Se quiser, clique em Testar conexão nesse painel para testar sua conexão com o URL de destino.

  6. Clique em Salvar.

gcloud

As flags de especificação usadas determinam a qual coleção de recursos seu componente pertence. Para um mapeamento completo de flags para coleções de recursos, consulte [Recursos de serviço e recursos de descoberta](/agent-registry/data-model#service-resources).

Para adicionar o endpoint ao Agent Registry, crie um recurso Service com o comando gcloud agent-registry services create e a flag --endpoint-spec-type definida como 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

Substitua:

  • ENDPOINT_NAME: o nome que você quer dar ao endpoint, por exemplo, my-external-api. O nome precisa ter de 4 a 63 caracteres e pode conter apenas letras minúsculas, números e hifens.
  • PROJECT_ID: o ID do projeto;
  • REGION: a região do registro.
  • DISPLAY_NAME: o nome legível por humanos do endpoint, por exemplo, My External API.
  • ENDPOINT_URL: o URL de destino, por exemplo, https://api.example.com/v1/data.
  • PROTOCOL: a vinculação de protocolo da 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 que os agentes e orquestradores podem descobrir e usar.

Terraform

O bloco de especificação que você configura determina a qual coleção de recursos seu componente pertence. Para um mapeamento completo de especificações para coleções de recursos, consulte [Recursos de serviço e recursos de descoberta](/agent-registry/data-model#service-resources).

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. O nome precisa ter de 4 a 63 caracteres e pode conter apenas letras minúsculas, números e hifens.
  • DISPLAY_NAME: o nome legível por humanos do endpoint, por exemplo, My External API.
  • ENDPOINT_URL: o URL de destino, por exemplo, https://api.example.com/v1/data.
  • PROTOCOL: a vinculação de protocolo da interface. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Registrar um endpoint de API composto do Google

Em uma arquitetura de vários projetos, um projeto de governança central hospeda a infraestrutura compartilhada, como o registro de agentes e o gateway de agente, e projetos separados do Google Cloud hospedam instâncias de computação do agente.

Quando você roteia o tráfego do agente pelo Gateway de Agente no modo de saída, o tráfego de rede de saída é bloqueado por padrão. Para permitir que os agentes em projetos do Google Cloud separados se comuniquem com as APIs essenciais do Google Cloud , é possível agrupar várias interfaces de API em um único recurso composto do Service no projeto de governança central.

Agrupar interfaces em um único endpoint simplifica a administração de políticas, permitindo que você gerencie uma única vinculação de política do Identity-Aware Proxy (IAP) para todo o conjunto de APIs principais do Google.

Siga estas etapas para registrar um endpoint de API composto do Google:

gcloud

Registre o endpoint com vários URLs de interface no projeto de governança central usando o 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

Substitua:

  • SERVICE_NAME: o identificador do serviço, por exemplo, core-gapi-services. O nome precisa ter de 4 a 63 caracteres e pode conter apenas letras minúsculas, números e hifens.
  • 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 estão.
  • DISPLAY_NAME: o nome legível por humanos, 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 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 API composto 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, por exemplo, core-gapi-services. O nome precisa ter de 4 a 63 caracteres e pode conter apenas letras minúsculas, números e hifens.
  • DISPLAY_NAME: o nome legível por humanos, por exemplo, Core Google APIs.
  • DESCRIPTION: a descrição do endpoint.
  • 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 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