注册端点

在 Agent Registry 中，端点表示代理访问的目标网址（通常是 REST API）。通过在 Agent Registry 中将这些目的地注册为受管理的智能体组件，您可以集中管理智能体舰队可以连接到的外部端点。

本文档介绍了如何在注册表中显式注册外部端点。

准备工作

开始之前，请先设置代理注册表。您需要项目 ID 才能执行这些任务。

如需使用本文档中的 Google Cloud CLI 命令，请确保您已设置 gcloud CLI 环境。

所需的角色

如需获得在代理注册表中注册端点所需的权限，请让您的管理员为您授予项目的 Agent Registry API Editor (roles/agentregistry.editor) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注册端点

由于端点是自定义的外部目的地，因此请使用手动注册将其添加到 Agent Registry：

控制台

  1. 在 Google Cloud 控制台中，前往 Agent Registry：

    前往 Agent Registry

  2. 在项目选择器中，选择 Google Cloud 项目，您在其中设置 Agent Registry。

  3. 选择端点标签页。

  4. 点击添加端点。

  5. 在端点详情面板中，输入显示名称、说明、地理区域和目标网址。

    （可选）点击此面板中的测试连接，以测试与目标网址的连接。

  6. 点击保存。

gcloud

您可以使用 no-spec 的 endpoint-spec-type 创建 Service 资源。

注册端点并定义其接口连接详细信息：

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

替换以下内容：

  • ENDPOINT_NAME：您要为端点指定的名称，例如 my-external-api。
  • PROJECT_ID：项目 ID。
  • REGION：注册区域。
  • DISPLAY_NAME：端点的直观易懂的名称。
  • ENDPOINT_URL：目标网址，例如 https://api.example.com/v1/data。
  • PROTOCOL：接口的协议绑定。 有效值为 http-json、grpc 或 jsonrpc。

创建 Service 资源后，Agent Registry 会在使用方自动生成只读 Endpoint 资源，供智能体和编排器发现和使用。

Terraform

如需注册外部端点，请使用 endpoint_spec 块配置 google_agent_registry_service 资源：

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
}

替换以下内容：

  • REGION：注册区域。
  • ENDPOINT_NAME：您要为端点指定的唯一名称，例如 my-external-api。
  • DISPLAY_NAME：端点的直观易懂的名称。
  • ENDPOINT_URL：目标网址，例如 https://api.example.com/v1/data。
  • PROTOCOL：接口的协议绑定。 有效值为 HTTP_JSON、GRPC 或 JSONRPC。

注册复合 Google API 端点

在跨项目架构中，中央治理项目托管共享基础设施（例如 Agent Registry 和 Agent Gateway），而各个工作负载项目托管代理计算实例。

在出站模式下，当您通过 Agent Gateway 路由代理流量时，出站网络流量默认会被阻止。为了让工作负载项目中的代理与必要的 Google Cloud API 进行通信，您可以在中央治理项目中将多个 API 接口分组到一个复合 Service 端点中。

通过将接口分组到一个端点中，您可以为整套核心 Google API 管理单个 IAP 政策绑定，从而简化政策管理。

如需注册复合 Google API 端点，请按以下步骤操作：

gcloud

在中央治理项目中注册具有多个接口网址的端点：

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

替换以下内容：

  • SERVICE_NAME：服务的标识符，例如 core-gapi-services。
  • CENTRAL_PROJECT_ID：托管 Agent Registry 和 Agent Gateway 的中央治理项目的项目 ID。
  • REGION：网关和注册表所在的区域。
  • DISPLAY_NAME：人类可读的名称，例如 Core Google APIs。
  • DESCRIPTION：简要说明，例如 Essential Google APIs for agent operations。
  • API_URL：主要 Google API 的网址，例如 https://telemetry.googleapis.com。
  • ADDITIONAL_API_URL：针对代理所需的每个额外的 Google API 网址或变体（例如 https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com 或区域和 mTLS 变体，如 https://telemetry.mtls.googleapis.com），重复使用 --interfaces 标志。

Terraform

如需使用 Terraform 注册复合 Google API 端点，请定义包含多个 interfaces 块的 google_agent_registry_service 资源：

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

替换以下内容：

  • CENTRAL_PROJECT_ID：中央治理项目的项目 ID。
  • REGION：注册区域。
  • SERVICE_NAME：服务 ID。
  • DISPLAY_NAME：直观易懂的名称。
  • DESCRIPTION：服务说明。
  • API_URL：主要 Google API 的网址，例如 https://telemetry.googleapis.com。
  • ADDITIONAL_API_URL：针对代理所需的每个额外的 Google API 网址或变体（例如 https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com 或区域性变体和 mTLS 变体，如 https://telemetry.mtls.googleapis.com），重复 interfaces 代码块。

后续步骤