Overview

Relevant source files

• .github/actions/spelling/allow.txt
• CHANGELOG.md
• Gemini.md
• README.md
• pyproject.toml
• src/a2a/utils/error_handlers.py
• tests/README.md
• tests/e2e/push_notifications/test_default_push_notification_support.py
• uv.lock

This page provides a high-level introduction to the a2a-python SDK, its purpose, architecture, and major subsystems. It is intended for developers who want to understand the SDK's structure before diving into implementation details.

For installation instructions, see Installation and Setup. For a detailed list of capabilities, see SDK Features and Capabilities. For protocol-level details, see A2A Protocol and Data Models.

---

Purpose and Scope

The a2a-python SDK is a Python implementation of the Agent-to-Agent (A2A) Protocol, enabling developers to:

1. Build A2A servers that expose agent capabilities to other systems
2. Consume remote A2A agents via client libraries
3. Implement multi-protocol communication using JSON-RPC, REST, or gRPC
4. Manage task state with pluggable persistence backends
5. Stream events in real-time using Server-Sent Events (SSE) or gRPC streaming

The SDK supports Python 3.10+ and provides optional integrations for HTTP servers (FastAPI/Starlette), databases (PostgreSQL, MySQL, SQLite), gRPC, OpenTelemetry, and cryptographic signing.

Sources: README.md1-103 pyproject.toml1-57

---

Package Structure and Distribution

The SDK is distributed as the a2a-sdk package on PyPI with a modular dependency structure:

Component	Dependencies	Purpose
Core	httpx, httpx-sse, pydantic, protobuf, google-api-core	Client functionality, type system, Protocol Buffer support
http-server	fastapi, starlette, sse-starlette	JSON-RPC and REST server implementations
grpc	grpcio, grpcio-tools, grpcio-reflection	gRPC transport support
telemetry	opentelemetry-api, opentelemetry-sdk	OpenTelemetry tracing integration
sql	sqlalchemy[asyncio,postgresql-asyncpg,aiomysql,aiosqlite]	Database persistence for tasks and push notification configs
encryption	cryptography	Cryptographic utilities
signing	PyJWT	Agent card signature verification

Users install only the components they need. For example, a client-only application needs just the core package, while a server application typically needs http-server and optionally sql.

Sources: pyproject.toml10-50 README.md44-60

---

Dual Architecture: Client and Server

The SDK is designed as two complementary subsystems that can be used independently or together:

Client Subsystem

Entry Point: ClientFactory class
Purpose: Discover and communicate with remote A2A agents
Key Classes: JsonRpcTransport, RestTransport, GrpcTransport, A2ACardResolver

The client subsystem enables applications to:

• Discover agent capabilities via the /.well-known/agent-card.json endpoint
• Send messages to agents using multiple transport protocols
• Stream real-time task updates via Server-Sent Events
• Manage task callbacks and push notification configurations

Sources: src/a2a/client/client_factory.py src/a2a/client/json_rpc_transport.py src/a2a/client/rest_transport.py src/a2a/client/agent_card.py

Server Subsystem

Entry Point: JSONRPCApplication or RestAdapter classes
Purpose: Expose agent functionality as an A2A-compliant server
Key Classes: DefaultRequestHandler, AgentExecutor, TaskManager, EventQueue

The server subsystem enables applications to:

• Serve agent cards at standardized endpoints
• Process incoming messages and execute agent logic
• Stream task updates to clients in real-time
• Persist task state to databases
• Send push notifications when tasks complete

Sources: src/a2a/jsonrpc/jsonrpc_app.py src/a2a/rest/rest_adapter.py src/a2a/server/request_handler.py src/a2a/server/agent_executor.py src/a2a/server/task_manager.py src/a2a/server/event_queue.py

---

Core Type System

The SDK defines its type system using two complementary approaches:

Pydantic Models (src/a2a/types.py)

Purpose: JSON serialization, validation, and Python-native type checking
Generated From: A2A specification JSON schemas via datamodel-code-generator

Key types include:

• Message: User or agent messages with parts (text, files, data)
• Task: Execution state with status, artifacts, and history
• AgentCard: Agent metadata, capabilities, and security schemes
• TaskStatusUpdateEvent / TaskArtifactUpdateEvent: Real-time updates
• Error types: InvalidRequestError, TaskNotFoundError, etc.

