# a2aproject/a2a-python architecture

> Architecture diagram of the GitHub repository a2aproject/a2a-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/a2aproject/a2a-python
- Repository: https://github.com/a2aproject/a2a-python

## Overview

A2A Python SDK implements the Agent2Agent protocol for building asynchronous agent servers and clients. A client resolves an agent card, selects a protocol transport, and sends requests to a remote server; server routes dispatch protocol operations to request handlers, which coordinate agent execution, task state, and streamed events. The SDK also provides plugins, push-notification support, database-backed stores, telemetry, and v0.3 compatibility transports and handlers. Edges reflect README claims or source-index references; unsampled subsystems and optional integrations are represented only where documented.

Main entry points: [`src/a2a/server/request_handlers/default_request_handler.py`](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/default_request_handler.py) (Default handler), [`src/a2a/client/client_factory.py`](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client_factory.py) (Client factory), [`src/a2a/server/routes`](https://github.com/a2aproject/a2a-python/tree/main/src/a2a/server/routes) (HTTP routes), [`src/a2a/server/request_handlers/request_handler.py`](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/request_handler.py) (Request handler API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client access"]
  node_client_factory["Client factory<br/>[client_factory.py]"]
  node_client_core["Client API<br/>[client.py]"]
  node_card_resolver["Card resolver<br/>[card_resolver.py]"]
  node_client_transport["Client transports"]
end

subgraph group_server["Server protocol"]
  node_server_routes["HTTP routes"]
  node_jsonrpc_dispatch["JSON-RPC dispatch"]
  node_rest_dispatch["REST dispatch<br/>[rest_dispatcher.py]"]
  node_card_routes["Agent card routes"]
  node_request_handler["Request handler API<br/>[request_handler.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_default_handler["Default handler"]
  node_agent_executor["Agent executor<br/>[agent_executor.py]"]
  node_event_queues["Event queues<br/>[event_queue.py]"]
  node_task_manager["Task manager<br/>[task_manager.py]"]
end

subgraph group_compat["v0.3 compatibility"]
  node_compat_handler["v0.3 gRPC handler<br/>[grpc_handler.py]"]
  node_compat_transports["v0.3 transports"]
end

subgraph group_platform["State and extensions"]
  node_task_store[("Task stores<br/>[task_store.py]")]
  node_memory_store[("In-memory store")]
  node_cluster_store[("Cluster stores<br/>[task_store.py]")]
  node_plugins["Plugin manager<br/>[manager.py]"]
  node_push["Push notifications"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

node_developer(("A2A caller"))
node_remote_server(("Remote A2A server"))
node_client_result(("Protocol response"))

node_developer -->|"creates client"| node_client_factory
node_client_factory -->|"resolves card"| node_card_resolver
node_client_factory -->|"selects transport"| node_client_transport
node_client_factory -->|"builds client"| node_client_core
node_client_core -->|"sends requests"| node_remote_server
node_remote_server -->|"returns response"| node_client_result
node_developer -->|"hosts server"| node_server_routes
node_server_routes -->|"routes JSON-RPC"| node_jsonrpc_dispatch
node_server_routes -->|"routes REST"| node_rest_dispatch
node_server_routes -->|"dispatches requests"| node_request_handler
node_server_routes -->|"serves agent card"| node_card_routes
node_request_handler -.->|"implemented by"| node_default_handler
node_default_handler -->|"runs agent"| node_agent_executor
node_default_handler -->|"updates tasks"| node_task_manager
node_default_handler -->|"streams events"| node_event_queues
node_task_manager -->|"persists tasks"| node_task_store
node_memory_store -.->|"implements interface"| node_task_store
node_cluster_store -.->|"implements interface"| node_task_store
node_default_handler -->|"uses hooks"| node_plugins
node_default_handler -.->|"sends notifications"| node_push
node_event_queues -->|"instruments queues"| node_telemetry
node_compat_handler -->|"delegates requests"| node_request_handler
node_client_factory -->|"selects v0.3 transport"| node_compat_transports
node_compat_transports -->|"uses v0.3 protocol"| node_remote_server

click node_client_factory "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client_factory.py"
click node_client_core "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client.py"
click node_card_resolver "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/card_resolver.py"
click node_client_transport "https://github.com/a2aproject/a2a-python/tree/main/src/a2a/client/transports"
click node_server_routes "https://github.com/a2aproject/a2a-python/tree/main/src/a2a/server/routes"
click node_jsonrpc_dispatch "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/jsonrpc_dispatcher.py"
click node_rest_dispatch "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/rest_dispatcher.py"
click node_card_routes "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/agent_card_routes.py"
click node_request_handler "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/request_handler.py"
click node_default_handler "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/default_request_handler.py"
click node_agent_executor "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/agent_execution/agent_executor.py"
click node_event_queues "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/events/event_queue.py"
click node_task_manager "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/task_manager.py"
click node_task_store "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/task_store.py"
click node_memory_store "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/inmemory_task_store.py"
click node_cluster_store "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/cluster/task_store.py"
click node_plugins "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/plugins/manager.py"
click node_push "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/push_notification_sender.py"
click node_telemetry "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/utils/telemetry.py"
click node_compat_handler "https://github.com/a2aproject/a2a-python/blob/main/src/a2a/compat/v0_3/grpc_handler.py"
click node_compat_transports "https://github.com/a2aproject/a2a-python/tree/main/src/a2a/compat/v0_3"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_factory,node_client_core,node_card_resolver,node_client_transport toneBlue
class node_server_routes,node_jsonrpc_dispatch,node_rest_dispatch,node_card_routes,node_request_handler toneAmber
class node_default_handler,node_agent_executor,node_event_queues,node_task_manager,node_remote_server toneMint
class node_compat_handler,node_compat_transports toneRose
class node_task_store,node_memory_store,node_cluster_store,node_plugins,node_push,node_telemetry,node_developer,node_client_result toneIndigo
```

## Components

### Client access

- [Client factory](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client_factory.py): `src/a2a/client/client_factory.py`
- [Client API](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client.py): `src/a2a/client/client.py`
- [Card resolver](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/card_resolver.py): `src/a2a/client/card_resolver.py`
- [Client transports](https://github.com/a2aproject/a2a-python/tree/main/src/a2a/client/transports): `src/a2a/client/transports`

### Server protocol

- [HTTP routes](https://github.com/a2aproject/a2a-python/tree/main/src/a2a/server/routes): `src/a2a/server/routes`
- [JSON-RPC dispatch](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/jsonrpc_dispatcher.py): `src/a2a/server/routes/jsonrpc_dispatcher.py`
- [REST dispatch](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/rest_dispatcher.py): `src/a2a/server/routes/rest_dispatcher.py`
- [Agent card routes](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/routes/agent_card_routes.py): `src/a2a/server/routes/agent_card_routes.py`
- [Request handler API](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/request_handler.py): `src/a2a/server/request_handlers/request_handler.py`

### Agent runtime

- [Default handler](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/request_handlers/default_request_handler.py): `src/a2a/server/request_handlers/default_request_handler.py`
- [Agent executor](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/agent_execution/agent_executor.py): `src/a2a/server/agent_execution/agent_executor.py`
- [Event queues](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/events/event_queue.py): `src/a2a/server/events/event_queue.py`
- [Task manager](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/task_manager.py): `src/a2a/server/tasks/task_manager.py`

### v0.3 compatibility

- [v0.3 gRPC handler](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/compat/v0_3/grpc_handler.py): `src/a2a/compat/v0_3/grpc_handler.py`
- [v0.3 transports](https://github.com/a2aproject/a2a-python/tree/main/src/a2a/compat/v0_3): `src/a2a/compat/v0_3`

### State and extensions

- [Task stores](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/task_store.py): `src/a2a/server/tasks/task_store.py`
- [In-memory store](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/inmemory_task_store.py): `src/a2a/server/tasks/inmemory_task_store.py`
- [Cluster stores](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/cluster/task_store.py): `src/a2a/server/cluster/task_store.py`
- [Plugin manager](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/plugins/manager.py): `src/a2a/plugins/manager.py`
- [Push notifications](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/tasks/push_notification_sender.py): `src/a2a/server/tasks/push_notification_sender.py`
- [Telemetry](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/utils/telemetry.py): `src/a2a/utils/telemetry.py`

### Other components

- **A2A caller**
- **Remote A2A server**
- **Protocol response**

## Connections

- A2A caller → Client factory: creates client (evidence: `README.md`)
- Client factory → Card resolver: resolves card (evidence: `src/a2a/client/client_factory.py`)
- Client factory → Client transports: selects transport (evidence: `src/a2a/client/client_factory.py`)
- Client factory → Client API: builds client (evidence: `src/a2a/client/client_factory.py`)
- Client API → Remote A2A server: sends requests (evidence: `README.md`)
- Remote A2A server → Protocol response: returns response (evidence: `README.md`)
- A2A caller → HTTP routes: hosts server (evidence: `README.md`)
- HTTP routes → JSON-RPC dispatch: routes JSON-RPC (evidence: `src/a2a/server/routes/jsonrpc_routes.py`)
- HTTP routes → REST dispatch: routes REST (evidence: `src/a2a/server/routes/rest_routes.py`)
- HTTP routes → Request handler API: dispatches requests (evidence: `src/a2a/server/routes/jsonrpc_routes.py`)
- HTTP routes → Agent card routes: serves agent card (evidence: `src/a2a/server/routes/agent_card_routes.py`)
- Request handler API → Default handler: implemented by (evidence: `src/a2a/server/request_handlers/default_request_handler.py`)
- Default handler → Agent executor: runs agent (evidence: `src/a2a/server/request_handlers/default_request_handler.py`)
- Default handler → Task manager: updates tasks (evidence: `src/a2a/server/request_handlers/default_request_handler.py`)
- Default handler → Event queues: streams events (evidence: `src/a2a/server/request_handlers/default_request_handler.py`)
- Task manager → Task stores: persists tasks (evidence: `src/a2a/server/tasks/task_manager.py`)
- In-memory store → Task stores: implements interface
- Cluster stores → Task stores: implements interface (evidence: `src/a2a/server/cluster/task_store.py`)
- Default handler → Plugin manager: uses hooks
- Default handler → Push notifications: sends notifications
- Event queues → Telemetry: instruments queues (evidence: `src/a2a/server/events/event_queue.py`)
- v0.3 gRPC handler → Request handler API: delegates requests (evidence: `src/a2a/compat/v0_3/grpc_handler.py`)
- Client factory → v0.3 transports: selects v0.3 transport (evidence: `src/a2a/client/client_factory.py`)
- v0.3 transports → Remote A2A server: uses v0.3 protocol (evidence: `README.md`)