A2A 通訊協定合約

A2A 通訊協定合約定義了在 Amazon Bedrock AgentCore 執行期中實作agent-to-agent通訊的需求。本合約會指定 A2A 伺服器必須實作的技術需求、端點和通訊模式。

如需範例程式碼，請參閱在 AgentCore 執行期中部署 A2A 伺服器。

通訊協定實作要求

您的 A2A 伺服器必須實作這些特定的通訊協定需求：

容器需求

您的 A2A 伺服器必須部署為符合下列規格的容器化應用程式：

路徑需求

/ - POST

用途

接收 JSON-RPC 2.0 訊息，並透過代理程式的功能進行處理，透過 A2A 通訊協定訊息完成傳遞 InvokeAgentRuntime API 承載

使用案例

根端點有幾個主要用途：

要求格式

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 伺服器是否正常運作並準備好處理請求

回應格式

傳回狀態碼，指出代理程式的運作狀態：

{
  "status": "Healthy"
}

status 為必要項目，且為 Healthy或 之一HealthyBusy。當狀態為 時HealthyBusy，執行階段工作階段會保持運作狀態。

可能會包含選用time_of_last_update欄位 （以秒為單位的 Unix 時間戳記），以報告status上次變更的時間。

身分驗證要求

A2A 伺服器支援多個身分驗證機制：

OAuth 2.0 承載權杖

對於 A2A 用戶端身分驗證，請在請求標頭中包含承載字符：

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 身分驗證

程式設計存取也支援 Standard AWS SigV4 身分驗證。

錯誤處理

A2A 伺服器會傳回標準 JSON-RPC 2.0 錯誤回應與 HTTP 200 狀態碼，以維持通訊協定合規：

錯誤回應範例：

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}

OAuth 身分驗證回應

OAuth 設定的代理程式遵循 RFC 6749 (OAuth 2.0) 身分驗證標準。缺少身分驗證時，服務會傳回具有 WWW-Authenticate 標頭的 401 未授權回應 （根據 RFC 7235)，讓用戶端能夠透過 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}"