Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

A2A プロトコルツール

Agent-to-Agent（A2A）プロトコルは、自律型 AI エージェントが異なるシステム間で通信し、タスクを調整できるようにするオープンメッセージング標準です。

CX Agent Studio の A2A プロトコルツールを使用すると、エージェントアプリケーションで外部のリモートエージェントにタスクを委任したり、外部アプリケーションやオーケストレーターで標準化されたメッセージングを使用して CX Agent Studio エージェントを呼び出したりできます。

A2A の仕組み

CX Agent Studio の A2A プロトコルは、委任モデルを使用して動作します。

委任モデル

委任モデルでは、開始 CX Agent Studio エージェントがプライマリオーケストレーターとして機能し、セッション全体の制御を保持します。

セッションの所有権: プライマリエージェントがユーザーの会話セッションを維持します。専門的なサブタスクが必要な場合、プライマリエージェントはリモートエージェントをツールとして呼び出します。
制御フロー: リモートエージェントがリクエストを処理し、構造化されたレスポンスデータを返します。制御はすぐにプライマリエージェントに戻り、プライマリエージェントはエンドユーザー向けに結果を要約または統合します。
コンテキストの転送: メインのエージェントは、委任されたタスクに必要なパラメータと会話コンテキストのみを送信します。

A2A 委任のシーケンス図

テキストベースのコミュニケーション

A2A プロトコルのエージェント間の通信はすべてテキストベースです。

エンドユーザーが音声チャネル（電話や WebRTC など）でプライマリエージェントとやり取りする場合、音声はまずテキストに変換されます。
プライマリエージェントは、テキスト文字起こしとパラメータを HTTP リクエストペイロードでリモートサブエージェントに送信します。
未加工の音声ストリームとエンベディングは、A2A ネットワークインターフェースを介して送信されません。

モダリティのサポート

A2A プロトコルのモダリティ（テキストと音声）のサポートは、通信の方向によって異なります。

リモートエージェントから CX Agent Studio: テキストモダリティのみをサポートします。
CX Agent Studio からリモートエージェント: CX Agent Studio ではモダリティに依存しません。つまり、CX Agent Studio セッションでは音声やテキストなどのサポートされているモダリティを使用できますが、リモートエージェントはテキストのみを受信します。

課金

プライマリセッションとリモートセッションの両方が CX Agent Studio にあり、同じプロジェクトにある場合は、1 つのセッションに対して課金されます。

それ以外の場合、複数のプロジェクトまたはサードパーティシステムにまたがるプライマリセッションとリモートセッションに対して、2 つのセッションの料金が請求されます。

認証とアクセス制御

認証要件は、通信の方向とターゲットサービスによって異なります。

方向	ターゲットの宛先	認証メカニズム	必要な IAM ロール	説明
インバウンド（CX Agent Studio の外部）	CX Agent Studio エージェントアプリケーション	OAuth 2.0 アクセストークン	`roles/ces.client`	外部の呼び出し元が CX Agent Studio インバウンドエンドポイントを呼び出すために必要です。
アウトバウンド（CX Agent Studio から CX Agent Studio）	別のプロジェクトの CX Agent Studio エージェント	サービスエージェント	`roles/ces.client`	ターゲットプロジェクトの呼び出し元プロジェクトのサービスエージェントに付与されます。
アウトバウンド（CX Agent Studio から Cloud Run）	Cloud Run サービス	サービスエージェントの ID トークン	`roles/run.invoker`	Cloud Run サービスで呼び出し元プロジェクトのサービスエージェントに付与されます。
アウトバウンド（CX Agent Studio から Vertex AI）	Vertex AI Agent Engine	サービスエージェントの OAuth	`roles/aiplatform.user`	ターゲットプロジェクトの呼び出し元プロジェクトのサービスエージェントに付与されます。
アウトバウンド（CX Agent Studio からサードパーティへ）	外部エンドポイント（ServiceNow や Salesforce など）	API キーまたは OAuth	Secret Manager を使用して管理される	ツールの実行中に挿入された保存済みの認証情報。

サービスエージェント ID

CX Agent Studio からのアウトバウンドリクエストは、CX Agent Studio サービスエージェントを使用します。

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

PROJECT_NUMBER は、使用する Google Cloud プロジェクト番号に置き換えます。

インバウンド認証

外部アプリケーション、カスタムエージェント、オーケストレーターが CX Agent Studio を呼び出す場合は、有効な Google 発行の OAuth 2.0 アクセストークンを Authorization ヘッダーで渡す必要があります。

