Install & Compatibility
Where this runs
tested against v1.1.2 · 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
67MB installed
● package 67MB
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.
Upgrade
Version history
1.1.2latest on PyPI · released Jul 22, 2026
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.