A2A SDK Reaches v1.0: Python Tutorial Overhaul

The Agent-to-Agent protocol's Python SDK hits its first stable milestone, with updated tutorials reflecting the modern event-driven approach and native protobuf construction.

+124

−41

5 files changed

PR #1678

About the Author

Iva Sokolaj is an A2A project contributor working on SDK documentation and developer experience. This PR updates the Python tutorial to align with the v1.0.0-alpha.0 SDK release, marking a significant milestone in the protocol's maturity.

Why This Matters

The Agent-to-Agent (A2A) protocol enables AI agents to communicate and collaborate with each other — think of it as a lingua franca for the emerging agent ecosystem. While UCP handles agent-to-business transactions, A2A handles agent-to-agent coordination.

The SDK reaching v1.0 (even as an alpha) signals the protocol is stabilizing. For developers building multi-agent systems, this means:

API stability — v1.0 semantics mean breaking changes require major version bumps
Production readiness — the SDK is ready for real workloads, not just experimentation
Ecosystem foundation — other languages (Go, Rust, TypeScript) can align to the Python reference

What Changed

Agent Card Schema Updates

The AgentCard — an agent's public capability declaration — received several updates:

Legacy url property replaced with icon_url
New supported_interfaces field for declaring protocol bindings
Documentation for the extended_agent_card capability

Event-Driven Execution Model

The HelloWorldAgentExecutor walkthrough was rewritten to reflect the modern approach:

Old vs New Model

Before: Single string message responses
After: Explicit event queuing — Task, TaskStatusUpdateEvent (WORKING), TaskArtifactUpdateEvent, TaskStatusUpdateEvent (COMPLETED)

This makes the difference between streaming and non-streaming execution explicit and prepares developers for more complex async workflows.

Client Factory Pattern

Direct A2ACardResolver instantiation replaced with the new ClientFactory approach:

# Old pattern
resolver = A2ACardResolver(agent_url)
client = A2AClient(resolver)

# New pattern
client = ClientFactory.create(config)
client.send_message(message)  # Handles streaming based on config + agent capabilities

Native Protobuf Construction

The tutorial now uses native protobuf Message, Part, and Role objects instead of MessageSendParams dictionaries — aligning with the generated types and enabling better IDE support.

Safer Defaults

Server binding changed from 0.0.0.0 to 127.0.0.1 in examples — a small but meaningful security improvement for developers following the tutorial.

A2A v1.0 Timeline

March 12, 2026

V1.0 Specification Published

Official 1.0 specification released with blog post announcement

March 24, 2026

a2a-sdk v1.0.0-alpha.0

Python SDK published with v1.0-aligned implementation

March 26, 2026

Tutorial Updates Merged

Documentation aligned with new SDK patterns

What's Next

For A2A adopters:

The a2a-samples repo is being updated to v1.0
Watch for v1.0.0-alpha.1 addressing early feedback
QuerySkill operation (PR #1655) may land in 1.1 — runtime skill capability introspection

For the ecosystem:

A2A's event-driven model aligns well with UCP's mechanism registry pattern
Expect MCP servers to add A2A client capabilities for agent-to-agent delegation
The supported_interfaces field enables multi-protocol agents (HTTP+JSON, gRPC, etc.)

Related:

Published March 26, 2026 · View Repo Pulse · Home