本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# A2A 通訊協定合約
A2A 通訊協定合約定義了在 Amazon Bedrock AgentCore 執行期中實作agent-to-agent通訊的需求。本合約會指定 A2A 伺服器必須實作的技術需求、端點和通訊模式。
如需範例程式碼，請參閱在 [ AgentCore 執行期中部署 A2A 伺服器](runtime-a2a.md)。
**Topics**
+ [通訊協定實作要求](#protocol-implementation-requirements)
+ [容器需求](#container-requirements)
+ [路徑需求](#path-requirements)
+ [身分驗證要求](#authentication-requirements)
+ [錯誤處理](#error-handling)
+ [OAuth 身分驗證回應](#a2a-oauth-authentication-responses)
## 通訊協定實作要求
您的 A2A 伺服器必須實作這些特定的通訊協定需求：
+ **傳輸** ：透過 HTTP [的 JSON-RPC 2.0](https://www.jsonrpc.org/specification) - 啟用標準化agent-to-agent通訊
+ **工作階段管理**：平台會自動新增工作階段隔離的`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`標頭
+ **客服人員探索**：必須在`/.well-known/agent-card.json`端點提供客服人員卡
## 容器需求
您的 A2A 伺服器必須部署為符合下列規格的容器化應用程式：
+ **主機** ： `0.0.0.0`
+ **連接埠**：`9000`- A2A 伺服器通訊的標準連接埠 （不同於 HTTP 和 MCP 通訊協定）
+ **平台** ：ARM64 容器 - 與 Amazon Bedrock AgentCore AWS 執行期環境相容時需要
## 路徑需求
### / - POST
#### 用途
接收 JSON-RPC 2.0 訊息，並透過代理程式的功能進行處理，透過 A2A 通訊協定訊息完成傳遞 [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API 承載
#### 使用案例
根端點有幾個主要用途：
+ Agent-to-agent之間的通訊和協同合作
+ 多步驟代理程式工作流程和任務委派
+ 客服人員之間的即時對話體驗
+ 工具調用和功能共用
#### 要求格式
A2A 伺服器預期 JSON-RPC 2.0 格式的請求：
```
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "Your message content here"
}
],
"messageId": "unique-message-id"
}
}
}
```
#### 回應格式
A2A 伺服器會以包含任務和成品的 JSON-RPC 2.0 格式回應進行回應：
```
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "req-001",
"result": {
"artifacts": [
{
"artifactId": "unique-artifact-id",
"name": "agent_response",
"parts": [
{
"kind": "text",
"text": "Agent response content"
}
]
}
]
}
}
```
### /.well-known/agent-card.json - GET
#### 用途
為客服人員探索和功能公告提供客服人員卡中繼資料
#### 使用案例
客服人員卡端點有幾個主要用途：
+ 多代理程式系統中的代理程式探索
+ 功能和技能公告
+ 身分驗證需求規格
+ 服務端點組態
#### 回應格式
傳回描述代理程式身分和功能的 JSON 中繼資料：
```
Content-Type: application/json
{
"name": "Agent Name",
"description": "Agent description and purpose",
"version": "1.0.0",
"url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
"protocolVersion": "0.3.0",
"preferredTransport": "JSONRPC",
"capabilities": {
"streaming": true
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "skill-id",
"name": "Skill Name",
"description": "Skill description and capabilities",
"tags": []
}
]
}
```
### /ping - GET
#### 用途
驗證您的 A2A 伺服器是否正常運作並準備好處理請求
#### 回應格式
傳回狀態碼，指出代理程式的運作狀態：
+ **Content-Type**： `application/json`
+ **HTTP 狀態碼**：`200`適用於運作狀態不良、適當的錯誤碼
```
{
"status": "Healthy"
}
```
`status` 為必要項目，且為 `Healthy`或 之一`HealthyBusy`。當狀態為 時`HealthyBusy`，執行階段工作階段會保持運作狀態。
可能會包含選用`time_of_last_update`欄位 （以秒為單位的 Unix 時間戳記），以報告`status`上次變更的時間。
**警告**
請勿在每個 ping 上`time_of_last_update`將 設定為目前時間。在每個 ping 上推進的時間戳記會發出持續狀態變更，防止閒置工作階段逾時永遠觸發 — 然後工作階段會保留到 ，`MaxLifetime`並可以耗盡工作階段配額。如果您省略 欄位，平台會自行追蹤狀態變更。如果您使用 Bedrock AgentCore 開發套件，則會為您處理 ping 回應。
## 身分驗證要求
A2A 伺服器支援多個身分驗證機制：
### OAuth 2.0 承載權杖
對於 A2A 用戶端身分驗證，請在請求標頭中包含承載字符：
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4 身分驗證
程式設計存取也支援 Standard AWS SigV4 身分驗證。
## 錯誤處理
A2A 伺服器會以標準 JSON-RPC 2.0 錯誤回應傳回錯誤。下表會將每個執行時間例外狀況映射至其 JSON-RPC 錯誤碼、HTTP 狀態碼和訊息。有些例外狀況會共用 JSON-RPC 錯誤代碼，但會傳回不同的訊息，因此它們會列為個別的資料列。
| JSON-RPC 錯誤代碼 | 執行時間例外狀況 | HTTP 錯誤代碼 | JSON-RPC 錯誤訊息 |
| --- | --- | --- | --- |
| 不適用 | AccessDeniedException | 403 | 存取遭拒 （以標準 HTTP 錯誤傳回，而非 JSON-RPC 錯誤） |
| -32051 | ResourceNotFoundException | 404 | 找不到資源 - 請求的資源不存在 |
| -32052 | ValidationException | 400 | 驗證錯誤 - 無效的請求資料 |
| -32053 | ThrottlingException | 429 | 超過速率限制 - 請求太多 |
| -32053 | ServiceQuotaExceededException | 429 | 超過速率限制 - 請求太多 |
| -32054 | ConflictException | 409 | 資源衝突 - 資源已存在 |
| -32054 | RetryableConflictException | 409 | 工作階段操作進行中，請重試 |
| -32055 | RuntimeClientError | 424 | 執行期用戶端錯誤 - 如需詳細資訊，請檢查您的 CloudWatch 日誌 |
| -32603 | 任何其他例外狀況 | 500 | 內部錯誤 - 處理請求時發生意外錯誤 |
`ConflictException` 和 `RetryableConflictException`都使用 JSON-RPC 錯誤代碼 `-32054`(HTTP 409)。他們的訊息會區分它們。當第二個操作以服務佈建或銷毀的工作階段為目標時，服務會傳回 `RetryableConflictException`(`Session operation in progress, please retry`)。此條件為暫時性且可重試。呼叫者必須以短指數退避重試，因為 A2A 用戶端不會自動重試。
**注意**
與透過 HTTP 200 回應傳遞 JSON-RPC 錯誤的 A2A 規格慣例不同，AgentCore 執行期會傳回實際的 HTTP 狀態碼 （例如 409 或 404)。即使在非 2xx 回應上也剖析 JSON-RPC `error`內文，因此您的用戶端不會錯過錯誤碼 （例如 `-32054`) 或驅動重試所需的`Session operation in progress, please retry`訊息。
錯誤回應範例：
```
{
"jsonrpc": "2.0",
"id": "req-001",
"error": {
"code": -32052,
"message": "Validation error - Invalid request data"
}
}
```
## OAuth 身分驗證回應
OAuth 設定的代理程式遵循 [RFC 6749 (OAuth 2.0) ](https://datatracker.ietf.org/doc/html/rfc6749)身分驗證標準。缺少身分驗證時，服務會傳回具有 WWW-Authenticate 標頭的 401 未授權回應 （根據 [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235))，讓用戶端能夠透過 GetRuntimeProtectedResourceMetadata API 探索授權伺服器端點。
### 401 未授權 - 缺少身分驗證
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
**注意**
SigV4-configured代理程式傳回 HTTP 403 時發生錯誤`ACCESS_DENIED`，且不包含`WWW-Authenticate`標頭。