マルチエージェント システムを構築して A2A エージェントを呼び出す

マルチエージェント システムでは、オーケストレーター エージェントが、特化したターゲット エージェントとツールにタスクを委任します。これらのターゲット エージェントは、マルチエージェント システムまたはアプリケーションのサブエージェントになります。

Agent Registry を使用すると、オーケストレーター エージェントは、アプリケーション コードにサービス URL をハードコードすることなく、実行時に Agent2Agent(A2A)エンドポイントと Model Context Protocol(MCP)エンドポイントを動的に検索できます。Agent Development Kit(ADK)の AgentRegistry クライアント、または標準の HTTP ライブラリと google-auth ライブラリを使用して、登録済みエージェントと MCP サーバーを取得し、オーケストレーター エージェントを構築できます。

オーケストレーター エージェントがターゲット エージェントのエンドポイントを呼び出すと、リクエストがターゲット エージェントのランタイムまたは MCP サーバーに直接送信されます。セキュリティ ポリシーを適用し、プロトコル メディエーションを実行して、ターゲット エージェント エンドポイントにコンテンツ フィルタリングを適用するには、Agent Gateway を介してエージェント呼び出しをルーティングします。

始める前に

ターゲット Agent Endpoint URL を検索したり、Agent Registry を介して A2A エージェントを呼び出したりする前に、次の手順を完了します。

  1. Agent Registry を設定する。
  2. 単一プロジェクトの設定の場合は、Agent Registry が有効になっているガバナンス プロジェクトのプロジェクト ID を取得します。複数のプロジェクトに管理境界を構成した場合は、境界全体の検出と登録に管理プロジェクトの ID を使用するか、単一プロジェクトのオペレーションにメンバー プロジェクト ID を指定します。

  3. フレームワークのクライアント依存関係をインストールします。

    ADK(pip)

    pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
    

    google-adk>=1.29.0 以上をインストールする必要があります。

    ADK(uv)

    uv add "google-adk[a2a,agent-identity,mcp]"
    

    google-adk>=1.29.0 以上をインストールする必要があります。

    ADK 以外の Python

    pip install --upgrade google-auth requests httpx
    
  4. ローカル開発用にアプリケーションのデフォルト認証情報(ADC)を構成します。それ以外の場合は、外部環境でサービス アカウントまたは Workload Identity 連携の認証情報構成を接続します。

    gcloud auth application-default login
    
  5. 次の環境変数を設定します。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=LOCATION
    

    次のように置き換えます。

必要なロール

ローカル開発にユーザー アカウントを使用することも、オーケストレーター エージェントにサービス アカウントまたはエージェント プリンシパルを使用して、登録済みのコンポーネントを検出し、ターゲット A2A エージェントを呼び出すこともできます。ユーザー アカウント、サービス アカウント、またはエージェント プリンシパルには、コンポーネントを検出し、ターゲット A2A エージェントを呼び出すための適切なロールが必要です。

登録済みのコンポーネントを検出し、ターゲット A2A エージェントを呼び出すために必要な権限がユーザー アカウント、サービス アカウント、またはエージェント プリンシパルに付与されるように、Agent Registry が有効になっているガバナンス プロジェクトで、ユーザー アカウント、サービス アカウント、またはエージェント プリンシパルに次の IAM ロールを付与するよう管理者に依頼してください。

  • 登録済みのエージェントと MCP サーバーを検出する: Agent Registry API 閲覧者(roles/agentregistry.viewer)
  • ランタイムにターゲット A2A エージェントを呼び出すには: ターゲット エージェントをホストするサービスのランタイム ロールまたはゲートウェイ ロール。このエージェントを呼び出すために必要です。たとえば、ターゲット エージェントが Cloud Run で実行されている場合、アカウントまたはプリンシパルには Cloud Run 起動元ロール(roles/run.invoker)が必要です。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、必要な権限をユーザー アカウント、サービス アカウント、またはエージェント プリンシパルに付与することもできます。

ターゲット A2A エージェント Agent Endpoint の認証情報を選択する

Agent Registry でコンポーネントを検索し、そのターゲット A2A エージェント Agent Endpoint を呼び出すには、個別の認証トークンが必要です。オーケストレーター エージェントがターゲット A2A エージェント エンドポイントを呼び出す場合は、そのエンドポイントで想定される署名なしトークン タイプを添付する必要があります。