テスト: アクティブなアカウントの一時アクセストークンを生成します。
```
gcloud auth print-access-token
```
プログラムクライアント: アプリケーションのデフォルト認証情報（ADC）を使用します。
```
gcloud auth application-default print-access-token
```
本番環境: roles/ces.client（Customer Engagement Suite Client）ロールを持つ専用の Google サービスアカウントを使用します。

前提条件

A2A プロトコルツールを構成する前に:

プロジェクトで Gemini Enterprise for Customer Experience API（ces.googleapis.com）を有効にします。
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
呼び出し元のプリンシパルまたはサービスアカウントに Customer Engagement Suite Client ロール（roles/ces.client）が付与されていることを確認します。

A2A プロトコルツールを構成する

プライマリエージェントを外部リモートエージェントに接続する手順は次のとおりです。

CX Agent Studio コンソールを開きます。
プロジェクトを選択して、エージェントアプリケーションを開きます。
エージェントビルダーで、[ツール] アイコンをクリックします。
[+]（追加）ボタンをクリックして、新しいツールを作成します。
[A2A Protocol] ツールカードを選択します。
UI フォームまたは JSON エディタを使用して、エージェントカードを構成します。
[URL] フィールドに、リモートエージェントのベースエンドポイント URL（https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID や Cloud Run サービスの URL など）を入力します。URL に /message:send を追加しないでください。CX Agent Studio は実行時に /message:send を自動的に追加します。
エンドポイントに適した認証タイプを選択します。
[作成] をクリックします。

エージェントカードの例

次の JSON サンプルは、リモート天気エージェントのエージェントカードを定義しています。

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

ルート案内を追加する

A2A ツールに委任するタイミングをプライマリエージェントに指示します。次に例を示します。

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

受信メッセージ

外部システムは、インバウンド A2A メッセージングエンドポイントを使用して、CX Agent Studio エージェントアプリケーションにメッセージを直接送信できます。

インバウンドエンドポイント URL

次のエンドポイントに HTTP POST リクエストを送信します。

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: エージェントアプリケーションをホストするリージョン（us-central1 など）。
APP_ID: CX Agent Studio エージェントアプリケーションの固有識別子。

リクエストペイロードのスキーマ

インバウンドメッセージを送信するための JSON ペイロード構造:

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

注: CX Agent Studio では、メッセージペイロードは content フィールドを使用してメッセージテキスト部分を含みます。

curl を使用したリクエストの例

curl を使用して、インバウンドメッセージングをテストできます。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

コンテキストと状態の管理

A2A プロトコルは、AgentContext メッセージを使用して、エージェント間の変数とセッションの状態を管理します。コンテキストは、gecx_a2a_agent_context キーを使用して SendMessageRequest のメタデータで渡されます。

変数のマッピング

タスクを委任するときに、プライマリエージェントとリモートエージェント間で変数をマッピングできます。

アウトバウンドマッピング: RemoteAgentTool.input_variable_mapping は、リモートエージェントに送信される AgentContext.variables を計算します。
インバウンドマッピング: RemoteAgentTool.output_variable_mapping は、リモートエージェントが応答したときにプライマリエージェントの変数を更新します。

インバウンドリクエスト（外部クライアントから CX Agent Studio）の場合、アプリケーションは gecx_a2a_agent_context メタデータを逆シリアル化し、AgentContext.variables を現在のセッションに直接書き込みます。更新された変数は、クライアントに応答するときに AgentContext.variables に書き戻されます。

セッションの終了

プライマリエージェントは AgentContext.session_metadata.closed をモニタリングして、リモートセッションが終了するタイミングを判断します。

アウトバウンドリクエストでは、常に closed が false に設定されます。リモートエージェントのレスポンスで closed が true に設定されている場合、A2A 接続は終了します。
クライアントへのインバウンドレスポンスの場合、セッションが終了すると、CX Agent Studio アプリは closed を true に設定します。

ステートフルモード

CXAS アプリを使用したリモートセッションは常にステートフルです。プライマリ CXAS セッションとリモート CXAS セッションは同じセッション ID を共有し、リモートセッションはプライマリエージェントとリモートエージェント間の会話履歴を保持します。

サードパーティシステムとのリモートセッションの場合、リモートセッションはデフォルトでステートレスになり、リモートエージェントはプライマリエージェントからの各メッセージを新しいセッション（新しいコンテキスト ID）として受信します。

RemoteAgentTool.stateful_agent フィールドを有効にすると、リモートエージェントから返された最初のコンテキスト ID が自動的にキャッシュに保存され、再利用されます。

