Google Cloudの外部でホストされているエージェント、サポートされていないランタイムで実行されているエージェント、異なる Google Cloud プロジェクトにデプロイされているエージェントについては、エージェント レジストリで手動登録が必要です。このドキュメントでは、エージェント レジストリにエージェントを手動で登録する方法について説明します。
始める前に
始める前に、エージェント レジストリを設定します。これらのタスクを行うには、プロジェクト ID が必要です。
このドキュメントの Google Cloud CLI コマンドを使用するには、gcloud CLI 環境を設定していることを確認してください。
必要なロール
Agent Registry にエージェントを手動で登録するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
Agent Registry にエージェントを登録するには: Agent Registry API 編集者 （
roles/agentregistry.editor） -
クロス プロジェクト登録で、リモート プロジェクトのエージェント メタデータにアクセスする: Agent Registry API 閲覧者 （
roles/agentregistry.viewer）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
エージェントのエンドポイントまたはエージェントカードに標準のパブリック URL を使用してアクセスできる場合や、事前に構成された認証情報で認証される場合は、追加の権限は必要ありません。
A2A 準拠のエージェントを登録する
リモート エージェントが Agent2Agent（A2A）仕様を実装している場合は、エージェントの agent-card.json ペイロードに Agent Registry を直接転送します。レジストリは、エージェント カードを自動的に同期し、検出用にエージェントの利用可能な A2A スキルをインデックス登録します。
エージェントを登録する手順は次のとおりです。
コンソール
Google Cloud コンソールで、[エージェント レジストリ] に移動します。
プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。
[エージェント] タブを選択します。
[エージェントを追加] をクリックします。
[エージェントの詳細] パネルで、次の詳細を入力します。
- タイプ: [A2A] を選択します。
- リージョン: エージェントを登録する地理的位置を選択します。
次のいずれかのオプションを選択します。
- リソース URI を使用してエージェントを登録するには、[URI から] タブを選択し、[URI] フィールドに有効な URL を入力します。[インポート] をクリックして、URL からエージェントカードを取得します。
- エージェント カードのコンテンツをコピーして貼り付けるには、[JSON を貼り付け] タブを選択し、
agent-card.jsonファイルの内容全体を貼り付けます。
[保存] をクリックします。
gcloud
A2A エージェントを登録するには、エージェントのエージェント カードをローカル JSON ファイル（agent-card.json など）として保存し、次の操作を行います。
gcloud agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=a2a-agent-card \
--agent-spec-content=@agent-card.json
仕様ファイルの最大ファイルサイズは 10 KB です。
次のように置き換えます。
AGENT_NAME: エージェントに付ける名前（例:my-support-agent）。PROJECT_ID: プロジェクト ID。REGION: エージェントを登録するリージョン。特定のリージョンを使用しない場合は、値globalを使用します。DISPLAY_NAME: エージェントに付ける人間が読める名前（Support Agentなど）。
Terraform
A2A 準拠のエージェントを登録するには、google_agent_registry_service リソースを構成します。A2A_AGENT_CARD 型と、エージェント カードの JSON ペイロードを表す content を含む agent_spec ブロックを指定します。
resource "google_agent_registry_service" "a2a_agent" {
location = "REGION"
service_id = "AGENT_NAME"
display_name = "DISPLAY_NAME"
agent_spec {
type = "A2A_AGENT_CARD"
content = jsonencode({
schemaVersion = "v1"
displayName = "DISPLAY_NAME"
description = "A custom support agent registered using Terraform."
skills = [
{
name = "customer_lookup"
description = "Looks up customer info by email address."
}
]
})
}
}
output "agent_resource_name" {
description = "The generated read-only Agent resource name."
value = google_agent_registry_service.a2a_agent.registry_resource
}
次のように置き換えます。
REGION: エージェントを登録するリージョン。AGENT_NAME: エージェントに付ける一意の名前（my-support-agentなど）。DISPLAY_NAME: エージェントに付ける人間が読める名前（Support Agentなど）。
標準 REST エージェントを登録する
標準の REST エージェントは名前と説明で検出できますが、A2A プロトコルを採用しない限り、検索可能な A2A スキルはありません。
標準の REST や SaaS API エンドポイントなど、A2A 仕様を実装していないリモート エージェントを登録する場合、Agent Registry API はエージェント プロトコル仕様のない Service リソースを作成します。
エージェントを登録する手順は次のとおりです。
コンソール
Google Cloud コンソールで、[エージェント レジストリ] に移動します。
プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。
[エージェント] タブを選択します。
[エージェントを追加] をクリックします。
[エージェントの詳細] パネルで、次の詳細を入力します。
- Type: [Non-A2A] を選択します。
- 名前: エージェントの人間が読める表示名（
Travel Agentなど）を入力します。 - 説明: エージェントの機能の説明を入力します（
A test agent that plans travel itineraries.など）。 - リージョン: エージェントを登録する地理的位置を選択します。
- エンドポイント: エージェントがホストされているエンドポイントを入力します。
[保存] をクリックします。
gcloud
必要に応じて、定義された HTTP/JSON エンドポイント インターフェースを --interfaces フラグで指定して、レジストリがエージェントとの接続を確立するようにできます。
標準の REST エージェントを登録する手順は次のとおりです。
gcloud agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=no-spec \
--interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
次のように置き換えます。
AGENT_NAME: エージェントに付ける名前（例:my-remote-rest-agent）。PROJECT_ID: プロジェクト ID。REGION: レジストリ リージョン。DISPLAY_NAME: エージェントに付ける人間が読める名前（Remote REST Agentなど）。ENDPOINT_URL: エージェントの API エンドポイント URL（例:https://api.remote-service.com/v1/agents/1234）。PROTOCOL: エンドポイントのプロトコル バインディング。有効な値はhttp-json、grpc、jsonrpcです。
Terraform
標準の REST エージェントを登録するには、agent_spec を NO_SPEC タイプに設定して google_agent_registry_service リソースを構成し、エンドポイント インターフェース接続を定義します。
resource "google_agent_registry_service" "rest_agent" {
location = "REGION"
service_id = "AGENT_NAME"
display_name = "DISPLAY_NAME"
description = "A standard REST agent registered using Terraform."
agent_spec {
type = "NO_SPEC"
}
interfaces {
url = "ENDPOINT_URL"
protocol_binding = "PROTOCOL"
}
}
output "agent_resource_name" {
description = "The generated read-only Agent resource name."
value = google_agent_registry_service.rest_agent.registry_resource
}
次のように置き換えます。
REGION: エージェントを登録するリージョン。AGENT_NAME: エージェントに付ける一意の名前（my-remote-rest-agentなど）。DISPLAY_NAME: エージェントに付ける人間が読める名前（Remote REST Agentなど）。ENDPOINT_URL: エージェントの API エンドポイント URL（例:https://api.remote-service.com/v1/agents/1234）。PROTOCOL: エンドポイントのプロトコル バインディング。有効な値はHTTP_JSON、GRPC、JSONRPCです。
別のプロジェクトからエージェントを登録する
組織が複数の Google Cloudプロジェクトにエージェントをデプロイし、中央の Agent Gateway を使用して下り（外向き）トラフィックを制御している場合は、スポーク プロジェクトまたはワークロード プロジェクトのエージェントを中央の Agent Registry カタログに登録できます。
自動登録では同じプロジェクトで作成されたリソースのみが検出されるため、各リモート エージェントを中央ガバナンス プロジェクトのレジストリに手動で登録する必要があります。
プロジェクト間の登録に関する考慮事項
プロジェクト間でエージェントを登録する前に、次の点を確認してください。
- 互換性のあるロケーション: Agent Registry インスタンス、Agent Gateway、エージェント エンドポイントは、同じ地理的リージョンまたは
globalロケーションに存在する必要があります。 - 自動検出の制限事項: プロジェクト間の自動検出は対象外です。各リモート エージェントを手動で登録する必要があります。
- ライフサイクル管理: リモート プロジェクトで変更が発生しても、エージェント レジストリの手動エントリは自動的に更新または削除されません。リモート エージェントが変更または削除された場合は、中央レジストリでこれらのエントリのライフサイクルを管理する必要があります。
- 下り（外向き）モードのみ: Agent Gateway を使用したクロス プロジェクト ガバナンスは、Agent-to-Anywhere（下り（外向き））ゲートウェイでのみサポートされます。クライアントからエージェントへの上り（内向き）ゲートウェイでは、エージェントとゲートウェイが同じプロジェクトに存在する必要があります。
リモート エージェントを登録する
別のプロジェクトからエージェントを手動で登録する手順は次のとおりです。
コンソール
Google Cloud コンソールで、[エージェント レジストリ] に移動します。
プロジェクト選択ツールから、エージェントを登録する中央ガバナンス プロジェクトを選択します。 Google Cloud
[エージェント] タブを選択します。
[エージェントを追加] をクリックします。
[エージェントの詳細] パネルで、次の詳細を入力します。
- タイプ: リモート エージェントが A2A プロトコルを実装している場合は [A2A] を選択し、標準の REST エンドポイントの場合は [Non-A2A] を選択します。
- リージョン: 中央ゲートウェイとリモート エージェントのデプロイに一致するリージョンを選択します。
エージェント エンドポイントを指定します。
- A2A エージェントの場合は、[URI から] を選択してリモート エージェントのエージェント カードの URL を入力するか、[JSON を貼り付け] を選択して
agent-card.jsonの内容を貼り付けます。 - A2A 以外のエージェントの場合は、リモート エージェントのエンドポイント URL を入力します。
- A2A エージェントの場合は、[URI から] を選択してリモート エージェントのエージェント カードの URL を入力するか、[JSON を貼り付け] を選択して
[保存] をクリックします。
gcloud
- A2A エージェント: gcloud CLI を使用して別のプロジェクトから A2A エージェントを登録するには、中央ガバナンス プロジェクトで次のコマンドを実行します。
gcloud agent-registry services create AGENT_NAME \
--project=CENTRAL_PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=a2a-agent-card \
--agent-spec-content=@agent-card.json
- REST エージェント: 別のプロジェクトから標準の REST エージェントを登録するには、中央ガバナンス プロジェクトで次のコマンドを実行します。
gcloud agent-registry services create AGENT_NAME \
--project=CENTRAL_PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=no-spec \
--interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL
次のように置き換えます。
AGENT_NAME: 中央レジストリ内のエージェントの名前（例:remote-support-agent）。CENTRAL_PROJECT_ID: 一元管理プロジェクトのプロジェクト ID。REGION: エージェントを登録するリージョン。DISPLAY_NAME: エージェントの人間が読める名前（例:Remote Support Agent）。REMOTE_ENDPOINT_URL: リモート プロジェクトで実行されているエージェントのエンドポイント URL（例:https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app）。PROTOCOL: エンドポイントのプロトコル バインディング。有効な値はhttp-json、grpc、jsonrpcです。
Terraform
Terraform を使用して中央ガバナンス プロジェクトにリモート エージェントを登録するには、google_agent_registry_service リソースを構成して中央プロジェクトを指定します。
resource "google_agent_registry_service" "remote_agent" {
project = "CENTRAL_PROJECT_ID"
location = "REGION"
service_id = "AGENT_NAME"
display_name = "DISPLAY_NAME"
description = "Remote agent registered from project REMOTE_PROJECT_ID."
agent_spec {
type = "NO_SPEC"
}
interfaces {
url = "REMOTE_ENDPOINT_URL"
protocol_binding = "PROTOCOL"
}
}
output "agent_resource_name" {
description = "The generated read-only Agent resource name."
value = google_agent_registry_service.remote_agent.registry_resource
}
次のように置き換えます。
CENTRAL_PROJECT_ID: 一元管理プロジェクトのプロジェクト ID。REGION: エージェントを登録するリージョン。AGENT_NAME: レジストリ内のエージェントの一意の名前（例:remote-support-agent）。DISPLAY_NAME: エージェントの人間が読める名前（例:Remote Support Agent）。REMOTE_PROJECT_ID: エージェントがホストされているプロジェクト ID。REMOTE_ENDPOINT_URL: リモート プロジェクトで実行されているエージェントのエンドポイント URL。PROTOCOL: エンドポイントのプロトコル バインディング。有効な値はHTTP_JSON、GRPC、JSONRPCです。
登録を確認する
エージェントを登録したら、Agent Registry が Service を正常に処理し、対応する Agent リソースを作成したことを確認します。
コンソール
Google Cloud コンソールで、[エージェント レジストリ] に移動します。
プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。
[エージェント] タブを選択します。
このページには、登録されているすべてのエージェントとその詳細が一覧表示されます。
gcloud
gcloud agent-registry agents list \
--project=PROJECT_ID \
--location=REGION
複数のエージェントがある場合や、単一のエージェントの登録を確認する場合は、エージェントのメタデータでリストをフィルタできます。
gcloud agent-registry agents list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
次のように置き換えます。
Terraform
google_agent_registry_agent データソースを使用して、他の Terraform 構成で登録済みエージェントを参照します。
data "google_agent_registry_agent" "my_agent" {
location = "REGION"
filter = "displayName=\"DISPLAY_NAME\""
}
output "agent_urn" {
value = data.google_agent_registry_agent.my_agent.urn
}
次のように置き換えます。
REGION: レジストリ リージョン。DISPLAY_NAME: エージェントの人が読める表示名。
次のステップ
- 登録代理人を管理する方法を確認する。
- マネージド ランタイムにデプロイされたエージェントを登録する場合に推奨される方法である自動登録について学習する。