A2A protocol contract

The A2A protocol contract defines the requirements for implementing agent-to-agent communication in Amazon Bedrock AgentCore Runtime. This contract specifies the technical requirements, endpoints, and communication patterns that your A2A server must implement.

For example code, see Deploy A2A servers in AgentCore Runtime.

Protocol implementation requirements

Your A2A server must implement these specific protocol requirements:

Container requirements

Your A2A server must be deployed as a containerized application meeting these specifications:

Path requirements

/ - POST

Purpose

Receives JSON-RPC 2.0 messages and processes them through your agent’s capabilities, complete pass-through of InvokeAgentRuntime API payload with A2A protocol messages

Use cases

The root endpoint serves several key purposes:

Request format

A2A servers expect JSON-RPC 2.0 formatted requests:

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

Response format

A2A servers respond with JSON-RPC 2.0 formatted responses containing tasks and artifacts:

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

Purpose

Provides Agent Card metadata for agent discovery and capability advertisement

Use cases

The Agent Card endpoint serves several key purposes:

Response format

Returns JSON metadata describing the agent’s identity and capabilities:

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

Purpose

Verifies that your A2A server is operational and ready to handle requests

Response format

Returns a status code indicating your agent’s health:

{
  "status": "Healthy"
}

status is required and is one of Healthy or HealthyBusy. While the status is HealthyBusy, the runtime session is kept alive.

An optional time_of_last_update field (a Unix timestamp in seconds) may be included to report when the status last changed.

Authentication requirements

A2A servers support multiple authentication mechanisms:

OAuth 2.0 Bearer Tokens

For A2A client authentication, include the Bearer token in request headers:

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

SigV4 Authentication

Standard AWS SigV4 authentication is also supported for programmatic access.

Error handling

A2A servers return errors as standard JSON-RPC 2.0 error responses. The following table maps each runtime exception to its JSON-RPC error code, HTTP status code, and message. Some exceptions share a JSON-RPC error code but return different messages, so they are listed as separate rows.

ConflictException and RetryableConflictException both use JSON-RPC error code -32054 (HTTP 409). Their messages distinguish them. The service returns RetryableConflictException (Session operation in progress, please retry) when a second operation targets a session that the service is provisioning or tearing down. This condition is transient and retryable. The caller must retry with short exponential backoff, because A2A clients do not auto-retry it.

Example error response:

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

OAuth authentication responses

OAuth-configured agents follow RFC 6749 (OAuth 2.0) authentication standards. When authentication is missing, the service returns a 401 Unauthorized response with a WWW-Authenticate header (per RFC 7235 ), enabling clients to discover the authorization server endpoints through the GetRuntimeProtectedResourceMetadata API.

401 Unauthorized - Missing Authentication

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