A2A/docs/sdk/python.md
Darrel b078419954
docs(spec): Large refactor of specification to separate application protocol definition from mapping to transports. (#1160)
Related to #1151 

Fixes https://github.com/a2aproject/A2A/issues/998
Fixes https://github.com/a2aproject/A2A/issues/1091
Fixes https://github.com/a2aproject/A2A/issues/1072
Fixes https://github.com/a2aproject/A2A/issues/1058
Fixes https://github.com/a2aproject/A2A/issues/975
Fixes https://github.com/a2aproject/A2A/issues/1105
Fixes https://github.com/a2aproject/A2A/issues/989
Fixes https://github.com/a2aproject/A2A/issues/1189
Fixes https://github.com/a2aproject/A2A/issues/1187
Fixes https://github.com/a2aproject/A2A/issues/1177
Fixes https://github.com/a2aproject/A2A/issues/1180
Fixes https://github.com/a2aproject/A2A/issues/1172



In order to more effectively describe the A2A protocol in a consistent
way across different protocols, this PR refactors the specification to
describe the application protocol in a transport agnostic way, and then
have separate sections that describe how each of the transports map to
the abstract application protocol. To see a preview of what it looks
like you can go here
https://purple-moss-0838db51e.3.azurestaticapps.net/specification/

The goal of the TSC is to use the changes in this PR as the baseline for
a v1.0 Release Candidate. This will give SDK maintainers an stable
document to validate the changes in the specification through
implementations before v1.0 release.

There are many pending feature requests for the A2A specifications that
the TSC are supportive of. However, getting a stable, consistent,
unambiguous, multi-protocol specification is necessary before additional
features can be added safely.

## Document Restructuring 

- [A2A
Operations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#3-a2a-protocol-operations)
are described independent of wire protocol
- [Protocol Data
Model](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#4-protocol-data-model)
is described using protobuf as source of truth. All other serializations
are derived from that.
- Protocol bindings (formerly described as transports) are now described
in their own sections
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#9-json-rpc-protocol-binding)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#10-grpc-protocol-binding)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#11-httpjsonrest-protocol-binding)
- [Operation Parameters
](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#32-operation-parameter-objects)
describe structures reused across different operations
- [Operation
Semantics](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#33-operation-semantics)
describe common behavior patterns across operations

## New Sections

- [Requirements
Language](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#21-requirements-language)
- [Capability
Validation](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#334-capability-validation)
- [Abstract description of error
handling](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#332-error-handling)
- [Abstract description of
"headers"](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#325-headers)
-
[Extensions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#46-extensions)
-
[Versioning](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#36-versioning)
- [Custom Binding
Guidelines](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#12-custom-binding-guidelines)
- [JSON Field Naming
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#54-json-field-naming-convention)
- [Data Type
Conventions](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#55-data-type-conventions)
- [Security
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#77-security-considerations)
- [Agent Card
Signing](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#84-agent-card-signing)
- [IANA
Considerations](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#13-iana-considerations)

## Protocol Clarifications

- Defining order for events returned from [Stream
Message](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#312-stream-message)
- [JSON
Examples](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#416-filepart)
provided for protobuf definitions of data model objects that previously
used discriminators
- Clarification of returned errors where multiple are applicable. e.g.
[Cancel
Task](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#315-cancel-task)
- Defined returned events and usage scenarios for
[Resubscribe](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#316-resubscribe-to-task)
- Defined protocol binding for errors using protocol native capabilities
for all bindings
-
[JSON-RPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#94-error-handling)
-
[gRPC](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#104-error-handling)
-
[HTTP](https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#115-error-handling)
  
## Artifact Generation

The scripts have been changed to enable a2a.json to be generated from
the a2a.proto so that a2a.proto and specification.md are the only
normative source. Additional work is required to align the generated
a2a.json with the original one.

Release-As: 1.0

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Signed-off-by: Luca Muscariello <lumuscar@cisco.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
2025-11-20 14:52:09 -05:00

773 B

Python SDK

The A2A Python SDK provides a comprehensive set of tools for building A2A-compliant agents and clients.

API Documentation

For detailed API documentation, see the Python SDK API Reference.

  • Client SDK: Build clients to communicate with A2A agents
  • Server SDK: Build A2A-compliant agent servers
  • Models: Data models and type definitions
  • Utilities: Helper functions and utilities

Installation

pip install a2a-sdk

Getting Started

Check out our Python tutorials for step-by-step guides on building A2A agents.

External Resources