A2A Python SDK

0.3.26 · active · verified Thu Apr 09

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]

Warnings

breaking The 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]
Fix: Review the A2A 1.0 specification and official migration guides when upgrading to ensure compatibility with new proto-based types and API changes.
breaking Class fields within the SDK are being refactored to be more Pythonic, adopting `snake_case` conventions. This affects how properties and fields are accessed. [12]
Fix: Update all code accessing SDK object fields to use `snake_case` instead of `camelCase` or other conventions.
breaking The 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]
Fix: Ensure your A2A servers correctly serve the Agent Card at the new `/.well-known/agent-card.json` endpoint.
gotcha The 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]
Fix: Design 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.
gotcha If 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]
Fix: Implement robust authentication and authorization for Agent Card endpoints. Prefer dynamic credentials obtained out-of-band over static secrets in the card.

Install

pip install a2a-sdk Install core SDK

Imports

AgentApp
```
from a2a.server.app import AgentApp
```
Main application class for an A2A server.
AgentExecutor
```
from a2a.server.sdk import AgentExecutor
```
Abstract base class for implementing agent logic.
AgentCard
```
from a2a.server.sdk import AgentCard
```
Defines an agent's capabilities and metadata.

Quickstart

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`)

view raw JSON →