エージェント レジストリでエージェントを登録して管理するには、4 つのアーキテクチャ レイヤを操作します。各レイヤは、特定の命名、ID、またはルーティング メカニズムを使用します。
- レジストリ識別子（エージェント識別子、MCP サーバー識別子、エンドポイント識別子）: インベントリの追跡、レジストリの検出、フィルタリングに使用される論理的で不変の Uniform Resource Name（URN）。これらの URN はランタイム ガバナンスには使用されません。
- リソース名: 登録時に生成され、Agent Gateway ルートルール、Identity-Aware Proxy（IAP）下り（外向き）ポリシー、Identity and Access Management（IAM）ポリシー バインディングで使用される標準のグローバルに一意なGoogle Cloud
リソース名（
registryResourceまたはname）。 - エージェント プリンシパル: 呼び出し元の認証、認可、監査ロギングに使用される、Google Cloud で実行されているエージェントの SPIFFE ID や外部エージェントのサービス アカウントなど、検証可能な IAM ID。
- ランタイム参照: トポロジ クエリと下り（外向き）トラフィックのマッチングに使用されるコンピューティング パスまたはインフラストラクチャ パス（
RuntimeReference）。
次の表は、各レイヤ、その主な目的、ダウンストリームのガバナンス ロール、構文を比較したものです。
| 層 | 主な目的 | ガバナンス ロール | 構文 |
|---|---|---|---|
| レジストリ ID （エージェント、MCP サーバー、エンドポイントの ID） |
安定したレジストリ検出、メタデータのタグ付け、検索。 | 不変で、ガバナンスには使用されません。 |
|
| リソース名 | ポリシーの適用対象となるリソースの識別。 | ポリシーで必要とされ、Agent Gateway ルートと IAP バインディングで使用されます。 |
|
| エージェント プリンシパル | 呼び出し元の認証、認可、監査ロギング。 | IAM によって適用されます。 |
|
| ランタイム リファレンス | 物理コンピューティングのルーティングとアウトバウンド トラフィックのマッチング。 | トポロジ クエリと Agent Gateway で評価され、ネットワーク トラフィックと照合されます。 |
コンピューティング パスまたはインフラストラクチャ パスを uri: "RUNTIME_URI" として含む agentregistry.googleapis.com/system/RuntimeReference |
レジストリ識別子
レジストリ識別子は、Agent Registry が登録済みコンポーネントに割り当てるグローバルに一意の不変の Uniform Resource Name（URN）です。この URN は、基盤となるインフラストラクチャの移行やコードの更新に関係なく、コンシューマーとオーケストレーター エージェントが Agent Registry でコンポーネントを検出、フィルタ、検索するための安定した参照を提供します。
レジストリ識別子は、レジストリの検出とメタデータのアノテーションにのみ使用される論理 URN です。これらはランタイム セキュリティ ID やリソース名とは異なり、IAM ポリシー バインディング、認可ヘッダー、Agent Gateway ルートルールでは使用できません。
エージェント レジストリでは、次の 3 種類のレジストリ識別子が使用されます。
- エージェント ID（
agentId） - MCP サーバー識別子（
mcpServerId） - エンドポイント ID（
endpointId）
エージェント ID
Agent Registry は、Google 管理のエージェント、外部エージェント、カスタム エージェントなど、登録されているすべてのエージェントにエージェント識別子（agentId）を割り当てます。エージェントの安全なポリシー管理通信を管理するには、エージェント ID ではなく、エージェント プリンシパルを使用します。
エージェント レジストリは、取り込み時にエージェント識別子を自動的に生成します。URN の正確な構造は、エージェントがデプロイされているコンピューティング環境によって異なります。
- Gemini Enterprise Agent Platform の Agent Runtime:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID - Cloud Run サービス:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME - Cloud Run ジョブ:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME - GKE の Deployment:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME - Gemini Enterprise:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID - Google Workspace:
urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a - 手動で登録されたエージェント:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID
MCP サーバー識別子
MCP サーバー識別子（mcpServerId）は、Agent Registry で MCP サーバーとそのツールを検出するために使用されるレジストリ識別子です。
MCP サーバーはリクエストにのみ応答し、IAM プリンシパルはありません。エージェントが MCP サーバーでツールを呼び出すと、呼び出し元のエージェント プリンシパルを使用してアクセスが承認されます。
URN の形式は、サーバーが Google マネージド サービスか、外部の登録済みサーバーかによって異なります。
- Google と Google Cloud リモート MCP サーバー:
urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID - 手動で登録された MCP サーバー:
urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID
エンドポイント識別子
エンドポイント識別子（endpointId）は、ターゲット API の宛先を検出するために登録済みエンドポイントに割り当てられたレジストリ識別子です。
手動で登録されたエンドポイントの URN 形式は urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID です。
リソース名
Agent Registry にエージェント、MCP サーバー、エンドポイントを登録すると、登録プロセスによって、階層 URI パスとしてフォーマットされた標準の Google Cloud リソース名が生成されます。
- エージェント:
projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID - MCP サーバー:
projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID - エンドポイント:
projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID
書き込み可能な Service リソースを作成または検査すると（たとえば、gcloud agent-registry services describe を実行するなど）、このリソース名は出力専用の registryResource フィールドで返されます。たとえば gcloud agent-registry agents describe コマンドを使用して、結果の読み取り専用 Agent、McpServer、Endpoint リソースを直接クエリまたは検査すると、このリソース名が標準の name フィールドで返されます。
リソース名を使用して、ポリシーのバインド、ネットワーク トラフィックのルーティング、アクセス制御の構成を行うことができます。Agent Gateway ルートルール、IAP 下り（外向き）ポリシー、IAM リソースポリシーなどのダウンストリーム ガバナンス サーフェスは、このリソース名に対して評価されます。エージェント識別子、MCP サーバー識別子、エンドポイント識別子などのレジストリ識別子からの URN は受け入れません。
ポリシー バインディングまたはルートルールでリソース名の代わりにレジストリ ID URN を使用すると、API は NOT_FOUND: Requested entity was not found. エラーを返します。ガバナンス ポリシーの構成時にこのエラーが発生した場合は、次のことを確認してください。
- 登録ステータス: ターゲット エージェント、MCP サーバー、エンドポイントが Agent Registry の想定される場所に登録されていることを確認します。
- 識別子の形式: ポリシー バインディングまたはルートルールで、レジストリ識別子 URN ではなく標準リソース名（
projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID）が指定されていることを確認します。
エージェント プリンシパル
エージェント プリンシパルは、IAM におけるエージェントのセキュリティ ID です。ユーザー アカウントやサービス アカウントと同様に、エージェントはプリンシパルを使用して権限を保持し、ダウンストリーム サービスを呼び出します。IAM ポリシーを構成する場合は、エージェントのプリンシパル文字列を使用してアクセス権を付与または制限します。
Agent Registry でエージェントがプリンシパルとして識別される方法は、エージェントの実行場所によって異なります。
- インフラストラクチャで実行されるエージェント Google Cloud : Gemini Enterprise Agent Platform の Agent Runtime などのマネージド ランタイムの場合、 Google CloudSPIFFE ID としてフォーマットされたマネージド Workload Identity が自動的にプロビジョニングされ、エージェントのコンピュート ランタイムに直接バインドされます。IAM 許可ポリシーとバインディングでこの ID を参照する場合は、SPIFFE URI スキームではなく、IAM プリンシパルまたはプリンシパル セットの文字列形式を使用する必要があります。IAM ポリシー バインディングに SPIFFE 文字列を使用すると、
INVALID_ARGUMENTエラーが返されます。 - Google Cloudの外部で実行されているエージェント: 外部エージェントまたはオンプレミス エージェントは、Workload Identity 連携を介して外部 ID を連携するか、標準のサービス アカウントを使用して Google Cloud リソースとやり取りする必要があります。認証されると、そのフェデレーション Workload Identity 文字列またはサービス アカウントのメールアドレスが IAM ポリシーのエージェント プリンシパルとして機能します。
Google Cloudで実行されているエージェントの場合、マネージド エージェント プリンシパルはエージェントのランタイムのコンピューティング リソースに直接バインドされるため、プリンシパル文字列にはその基盤となるコンピューティング リソースの完全パスが組み込まれます。
IAM は、次のスコープ全体でエージェント アクセスの制御をサポートしています。
- 単一エンジン インスタンス: 特定のエージェント デプロイに権限を付与します。たとえば、個々の Agent Runtime インスタンスは、単一のプリンシパル文字列で表されます。
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID - プロジェクト スコープ: プリンシパル セットを介して、特定のプロジェクト内で実行されているすべての推論エンジンに権限を付与します。
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER - 組織全体のスコープ: プリンシパル セットのワイルドカード
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*を使用して、組織全体のすべてのエージェントに権限を付与します。
エージェントの詳細を表示すると、Agent Registry に個々のエージェント プリンシパルが出力専用の属性として表示されます。
ランタイム参照
ランタイム参照は、エージェント、MCP サーバー、エンドポイントのコードが実行される基盤となるコンピューティング インフラストラクチャを指します。たとえば、ランタイム参照は、Agent Runtime 推論エンジン、GKE デプロイ、Cloud Run サービスを指すことができます。
エージェントのプリンシパル文字列には、ランタイム参照パスが含まれています。これにより、IAM 権限がエージェントの実行場所に直接関連付けられます。エージェントをデプロイ先とは異なるプロジェクトに登録すると、ランタイム参照は基盤となるワークロードをホストするプロジェクトを指します。
Agent Registry API では、ランタイム参照は agentregistry.googleapis.com/system/RuntimeReference 属性で表されます。この属性の uri フィールドには、コンピューティングまたはインフラストラクチャのパスが含まれています。この出力専用属性は、エージェントの詳細の一部として表示するか、トポロジ グラフでトラフィック フローと関係をクエリするために使用できます。
次のステップ
- ロールと権限について学習する。
- エージェントの管理と検査。
- エージェント レジストリのデータモデルについて理解する。
- 一般的な主なコンセプトを確認する。