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",
  "time_of_last_update": 1640995200
}

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 with HTTP 200 status codes to maintain protocol compliance:

Example error response:

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