Google 會運用 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 管理	工具執行期間會注入儲存的憑證。

服務代理身分

CX Agent Studio 的外送要求會使用 CX Agent Studio 服務代理：

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

將 PROJECT_NUMBER 替換為 Google Cloud 專案編號。

對內驗證

外部應用程式、自訂代理程式或協調器呼叫 CX Agent Studio 時，必須在 Authorization 標頭中傳遞 Google 核發的有效 OAuth 2.0 存取權杖：

測試：為有效帳戶產生臨時存取權杖：
```
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 通訊協定」工具卡。
使用使用者介面表單或 JSON 編輯器設定代理程式資訊卡。
在「URL」欄位中，輸入遠端代理程式的基準端點網址 (例如 https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID 或 Cloud Run 服務網址)。請勿在網址中附加 /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 服務專員應用程式。

傳入端點網址

將 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 代理應用程式的專屬 ID。

要求酬載結構定義

傳送訊息的 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 工作階段會共用相同的工作階段 ID，遠端工作階段則會保留主要和遠端服務專員之間的對話記錄。

如果是與第三方系統進行遠端工作階段，遠端工作階段預設為無狀態，遠端服務專員會將主要服務專員傳送的每則訊息視為新的工作階段 (也就是新的內容 ID)。

您可以啟用 RemoteAgentTool.stateful_agent 欄位，自動快取並重複使用遠端代理程式傳回的第一個內容 ID。

除非遠端代理程式以 AgentContext.session_metadata.closed == true 回應，否則系統會在工作階段的其餘時間使用這個快取內容 ID。如果工作階段已關閉，快取會重設，且下一次工具呼叫時會快取新的情境 ID。

部署遠端子代理程式

您可以在 Google Cloud 服務上部署自訂遠端代理，做為 CX Agent Studio 的子代理。

部署至 Cloud Run

如要在 Cloud Run 上代管使用 Agent Development Kit (ADK) 建構的代理程式，請按照下列步驟操作：

在代理程式專案目錄中建立 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

將 Cloud Run 服務的 roles/run.invoker 角色授予呼叫專案的 CX Agent Studio 服務代理。
按照「設定 A2A 通訊協定工具」一文中的步驟，將 Cloud Run 服務網址附加至 CX Agent Studio。

部署至 Vertex AI Agent Engine

如要將 ADK 代理部署至 Vertex AI Agent Engine，請按照下列步驟操作：

在 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}")

在目標專案中，將 roles/aiplatform.user 角色授予呼叫專案的 CX Agent Studio 服務代理。
按照「設定 A2A 通訊協定工具」一文中的步驟，將 Agent Engine 端點附加至 CX Agent Studio。

連線至第三方端點

CX Agent Studio 可以將工作委派給外部第三方端點，例如 ServiceNow 或 Salesforce。

在控制台中設定工具時：

按照「設定 A2A 通訊協定工具」一文中的步驟操作。
選取第三方端點所需的驗證方式 (例如 API 金鑰或 OAuth)。
使用 Secret Manager 安全地儲存憑證。