本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

A2A 协议合约

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

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

协议实施要求

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

容器要求

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

路径要求

/-帖子

用途

接收 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--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 服务器是否正常运行并已准备好处理请求

响应格式

返回表示代理人健康状况的状态码：

{
  "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 错误响应返回。下表将每个运行时异常映射到其 JSON-RPC 错误代码、HTTP 状态代码和消息。一些异常共享 JSON-RPC 错误代码，但返回不同的消息，因此它们被列为单独的行。

ConflictException并且RetryableConflictException都使用 JSON-RPC 错误代码 -32054 (HTTP 409)。他们的信息使他们与众不同。当第二项操作以服务正在配置或拆除的会话为目标时，该服务返回 RetryableConflictException (Session operation in progress, please retry)。这种情况是暂时的，可以重试。调用方必须使用短暂的指数回退来重试，因为 A2A 客户端不会自动重试。

错误响应示例：

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