エンドポイントの登録

Agent Registry では、エンドポイントは、エージェントがアクセスするターゲット URL（ 通常は REST API）を表します。これらの宛先を Agent Registry 内でマネージド エージェント コンポーネントとして登録することで、エージェントのフリートが接続できる外部エンドポイントを一元的に管理できます。

このドキュメントでは、レジストリに外部エンドポイントを明示的に登録する方法について説明します。

始める前に

始める前に、Agent Registry を設定します。これらのタスクを行うには、 プロジェクト IDが 必要です。

このドキュメントの Google Cloud CLI コマンドを使用するには、gcloud CLI 環境を 設定していることを確認してください。

必要なロール

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

使用する仕様フラグによって、サービスが属するリソース コレクションが決まります。フラグとリソース コレクションの完全なマッピングについては、 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: ターゲット 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: ターゲット URL（https://api.example.com/v1/data など）。
  • PROTOCOL: インターフェースのプロトコル バインディング。 有効な値は HTTP_JSON、GRPC、JSONRPC です。

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

クロスプロジェクト アーキテクチャでは、中央ガバナンス プロジェクトが Agent Registry や Agent Gateway などの共有インフラストラクチャをホストし、個々のワークロード プロジェクトがエージェント コンピューティング インスタンスをホストします。

エージェント トラフィックを下り（外向き）モードで Agent Gateway を介してルーティングすると、デフォルトで下り（外向き）ネットワーク トラフィックがブロックされます。ワークロード プロジェクトのエージェントが重要な Google Cloud API と通信できるようにするには、中央ガバナンス プロジェクトで複数の API インターフェースを 1 つの複合 Service エンドポイントにグループ化します。

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

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

gcloud

中央ガバナンス プロジェクトで、複数のインターフェース 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 など）。
  • 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 またはバリアントごとに --interfaces フラグを繰り返します（https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com、または https://telemetry.mtls.googleapis.com などのリージョン バリアントと mTLS バリアント）。

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 の URL（https://telemetry.googleapis.com など）。
  • ADDITIONAL_API_URL: エージェントに必要な追加の Google API URL またはバリアントごとに interfaces ブロックを繰り返します（https://cloudresourcemanager.googleapis.com、https://iamcredentials.googleapis.com、https://agentregistry.googleapis.com、または https://telemetry.mtls.googleapis.com などのリージョン バリアントと mTLS バリアント）。

次のステップ