Practical Guide to the Official A2A SDK Python

Table of Contents Note My Environment A2A SDK Python Note This is just a prototype that is rapidly evolving. This tutorial may become outdated at any time. You can find the latest updated article on the A2AProtocol blog. My Environment Python 3.13 uv: uv 0.7.2 (Homebrew 2025-04-30) Warp Ollama 0.6.7 (supports Qwen3) macOS Sequoia 15.4.1 A2A SDK Python Clone the latest code: git clone git@github.com:google/A2A.git Create a virtual environment cd A2A/a2a-python-sdk # Create virtual environment uv venv # Activate source .venv/bin/activate Install A2A SDK uv pip install -e . Run A2A Server cd a2a-python-sdk/examples/helloworld uv run python main.py Output: ⠙ Preparing packages... (16/18) black ------------------------------ 481.31 KiB/1.39 MiB ruff ------------------------------ 454.19 KiB/9.87 MiB Uninstalled 4 packages in 20ms Installed 25 packages in 40ms INFO: Started server process [46538] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit) INFO: 127.0.0.1:49177 - "GET /.well-known/agent.json HTTP/1.1" 200 OK INFO: 127.0.0.1:49179 - "POST / HTTP/1.1" 200 OK INFO: 127.0.0.1:49181 - "POST / HTTP/1.1" 200 OK Run A2A Client In a new terminal window, activate the venv, navigate to the a2a-python-sdk/examples/helloworld directory, and then execute: uv run python test_client.py Output: {'id': 'd220c3d7335e40478e1745d28d54155f', 'jsonrpc': '2.0', 'result': {'messageId': 'ac094ba7-f56c-41e3-85cf-a813406c65d4', 'parts': [{'text': 'Hello World', 'type': 'text'}], 'role': 'agent'}} Received an instance of Message, getTask and cancelTask are not applicable for invocation {'id': '403b8991269b42659d6349f34e8bf579', 'jsonrpc': '2.0', 'result': {'final': False, 'messageId': '0b56aa9d-25ca-4f2a-b397-7247c0081e94', 'parts': [{'text': 'Hello ', 'type': 'text'}], 'role': 'agent'}} {'id': '403b8991269b42659d6349f34e8bf579', 'jsonrpc': '2.0', 'result': {'final': True, 'messageId': '16dce67d-e4e6-4943-bad9-933412ad94ed', 'parts': [{'text': 'World', 'type': 'text'}], 'role': 'agent'}} Example completed. Hello World Explanation This is a simple A2A (Agent-to-Agent) SDK example that demonstrates how to create a basic Agent service. The example implements a simple Hello World Agent that can respond to messages and return "Hello World". Project Structure helloworld/ ├── main.py # Main program entry, configuration and Agent service startup ├── agent_executor.py # Agent executor implementation └── test_client.py # Test client example Core Components 1. Agent Service Configuration (main.py) Defines the Agent's skill: a simple "hello_world" skill Creates an AgentCard, including the Agent's basic information and capabilities Configures and starts the A2A server, listening on localhost:9999 2. Agent Executor (agent_executor.py) HelloWorldAgent class: implements basic message handling logic invoke(): synchronously returns "Hello World" stream(): returns "Hello World" as a stream (in two parts) HelloWorldAgentExecutor class: handles various message requests Supports regular message sending Supports streaming messages Handles task cancellation and resubscription requests 3. Test Client (test_client.py) Demonstrates how to connect to the Agent service Shows how to send messages Shows how to get task status Shows how to cancel tasks Shows how to use streaming messages Workflow Features Basic Message Handling: Able to receive and respond to simple text messages Streaming Response: Supports returning message content in chunks Task Management: Supports task status queries and cancellation operations Error Handling: Includes basic error handling mechanisms A2A SDK Python Guide

May 11, 2025 - 09:28

Practical Guide to the Official A2A SDK Python

Note
My Environment
A2A SDK Python

