注册端点

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

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

准备工作

开始之前，请先设置 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. 在项目选择器中，选择您在其中 设置了 Agent Registry的 Google Cloud 项目。

  3. 选择端点 标签页。

  4. 点击添加端点 。

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

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

  6. 点击保存 。

gcloud

您使用的规范标志决定了您的服务所属的资源集合。如需查看标志与资源集合的完整映射， 请参阅 API 资源。

您可以使用 endpoint-spec-type 为 no-spec 创建 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）决定了您的服务所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 API 资源。

如需注册外部端点，请使用 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），而各个工作负载项目托管代理计算实例。

当您以出站模式通过 代理网关 路由代理流量时，出站网络流量默认会被阻止。如需让 工作负载项目中的代理与基本 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 网址或变体重复 --interfaces 标志，例如 https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com 或区域和 mTLS 变体（例如 https://telemetry.mtls.googleapis.com）。

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 网址或变体重复 interfaces 块，例如 https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com 或区域和 mTLS 变体（例如 https://telemetry.mtls.googleapis.com）。

后续步骤