ターゲット A2A エージェント エンドポイント 必要な署名なしトークン クルデンシャルのソースとガイド
Google Cloud API エージェント エンドポイント(https://*.googleapis.com) https://www.googleapis.com/auth/cloud-platform スコープまたはより狭いサービス スコープを持つ OAuth 2.0 アクセス トークン。デフォルトの割り当てプロジェクトが構成されていないアプリケーションのデフォルト認証情報(ADC)を使用する場合は、X-Goog-User-Project ヘッダーを含めて、API 割り当ての課金対象となるプロジェクトを指定します。詳細については、REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。 google.auth.default()。アプリケーションのデフォルト認証情報(ADC)、関連付けられたサービス アカウント、または Workload Identity 連携認証情報構成を使用します。呼び出しごとに権限を制限するには、サービス アカウントの権限借用を使用するをご覧ください。
Cloud Run または Identity-Aware Proxy(IAP)の HTTPS エージェント エンドポイント(https://*.run.app またはカスタム ドメイン) aud クレームがターゲット サービスの URL または IAP OAuth 2.0 クライアント ID と一致する ID トークン。 google.oauth2.id_token.fetch_id_token()。サービス アカウントまたはコンピューティング メタデータ サーバーを使用します。設定手順については、ID トークンを取得する、Cloud Run でのサービス間認証、IAP のプログラムによる認証をご覧ください。
OAuth にバインドされた外部エージェントまたは SaaS エージェント 2-legged OAuth 2.0 トークン、3-legged OAuth 2.0 トークン、または API キー。 Agent Identity Auth Manager バインディングがエージェントに接続されている場合、ADK で自動的に管理されます。設定手順については、ツールとリソースの認証をご覧ください。

ADK で AgentRegistry クライアントを初期化する

ADK を介して Agent Registry を操作するには、Python コードで AgentRegistry クライアントをガバナンス プロジェクト ID と Agent Registry のロケーションで初期化します。

import os
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

ADK AgentRegistry クライアントを初期化すると、Agent Registry からリモート A2A エージェントとリモート MCP ツールを取得できます。ADK では、登録された A2A エージェントは RemoteA2aAgent インスタンスとしてラップされます。これらのインスタンスは、ADK がローカル プロセスで実行するのではなく、ネットワーク経由でタスクを委任するため、リモート エージェントと呼ばれます。同様に、登録済みのリモート MCP サーバーは McpToolset インスタンスとしてラップされます。

ADK を使用してマルチエージェント システムを構成する

Agent Registry からリモート A2A サブエージェントとリモート MCP ツールセットを取得し、LlmAgent オーケストレーター エージェント定義に含めるには、初期化された AgentRegistry クライアントを使用します。

  • リモート A2A エージェントを取得する: サブエージェントの相対リソース名を指定して registry.get_remote_a2a_agent() を呼び出します。このリソース名は、AgentRegistry クライアントで構成されたプロジェクト ID とロケーションを使用する agents/AGENT_ID 形式の相対リソース名か、projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID 形式の完全なリソース名のいずれかです。エージェントに認証マネージャー Binding が存在する場合、get_remote_a2a_agent() はリクエスト認証情報を自動的に構成します。Binding が存在しない場合は、httpx.Auth ハンドラで構成されたカスタム httpx_client を渡します。
  • リモート MCP ツールセットを取得する: MCP サーバーの相対リソース名(mcpServers/SERVER_ID)または完全なリソース名(projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID)を指定して registry.get_mcp_toolset() を呼び出します。

次の例は、ADK agent.py ファイルでオーケストレーター エージェントを定義する方法を示しています。このサンプルでは、次の点を考慮してください。

  • GoogleApiAuth クラスは、Google Cloud API(https://*.googleapis.com)A2A サブエージェントを呼び出すための httpx.Auth ハンドラを実装します。google.auth.default() を使用して、アプリケーションのデフォルト認証情報、接続されたサービス アカウント、または Workload Identity 連携の認証情報を読み込み、各リクエストに Authorization ヘッダーと X-Goog-User-Project ヘッダーを設定します。

  • registry クライアントは、Agent Registry からリモート A2A サブエージェントとリモート MCP ツールセットを取得し、sub_agents パラメータと tools パラメータを介して LlmAgent に渡します。

import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent

class GoogleApiAuth(httpx.Auth):
    def __init__(self, user_project_id: str):
        self.user_project_id = user_project_id
        self.creds, _ = google.auth.default(
            scopes=["https://www.googleapis.com/auth/cloud-platform"]
        )

    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        request.headers["X-Goog-User-Project"] = self.user_project_id
        yield request

quota_project_id = "QUOTA_PROJECT_ID"
agent_name = "agents/AGENT_ID"
httpx_client = httpx.AsyncClient(
    auth=GoogleApiAuth(quota_project_id),
    timeout=httpx.Timeout(60.0),
)
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client,
)

mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

root_agent = LlmAgent(
    model="MODEL_ID",
    name="travel_orchestrator",
    instruction=(
        "You are a travel coordinator. Use your subagents to book travel "
        "and your tools to query historical travel data."
    ),
    tools=[my_mcp_toolset],
    sub_agents=[my_remote_agent],
)

次のように置き換えます。

  • QUOTA_PROJECT_ID:Google Cloud Agent Endpoint へのリクエストの割り当てと課金属性に使用されるプロジェクト ID。
  • AGENT_ID: オーケストレーター エージェントが呼び出す登録済み A2A サブエージェントの ID(例: agentregistry-01234456-7890-abcd-1234-567890abcdef)。
  • SERVER_ID: オーケストレーター エージェントで使用する登録済み MCP サーバーの ID。
  • MODEL_ID: オーケストレーター エージェントのモデル ID(例: gemini-2.5-flash)。

ADK プロジェクトの agent.py ファイルに root_agent を保存したら、adk run または adk web CLI コマンドを使用してオーケストレーター エージェントをローカルでテストして実行するか、Gemini Enterprise Agent Platform の Agent Runtime にデプロイできます。プロジェクトの完全な構造と実行手順については、ADK Python クイックスタートと GitHub の ADK Agent Registry サンプルをご覧ください。

ADK 以外のクライアントから A2A エージェントを呼び出す

ADK を使用せずにカスタム オーケストレーター エージェントまたはクライアントを構築する場合、アプリケーションは次の 2 つの認証ステップを実行します。

  1. 検出: OAuth 2.0 アクセス トークンを使用して Agent Registry API で認証し、ターゲット サブエージェントの Agent リソースを取得して、そのエージェント カードを検査します。
  2. ランタイム呼び出し: ターゲット Agent Endpoint に必要な署名なしトークンをアタッチします。これは、*.googleapis.com Agent Endpoint の OAuth 2.0 アクセス トークン、または Cloud Run と IAP Agent Endpoint の OIDC ID トークンです。次に、A2A SendMessage リクエストを送信します。出力は SendMessageResponse JSON オブジェクトを返します。このオブジェクトには、{"task": ...} 形式または {"message": ...} 形式の task フィールドまたは message フィールドが含まれています。このフィールドには、オーケストレーター エージェントが解析してワークフローで使用できるサブエージェントのレスポンスが含まれます。

google-auth と httpx を使用して、登録済みの A2A サブエージェントを検索して呼び出す手順は次のとおりです。

  1. OAuth 2.0 アクセス トークンを使用して Agent Registry で認証し、Agent Registry API からサブエージェントの Agent リソースを取得します。

    import os
    import uuid
    from urllib.parse import urlparse
    import google.auth
    from google.auth.transport.requests import Request
    from google.oauth2 import id_token
    import httpx
    
    project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
    location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
    agent_id = "AGENT_ID"
    
    creds, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    creds.refresh(Request())
    
    registry_url = (
        f"https://agentregistry.googleapis.com/v1/projects/{project_id}"
        f"/locations/{location}/agents/{agent_id}"
    )
    client = httpx.Client(timeout=60.0)
    reg_response = client.get(
        registry_url,
        headers={
            "Authorization": f"Bearer {creds.token}",
            "X-Goog-User-Project": project_id,
        },
    )
    reg_response.raise_for_status()
    agent_resource = reg_response.json()
    

    AGENT_ID は、呼び出す登録済み A2A サブエージェントの ID(agentregistry-01234456-7890-abcd-1234-567890abcdef など)に置き換えます。

  2. Agent リソースのエージェント カードから HTTP ベースの A2A インターフェースを抽出します。

    card = agent_resource.get("card", {}).get("content", {})
    interfaces = card.get("supportedInterfaces") or (
        (agent_resource.get("protocols") or [{}])[0].get("interfaces", [])
    )
    iface = next(
        i for i in interfaces
        if i.get("protocolBinding", "HTTP+JSON")
        in ("HTTP+JSON", "HTTP_JSON", "JSONRPC")
    )
    endpoint_url = iface["url"]
    binding = iface.get("protocolBinding", "HTTP+JSON")
    tenant = iface.get("tenant", "")
    
  3. *.googleapis.com Agent Endpoint 用の OAuth 2.0 アクセス トークンまたは Cloud Run または IAP Agent Endpoint 用の OIDC ID トークンを使用してリクエスト ヘッダーを準備します。

    host = urlparse(endpoint_url).hostname or ""
    headers = {"Content-Type": "application/json", "A2A-Version": "1.0"}
    if host == "googleapis.com" or host.endswith(".googleapis.com"):
        headers["Authorization"] = f"Bearer {creds.token}"
        headers["X-Goog-User-Project"] = project_id
    else:
        oidc_audience = f"https://{host}"
        oidc_jwt = id_token.fetch_id_token(Request(), oidc_audience)
        headers["Authorization"] = f"Bearer {oidc_jwt}"
    
  4. エージェント カードのプロトコル バインディングを使用して A2A SendMessage リクエストをフォーマットして送信し、サブエージェントからのレスポンスを解析します。

    message = {
        "messageId": str(uuid.uuid4()),
        "role": "ROLE_USER",
        "parts": [{"text": "Summarize recent deployment status."}],
    }
    if binding == "JSONRPC":
        params = {"message": message}
        if tenant:
            params["tenant"] = tenant
        payload = {
            "jsonrpc": "2.0",
            "id": str(uuid.uuid4()),
            "method": "SendMessage",
            "params": params,
        }
        target_url = endpoint_url
    else:
        payload = {"message": message}
        prefix = f"/{tenant.strip('/')}" if tenant else ""
        target_url = f"{endpoint_url.rstrip('/')}{prefix}/message:send"
    
    response = client.post(target_url, headers=headers, json=payload)
    response.raise_for_status()
    body = response.json()
    if binding == "JSONRPC":
        if "error" in body:
            raise RuntimeError(f"JSON-RPC error: {body['error']}")
        send_message_response = body["result"]
    else:
        send_message_response = body
    print(send_message_response)
    client.close()
    

    このステップでは、A2A バージョン 1.0 の SendMessage リクエストをフォーマットします。A2A プロトコル バージョン 1.0 と 0.3 の間で自動的にネゴシエーションを行う必要がある場合は、ADK または a2a-sdk Python クライアントを使用します。

ADK でオーケストレーター エージェント間でリモート エージェントを再利用する

ネットワーク レイテンシを最小限に抑えるには、リクエストごとに get_remote_a2a_agent() を呼び出すのではなく、アプリケーションの起動時に Agent Registry からリモート エージェントとツールセットを 1 回取得します。

ADK では、RemoteA2aAgent インスタンスが一度に持つことができる親オーケストレーター エージェントは 1 つだけです。初期化の設定から、.clone() を呼び出して、親オーケストレーター エージェントごとに独立したコピーを作成します。

agent_path = (
    f"projects/{project_id}/locations/{location}"
    "/agents/AGENT_ID"
)
base_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_path,
    httpx_client=httpx_client,
)

flight_orchestrator = LlmAgent(
    model="gemini-2.5-flash",
    name="flight_orchestrator",
    sub_agents=[base_remote_agent.clone()],
)

hotel_orchestrator = LlmAgent(
    model="gemini-2.5-flash",
    name="hotel_orchestrator",
    sub_agents=[base_remote_agent.clone()],
)

AGENT_ID は、オーケストレーター エージェントが呼び出す登録済み A2A サブエージェントの ID に置き換えます。

次のステップ