Note

This is just a prototype that is rapidly evolving. This tutorial may become outdated at any time. You can find the latest updated article on the A2AProtocol blog.

My Environment

Python 3.13
uv: uv 0.7.2 (Homebrew 2025-04-30)
Warp
Ollama 0.6.7 (supports Qwen3)
macOS Sequoia 15.4.1

A2A SDK Python

Clone the latest code:

git clone git@github.com:google/A2A.git

Create a virtual environment

cd A2A/a2a-python-sdk
# Create virtual environment
uv venv
# Activate
source .venv/bin/activate

Install A2A SDK

uv pip install -e .

Run A2A Server

cd a2a-python-sdk/examples/helloworld

uv run python __main__.py

Output:

⠙ Preparing packages... (16/18)
black      ------------------------------ 481.31 KiB/1.39 MiB
ruff       ------------------------------ 454.19 KiB/9.87 MiB                                                                                                                                                                     Uninstalled 4 packages in 20ms
Installed 25 packages in 40ms
INFO:     Started server process [46538]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
INFO:     127.0.0.1:49177 - "GET /.well-known/agent.json HTTP/1.1" 200 OK
INFO:     127.0.0.1:49179 - "POST / HTTP/1.1" 200 OK
INFO:     127.0.0.1:49181 - "POST / HTTP/1.1" 200 OK

Run A2A Client

In a new terminal window, activate the venv, navigate to the a2a-python-sdk/examples/helloworld directory, and then execute:

uv run python test_client.py

Output:

{'id': 'd220c3d7335e40478e1745d28d54155f', 'jsonrpc': '2.0', 'result': {'messageId': 'ac094ba7-f56c-41e3-85cf-a813406c65d4', 'parts': [{'text': 'Hello World', 'type': 'text'}], 'role': 'agent'}}
Received an instance of Message, getTask and cancelTask are not applicable for invocation
{'id': '403b8991269b42659d6349f34e8bf579', 'jsonrpc': '2.0', 'result': {'final': False, 'messageId': '0b56aa9d-25ca-4f2a-b397-7247c0081e94', 'parts': [{'text': 'Hello ', 'type': 'text'}], 'role': 'agent'}}
{'id': '403b8991269b42659d6349f34e8bf579', 'jsonrpc': '2.0', 'result': {'final': True, 'messageId': '16dce67d-e4e6-4943-bad9-933412ad94ed', 'parts': [{'text': 'World', 'type': 'text'}], 'role': 'agent'}}

Example completed.

Hello World Explanation

This is a simple A2A (Agent-to-Agent) SDK example that demonstrates how to create a basic Agent service. The example implements a simple Hello World Agent that can respond to messages and return "Hello World".

Project Structure

helloworld/
├── __main__.py          # Main program entry, configuration and Agent service startup
├── agent_executor.py    # Agent executor implementation
└── test_client.py       # Test client example

Core Components

1. Agent Service Configuration (`main.py`)

Defines the Agent's skill: a simple "hello_world" skill
Creates an AgentCard, including the Agent's basic information and capabilities
Configures and starts the A2A server, listening on localhost:9999

2. Agent Executor (`agent_executor.py`)

HelloWorldAgent class: implements basic message handling logic
- invoke(): synchronously returns "Hello World"
- stream(): returns "Hello World" as a stream (in two parts)
HelloWorldAgentExecutor class: handles various message requests
- Supports regular message sending
- Supports streaming messages
- Handles task cancellation and resubscription requests

3. Test Client (`test_client.py`)

Demonstrates how to connect to the Agent service
Shows how to send messages
Shows how to get task status
Shows how to cancel tasks
Shows how to use streaming messages

Workflow

Features

Basic Message Handling: Able to receive and respond to simple text messages
Streaming Response: Supports returning message content in chunks
Task Management: Supports task status queries and cancellation operations
Error Handling: Includes basic error handling mechanisms

A2A SDK Python Guide