このキャッシュに保存されたコンテキスト ID は、リモートエージェントが AgentContext.session_metadata.closed == true で応答しない限り、セッションの残りの部分で使用されます。セッションが閉じると、キャッシュがリセットされ、次のツール呼び出しで新しいコンテキスト ID がキャッシュに保存されます。

リモートサブエージェントをデプロイする

Google Cloud サービスにカスタムリモートエージェントをデプロイして、CX Agent Studio のサブエージェントとして機能させることができます。

Cloud Run へのデプロイ

Agent Development Kit（ADK）で構築されたエージェントを Cloud Run でホストするには:

エージェントプロジェクトディレクトリに Dockerfile を作成します。

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

コンテナを Cloud Run にデプロイします。

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

呼び出し元プロジェクトの CX Agent Studio サービスエージェントに、Cloud Run サービスに対する roles/run.invoker ロールを付与します。
A2A プロトコルツールを構成するの手順に沿って、Cloud Run サービスの URL を CX Agent Studio に関連付けます。

Vertex AI Agent Engine へのデプロイ

Vertex AI Agent Engine に ADK エージェントをデプロイするには:

requirements.txt で依存関係を定義します。
```
a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0
```

Vertex AI SDK を使用してエンジンをデプロイします。

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

呼び出し元プロジェクトの CX Agent Studio サービスエージェントに、ターゲットプロジェクトの roles/aiplatform.user ロールを付与します。
A2A プロトコルツールを構成するの手順に沿って、Agent Engine エンドポイントを CX Agent Studio に接続します。

サードパーティエンドポイントに接続する

CX Agent Studio は、ServiceNow や Salesforce などの外部のサードパーティエンドポイントにタスクを委任できます。

コンソールでツールを構成する場合:

A2A プロトコルツールを構成するの手順に沿って操作します。
サードパーティエンドポイントで必要な認証方法（API キーや OAuth など）を選択します。
Secret Manager を使用して認証情報を安全に保存します。

A2A プロトコルツールとツールとしてのエージェントの比較

CX Agent Studio には、マルチエージェントワークフローを調整するための複数の方法が用意されています。

機能	ツールとしてのエージェント	A2A プロトコルツール
範囲	アプリケーション内（同じ CX Agent Studio アプリ内のエージェント）。	アプリケーション間（外部エージェント、リモートサービス、サードパーティプラットフォーム）。
通信	インメモリ / 内部実行を直接行います。	A2A メッセージング標準を使用するネットワーク HTTP リクエスト。
ユースケース	セッションをハンドオフせずに内部サブエージェントを再利用する。	Cloud Run、Vertex AI、または外部 API でカスタム ADK エージェントを呼び出す。
プロトコル	プラットフォーム内部ツールの実行。	REST 経由の標準化された A2A JSON ペイロード。

LLM ツールの実行

内部的には、A2A プロトコル呼び出しは標準の LLM ツール呼び出しを介して動作します。

A2A ツールがエージェントに割り当てられると、ツールの説明とスキル定義が関数宣言としてモデルに提供されます。
モデルがサブタスクの委任を決定すると、関数呼び出しイベントが生成されます。
CX Agent Studio ランタイムは、関数呼び出しをインターセプトし、パラメータを A2A HTTP リクエストに変換して、構成されたリモートエンドポイントに送信します。
リモートエージェントから返されたレスポンスは、会話レスポンスの生成を続行するためにモデルに渡されます。

エージェントが呼び出し可能なツールとしてカプセル化される方法については、GitHub の ADK AgentTool の実装をご覧ください。

A2A プロトコル ツール コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

A2A の仕組み

委任モデル

テキストベースのコミュニケーション

モダリティのサポート

課金

認証とアクセス制御

サービス エージェント ID

インバウンド認証

前提条件

A2A プロトコル ツールを構成する

エージェント カードの例

ルート案内を追加する

受信メッセージ

インバウンド エンドポイント URL

リクエスト ペイロードのスキーマ

curl を使用したリクエストの例

コンテキストと状態の管理

変数のマッピング

セッションの終了

ステートフル モード

リモート サブエージェントをデプロイする

Cloud Run へのデプロイ

Vertex AI Agent Engine へのデプロイ

サードパーティ エンドポイントに接続する

A2A プロトコル ツールとツールとしてのエージェントの比較

LLM ツールの実行

A2A プロトコルツール

サービスエージェント ID

A2A プロトコルツールを構成する

エージェントカードの例

インバウンドエンドポイント URL

リクエストペイロードのスキーマ

ステートフルモード

リモートサブエージェントをデプロイする

サードパーティエンドポイントに接続する

A2A プロトコルツールとツールとしてのエージェントの比較