The A2A Python SDK is an official library for building agentic applications that comply with the Agent2Agent (A2A) Protocol. It provides foundational building blocks for creating A2A servers and clients, supporting features like multi-turn conversations and streaming responses. The library is actively maintained with regular updates, and the 0.3 version of the protocol is intended to remain stable for a significant period with backward compatibility for SDKs starting at version 0.3. [1, 3, 12, 17, 19]
Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgentApp
✓ from a2a import AgentApp
✗ from a2a import AgentApp
This quickstart demonstrates how to create a basic 'Echo' A2A agent. It defines an `AgentExecutor` to handle incoming tasks, an `AgentCard` to describe the agent's capabilities, and then initializes an `AgentApp`. The example code shows how to process a simple text message and return an echoed response. To run this, you would typically use a ASGI server like Uvicorn. [21, 9]
import os
from a2a.server.app import AgentApp
from a2a.server.sdk import AgentExecutor, AgentCard
from a2a.server.types import AgentTask, TaskOutput, MessagePart
from a2a.server.exceptions import AgentException
class EchoAgentExecutor(AgentExecutor):
"""A simple agent that echoes back the input message."""
async def invoke(self, task: AgentTask) -> TaskOutput:
input_message = ""
# Extract text from the first message part
for part in task.input.parts:
if part.text:
input_message += part.text.text
break # Only process the first text part for simplicity
if not input_message:
raise AgentException("No text message received.")
response_parts = [MessagePart(text=f"Echo: {input_message}")]
return TaskOutput(output=response_parts)
# Define the agent's capabilities
agent_card = AgentCard(
agent_id="echo-agent",
display_name="Echo Agent",
description="An agent that echoes back any message it receives.",
skills=[{"name": "echo", "description": "Echoes the input."}]
)
# Create the A2A application instance
app = AgentApp(
agent_card=agent_card,
agent_executor=EchoAgentExecutor()
)
# To run this application (e.g., using uvicorn):
# 1. Save the code above as `main.py`
# 2. Run from your terminal: `uvicorn main:app --host 0.0.0.0 --port 8000`
# (Install uvicorn first: `pip install uvicorn`)
Debug
Known issues
breakingThe SDK is being upgraded to align with the A2A 1.0 protocol specification, introducing proto-based types. This will likely involve significant changes to existing classes and data structures. [10]fixReview the A2A 1.0 specification and official migration guides when upgrading to ensure compatibility with new proto-based types and API changes.
affects: Transitioning from 0.3.x to 1.0.x (alpha releases from March 2026).
breakingClass fields within the SDK are being refactored to be more Pythonic, adopting `snake_case` conventions. This affects how properties and fields are accessed. [12]fixUpdate all code accessing SDK object fields to use `snake_case` instead of `camelCase` or other conventions.
affects: 0.3.x (roadmap states this is part of 0.3 release, though specifics depend on minor versions).
breakingThe standard path for hosting Agent Cards has been updated from `/.well-known/agent.json` to `/.well-known/agent-card.json` based on IANA feedback. [12]fixEnsure your A2A servers correctly serve the Agent Card at the new `/.well-known/agent-card.json` endpoint.
affects: 0.3.x (roadmap states this is part of 0.3 release, though specifics depend on minor versions).
gotchaThe SDK's `AgentExecutor` signature and `DefaultRequestHandler` often lead to agent logic being tightly coupled to A2A protocol details (e.g., `Task`, `TaskOutput`, `MessagePart`). This can hinder testability, reusability, and readability of core agent intelligence. [15, 16]fixDesign your agent's core logic to be framework-agnostic, separating business rules from A2A protocol handling. Use a clean architectural pattern (e.g., hexagonal architecture) to prevent protocol knowledge from leaking into your agent's core components.
affects: All versions up to 0.3.x.
gotchaIf an `AgentCard` contains sensitive information, the endpoint serving it *must* be protected by appropriate access controls (e.g., mTLS, network restrictions, authentication). It is generally *not recommended* to include plaintext secrets (like static API keys) directly in an `AgentCard`. [20]fixImplement robust authentication and authorization for Agent Card endpoints. Prefer dynamic credentials obtained out-of-band over static secrets in the card.
affects: All versions.
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
FastAPIoptionalCommonly used for building A2A servers with HTTP/JSON-RPC, often included in SDK server implementations.
PydanticoptionalUsed for data validation and serialization within the SDK, especially with FastAPI.