A2A 协议合约

A2A 协议合同定义了在 Amazon Bedrock Runtime 中实现代理间通信的要求。 AgentCore 本合同规定了您的 A2A 服务器必须实现的技术要求、端点和通信模式。

有关示例代码，请参阅在运行时部署 A2A 服务器。 AgentCore

协议实施要求

您的 A2A 服务器必须实现以下特定的协议要求：

容器要求

您的 A2A 服务器必须部署为符合以下规格的容器化应用程序：

路径要求

/-帖子

用途

接收 JSON-RPC 2.0 消息并通过代理的功能处理它们，使用 A2A 协议消息完成 InvokeAgentRuntimeAPI 有效负载的直通

使用案例

根端点有几个关键用途：

请求格式

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---card.json-known/agent GET

用途

提供代理卡元数据，用于代理发现和能力通告

使用案例

Agent Card 端点有几个关键用途：

响应格式

返回描述代理身份和功能的 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 身份验证

编程访问还支持标准 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-configured 代理遵守 RFC 6749 (OAuth 2.0) 身份验证标准。当缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 RFC 7235），使客户端能够通过 API 发现授权服务器端点。 GetRuntimeProtectedResourceMetadata

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