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 (Agent2Agent) 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

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