本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# A2A 协议合约
A2A 协议合同定义了在亚马逊 Bedrock Runtime 中实现代理间通信的要求。 AgentCore 该合同规定了您的 A2A 服务器必须实现的技术要求、端点和通信模式。
有关示例代码，请参见在 AgentCore 运行时[在 AgentCore 运行时部署 A2A 服务器](runtime-a2a.md)部署 A2A 服务器。
**Topics**
+ [协议实施要求](#protocol-implementation-requirements)
+ [容器要求](#container-requirements)
+ [路径要求](#path-requirements)
+ [身份验证要求](#authentication-requirements)
+ [错误处理](#error-handling)
+ [OAuth 身份验证响应](#a2a-oauth-authentication-responses)
## 协议实施要求
您的 A2A 服务器必须实现以下特定协议要求：
+ **传输**：基于 [ HTTP 的 ](https://www.jsonrpc.org/specification) JSON-RPC 2.0-支持标准化的代理与代理通信
+ **会话管理**：平台自动为会话隔离添加`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`标头
+ **代理发现**：必须在`/.well-known/agent-card.json`终端提供代理卡
## 容器要求
您的 A2A 服务器必须部署为符合以下规格的容器化应用程序：
+ **主机**：`0.0.0.0`
+ **端口**：`9000`-用于 A2A 服务器通信的标准端口（与 HTTP 和 MCP 协议不同）
+ **平台**：ARM64 容器-与 Amazon Amazon Bedrock AgentCore 运行时环境兼容所必需的
## 路径要求
### /-帖子
#### 用途
接收 JSON-RPC 2.0 消息并通过代理的功能对其进行处理，使用 A2A 协议消息完成 [ InvokeAgentRuntime ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API 负载的传递
#### 使用案例
根端点有几个关键用途：
+ Agent-to-agent 沟通与协作
+ Multi-step 代理工作流程和任务委托
+ Real-time 代理之间的对话体验
+ 工具调用和能力共享
#### 请求格式
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
#### 用途
为代理发现和能力通告提供代理卡元数据
#### 使用案例
代理卡端点有几个关键用途：
+ 多代理系统中的代理发现
+ 能力和技能广告
+ 身份验证要求规范
+ 服务端点配置
#### 响应格式
返回描述代理身份和能力的 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-获取
#### 用途
验证您的 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 SDK，则会为您处理 ping 响应。
## 身份验证要求
A2A 服务器支持多种身份验证机制：
### OAuth 2.0 持有者代币
对于 A2A 客户端身份验证，请在请求标头中加入不记名令牌：
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4 身份验证
编程访问还支持标准 Amazon 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 客户端不会自动重试。
**注意**
与 A2A 规范中通过 HTTP 200 响应传送 JSON-RPC 错误的惯例不同， 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-configured 代理遵循 [ RFC 6749 (OAuth 2.0) 身份验证标准。](https://datatracker.ietf.org/doc/html/rfc6749)缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 [ RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)），使客户端能够通过 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}"
```
**注意**
SigV4-configured 代理返回 HTTP 403 `ACCESS_DENIED` 时出现错误，并且不包含`WWW-Authenticate`标头。