エンドポイントの登録

Agent Registry を使用すると、外部 REST API などのターゲット URL をマネージド エンドポイントとして手動で登録できます。これにより、エージェントのフリートが接続できる宛先を一元管理できます。

エンドポイントの登録は、us と eu のマルチリージョン ロケーションではサポートされていません。サポート対象の地域または global ロケーションを使用する必要があります。詳細については、Agent Registry のロケーションをご覧ください。

始める前に

  1. Agent Registry を設定する。

  2. Agent Registry が有効になっているガバナンス プロジェクトのプロジェクト ID を取得します。

  3. このドキュメントの Google Cloud CLI コマンドを使用するには、gcloud CLI 環境を設定します。

必要なロール

Agent Registry にエンドポイントを登録するために必要な権限を取得するには、Agent Registry が有効になっているガバナンス プロジェクトに対する Agent Registry API 編集者 （roles/agentregistry.editor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

エンドポイントを登録する

エンドポイントはカスタムの外部宛先であるため、手動登録を使用して Agent Registry に追加します。

コンソール

  1. Google Cloud コンソールで [Agent Registry] に移動します。

    Agent Registry に移動

  2. プロジェクト選択ツールから、Agent Registry を設定した Google Cloud プロジェクトを選択します。

  3. [エンドポイント] タブを選択します。

  4. [エンドポイントを追加] をクリックします。

  5. [エンドポイントの詳細] パネルで、表示名、説明、地理的リージョン、リンク先 URL を入力します。

    必要に応じて、このパネルの [接続をテスト] をクリックして、リンク先 URL への接続をテストします。

  6. [保存] をクリックします。

gcloud

使用する仕様フラグによって、コンポーネントが属するリソース コレクションが決まります。フラグとリソース コレクションの完全なマッピングについては、[サービス リソースと検出リソース](/agent-registry/data-model#service-resources)をご覧ください。

エンドポイントを Agent Registry に追加するには、gcloud agent-registry services create コマンドと --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）。名前は 4 ～ 63 文字で、英小文字、数字、ハイフンのみを使用できます。
  • PROJECT_ID: プロジェクト ID。
  • REGION: レジストリ リージョン。
  • DISPLAY_NAME: エンドポイントの人が読める形式の名前（例: My External API）。
  • ENDPOINT_URL: ターゲット URL（例: https://api.example.com/v1/data）。
  • PROTOCOL: インターフェースのプロトコル バインディング。有効な値は http-json、grpc、jsonrpc です。

Service リソースが作成されると、Agent Registry は、エージェントとオーケストレーターが検出して使用できる読み取り専用の Endpoint リソースを自動的に生成します。

Terraform

構成する仕様ブロックによって、コンポーネントが属するリソース コレクションが決まります。仕様とリソース コレクションの完全なマッピングについては、[サービス リソースと検出リソース](/agent-registry/data-model#service-resources)をご覧ください。

外部エンドポイントを登録するには、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）。名前は 4 ～ 63 文字で、英小文字、数字、ハイフンのみを使用できます。
  • DISPLAY_NAME: エンドポイントの人が読める形式の名前（例: My External API）。
  • ENDPOINT_URL: ターゲット URL（例: https://api.example.com/v1/data）。
  • PROTOCOL: インターフェースのプロトコル バインディング。有効な値は HTTP_JSON、GRPC、JSONRPC です。

複合 Google API エンドポイントを登録する

プロジェクトをまたぐアーキテクチャでは、一元管理されたガバナンス プロジェクトが Agent Registry や Agent Gateway などの共有インフラストラクチャをホストし、別の Google Cloud プロジェクトがエージェント コンピューティング インスタンスをホストします。

エージェント トラフィックを外向きモードの Agent Gateway 経由でルーティングすると、アウトバウンド ネットワーク トラフィックはデフォルトでブロックされます。別々の Google Cloud プロジェクトのエージェントが、必要なGoogle Cloud API と通信できるようにするには、中央ガバナンス プロジェクトで複数の API インターフェースを 1 つの複合 Service リソースにグループ化します。

インターフェースを 1 つのエンドポイントにグループ化すると、Google API のコアスイート全体に対して 1 つの Identity-Aware Proxy（IAP）ポリシー バインディングを管理できるため、ポリシー管理が簡素化されます。

複合 Google API エンドポイントを登録する手順は次のとおりです。

gcloud

gcloud agent-registry services create コマンドを使用して、中央ガバナンス プロジェクトに複数のインターフェース URL を持つエンドポイントを登録します。

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: サービスの ID（例: core-gapi-services）。名前は 4 ～ 63 文字にする必要があります。使用できるのは、小文字、数字、ハイフンのみです。
  • 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 の URL（https://telemetry.googleapis.com など）。
  • ADDITIONAL_API_URL: エージェントに必要な追加の Google API URL またはバリアント（https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com、https://telemetry.mtls.googleapis.com などのリージョン バリアントや mTLS バリアントなど）ごとに --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（例: core-gapi-services）。名前は 4 ～ 63 文字にする必要があります。使用できるのは、英小文字、数字、ハイフンのみです。
  • DISPLAY_NAME: 人が読める形式の名前（例: Core Google APIs）。
  • DESCRIPTION: エンドポイントの説明。
  • API_URL: プライマリ Google API の URL（https://telemetry.googleapis.com など）。
  • ADDITIONAL_API_URL: エージェントに必要な追加の Google API URL またはバリアント（https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com、https://telemetry.mtls.googleapis.com などのリージョン バリアントや mTLS バリアントなど）ごとに interfaces ブロックを繰り返します。

次のステップ