A2A Server Implementation
Before writing code
Fetch live docs:
- Fetch
https://a2a-protocol.org/latest/specification/ for the server-side protocol requirements
- Web-search
site:github.com a2aproject a2a-python server or a2aproject a2a-js server for SDK server classes
- Web-search
site:github.com a2aproject a2a-samples server for reference server implementations
- Fetch the target SDK README for server setup patterns
Conceptual Architecture
What an A2A Server Does
An A2A server is the agent's network endpoint that:
- Serves the Agent Card at
/.well-known/agent-card.json
- Accepts JSON-RPC 2.0 requests at the agent's URL
- Routes requests to the appropriate method handler
- Manages task state (creation, updates, terminal states)
- Executes the agent's logic (the "brain" — typically an LLM or deterministic logic)
- Returns responses in the correct JSON-RPC format
Request Processing Flow
HTTP POST → JSON-RPC parse → Method routing → Handler execution → Task state update → JSON-RPC response
Methods to Implement
Every A2A server must handle:
| Method |
Required |
Description |
message/send |
Yes |
Receive a message, create/update task, return result |
message/stream |
If streaming |
Same as send but returns SSE stream |
tasks/get |
Yes |
Return task by ID |
tasks/cancel |
Yes |
Cancel a task |
tasks/resubscribe |
If streaming |
Re-subscribe to task's SSE stream |
| Push notification methods |
If supported |
Configure/manage push notification callbacks |
Task State Management
The server is responsible for task state transitions:
- Create tasks in
submitted state when receiving new messages
- Transition to
working when processing begins
- Transition to
input-required when more input is needed
- Transition to terminal state (
completed, failed, canceled, rejected) when done
- Never transition from a terminal state to a non-terminal state
Handler Pattern
The SDK typically provides a handler interface you implement:
class MyAgentHandler:
async def handle_message(task_id, message) -> TaskResult:
# Your agent logic here
# 1. Parse the input message parts
# 2. Process with LLM or business logic
# 3. Return result with updated task state
Server Components
- HTTP Server — Handles HTTP requests (FastAPI, Express, built-in SDK server)
- JSON-RPC Router — Parses JSON-RPC and routes to method handlers
- Task Store — Persists task state (in-memory for dev, database for production)
- Agent Handler — Your custom logic that processes tasks
- Agent Card Endpoint — Serves the discovery document
Task Storage
- In-memory — Dict/Map of task IDs to task objects (development only)
- Redis — Fast key-value storage for task state (good for single-region)
- Database — PostgreSQL, MongoDB, etc. (production, multi-region)
- SDK built-in — Some SDKs provide task store abstractions
Concurrency
A2A servers must handle concurrent requests:
- Multiple tasks running simultaneously
- Same task receiving updates while processing
- Streaming responses held open while processing continues
- Proper locking/synchronization for task state updates
Best Practices
- Use the SDK's built-in server utilities rather than implementing raw JSON-RPC
- Implement proper task state validation — reject invalid transitions
- Add request logging with task IDs for debugging
- Set reasonable timeouts for long-running tasks
- Handle graceful shutdown — complete or cancel in-flight tasks
- Return proper JSON-RPC errors for invalid requests
- Validate incoming messages against expected input modes
- Use async/await for I/O-bound operations (LLM calls, external APIs)
Fetch the SDK documentation for exact server class names, constructor parameters, middleware patterns, and handler interfaces before implementing.
1---2name: a2a-server3description: Build an A2A server — the agent-side endpoint that receives JSON-RPC requests, processes tasks, manages state, and returns results. Use when implementing the server side of an A2A agent.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/a2a-server7---89# A2A Server Implementation1011## Before writing code1213**Fetch live docs**:141. Fetch `https://a2a-protocol.org/latest/specification/` for the server-side protocol requirements152. Web-search `site:github.com a2aproject a2a-python server` or `a2aproject a2a-js server` for SDK server classes163. Web-search `site:github.com a2aproject a2a-samples server` for reference server implementations174. Fetch the target SDK README for server setup patterns1819## Conceptual Architecture2021### What an A2A Server Does2223An A2A server is the **agent's network endpoint** that:241. Serves the Agent Card at `/.well-known/agent-card.json`252. Accepts JSON-RPC 2.0 requests at the agent's URL263. Routes requests to the appropriate method handler274. Manages task state (creation, updates, terminal states)285. Executes the agent's logic (the "brain" — typically an LLM or deterministic logic)296. Returns responses in the correct JSON-RPC format3031### Request Processing Flow3233```34HTTP POST → JSON-RPC parse → Method routing → Handler execution → Task state update → JSON-RPC response35```3637### Methods to Implement3839Every A2A server must handle:4041| Method | Required | Description |42|--------|----------|-------------|43| `message/send` | Yes | Receive a message, create/update task, return result |44| `message/stream` | If streaming | Same as send but returns SSE stream |45| `tasks/get` | Yes | Return task by ID |46| `tasks/cancel` | Yes | Cancel a task |47| `tasks/resubscribe` | If streaming | Re-subscribe to task's SSE stream |48| Push notification methods | If supported | Configure/manage push notification callbacks |4950### Task State Management5152The server is responsible for task state transitions:53- Create tasks in `submitted` state when receiving new messages54- Transition to `working` when processing begins55- Transition to `input-required` when more input is needed56- Transition to terminal state (`completed`, `failed`, `canceled`, `rejected`) when done57- Never transition from a terminal state to a non-terminal state5859### Handler Pattern6061The SDK typically provides a handler interface you implement:6263```64class MyAgentHandler:65 async def handle_message(task_id, message) -> TaskResult:66 # Your agent logic here67 # 1. Parse the input message parts68 # 2. Process with LLM or business logic69 # 3. Return result with updated task state70```7172### Server Components73741. **HTTP Server** — Handles HTTP requests (FastAPI, Express, built-in SDK server)752. **JSON-RPC Router** — Parses JSON-RPC and routes to method handlers763. **Task Store** — Persists task state (in-memory for dev, database for production)774. **Agent Handler** — Your custom logic that processes tasks785. **Agent Card Endpoint** — Serves the discovery document7980### Task Storage8182- **In-memory** — Dict/Map of task IDs to task objects (development only)83- **Redis** — Fast key-value storage for task state (good for single-region)84- **Database** — PostgreSQL, MongoDB, etc. (production, multi-region)85- **SDK built-in** — Some SDKs provide task store abstractions8687### Concurrency8889A2A servers must handle concurrent requests:90- Multiple tasks running simultaneously91- Same task receiving updates while processing92- Streaming responses held open while processing continues93- Proper locking/synchronization for task state updates9495### Best Practices9697- Use the SDK's built-in server utilities rather than implementing raw JSON-RPC98- Implement proper task state validation — reject invalid transitions99- Add request logging with task IDs for debugging100- Set reasonable timeouts for long-running tasks101- Handle graceful shutdown — complete or cancel in-flight tasks102- Return proper JSON-RPC errors for invalid requests103- Validate incoming messages against expected input modes104- Use async/await for I/O-bound operations (LLM calls, external APIs)105106Fetch the SDK documentation for exact server class names, constructor parameters, middleware patterns, and handler interfaces before implementing.