Protocol Buffers (src/a2a/grpc/*.proto)

Purpose: Binary serialization for gRPC transport
Generated From: A2A specification .proto files via buf generate

The proto_utils module (src/a2a/proto_utils.py) provides bidirectional conversion between Pydantic models and Protocol Buffer messages using ToProto and FromProto classes.

Sources: src/a2a/types.py src/a2a/grpc/ src/a2a/proto_utils.py .github/workflows/update-a2a-types.yml

---

Repository Structure

The repository is organized into distinct directories by functionality:

Key Directories:

Directory	Purpose
src/a2a/	Main SDK source code
src/a2a/client/	Client transport implementations and agent discovery
src/a2a/server/	Server-side request processing, task management, event streaming
src/a2a/jsonrpc/	FastAPI-based JSON-RPC 2.0 server implementation
src/a2a/rest/	Starlette-based REST API server implementation
src/a2a/grpc/	Generated Protocol Buffer code and gRPC servicer
src/a2a/utils/	Helper functions, validators, error handlers
tests/	Unit tests and end-to-end integration tests
.github/workflows/	CI/CD automation for testing, linting, type generation, and releases

Sources: [Repository structure visible in file paths]

---

Communication Flow: Message to Task

The following diagram illustrates how a client message becomes a persisted task with real-time updates:

Process Breakdown:

1. Client Request: Application calls send_message() on a transport client
2. Agent Discovery: Transport resolves agent capabilities from agent card
3. Server Routing: HTTP request routes to DefaultRequestHandler.on_message_send()
4. Task Creation: Handler creates a new task in TaskStore
5. Execution: AgentExecutor.execute() processes the message asynchronously
6. Event Publishing: Executor publishes status and artifact events to EventQueue
7. Event Consumption: Handler consumes events and updates task state in storage
8. Response Streaming: For streaming requests, events are sent via SSE as they occur; for non-streaming, final task is returned

Sources: src/a2a/client/json_rpc_transport.py src/a2a/jsonrpc/jsonrpc_app.py src/a2a/server/request_handler.py src/a2a/server/agent_executor.py src/a2a/server/event_queue.py src/a2a/server/task_store/

---

Protocol Support Matrix

The SDK implements multiple protocol layers for maximum interoperability:

Protocol	Client Support	Server Support	Streaming	Binary
JSON-RPC 2.0 over HTTP	✓ JsonRpcTransport	✓ JSONRPCApplication	SSE	JSON
REST API	✓ RestTransport	✓ RestAdapter	SSE	JSON or Protobuf
gRPC	✓ GrpcTransport	✓ A2AServicer	gRPC Streaming	Protobuf

All protocols support:

• Agent card discovery
• Message sending (blocking and streaming)
• Task retrieval and cancellation
• Push notification configuration
• Extension negotiation via headers

Sources: src/a2a/client/ src/a2a/jsonrpc/ src/a2a/rest/ src/a2a/grpc/

---

Development and Release Pipeline

The SDK uses an automated CI/CD pipeline to maintain code quality and synchronization with the A2A specification:

Automated Workflows:

1. Type Generation (.github/workflows/update-a2a-types.yml): Triggered by changes to the A2A specification repository, automatically regenerates types.py and Protocol Buffer code
2. Linting (.github/workflows/linter.yaml): Runs Ruff (formatting), MyPy and Pyright (type checking), and JSCPD (duplication detection)
3. Testing (.github/workflows/unit-tests.yml): Executes pytest across Python 3.10-3.13 and multiple database backends, enforces >88% coverage
4. Publishing (.github/workflows/python-publish.yml): Builds distributions and publishes to PyPI with dynamic versioning from Git tags

Sources: .github/workflows/ pyproject.toml118-144

---

Further Reading

This overview provides a foundation for understanding the SDK's architecture. For detailed information on specific topics:

• Getting Started: Installation and Setup
• Features: SDK Features and Capabilities
• Protocol Details: A2A Protocol and Data Models
• Client Usage: Client SDK Usage
• Server Implementation: Building A2A Servers
• Type System: Type System and Code Generation
• Multi-Transport: Multi-Transport Support

Sources: [Table of contents in JSON format provided]