wehub-resource-sync
a9cd7750f4
3.7 KiB
6. Versioning — v0.2.5 → v0.3.0 → v1.0
The biggest practical gotcha in A2A right now is that two materially different spec
generations are live at once. The site's /latest/ already points to v1.0, but the
broad SDK and deployed-agent ecosystem is still largely on v0.3.x (and plenty on v0.2.5).
They are not interchangeable on the wire — enum spellings, polymorphism, and several field
names differ. Pin your target version explicitly.
6.1 The two models
| Aspect | v0.2.x / v0.3.x (JSON-RPC-first) | v1.0 (Protobuf-first / ProtoJSON) |
|---|---|---|
| Source of truth | JSON Schema / TS types | specification/a2a.proto (pkg lf.a2a.v1) — JSON schema is a generated artifact |
TaskState |
"submitted", "input-required", … |
TASK_STATE_SUBMITTED, TASK_STATE_INPUT_REQUIRED, … (+TASK_STATE_UNSPECIFIED) |
Message.role |
"user" / "agent" |
ROLE_USER / ROLE_AGENT (+ROLE_UNSPECIFIED) |
| Polymorphism | kind discriminator ("task", "text", "status-update", …) |
no kind — JSON-member / wrapper polymorphism ({ "taskStatusUpdate": {…} }) |
Part file |
mimeType; FileWithBytes.bytes / FileWithUri.uri |
mediaType; file content via raw (bytes) / url members |
| Transport on card | preferredTransport + additionalInterfaces[] (each {url, transport}) |
supportedInterfaces[] (each {url, protocolBinding, protocolVersion}; first = preferred) |
| Extended-card flag | supportsAuthenticatedExtendedCard (top-level) |
capabilities.extendedAgentCard |
AgentCard.protocolVersion |
"0.3.0" |
"1.0" (Major.Minor; patch doesn't affect compatibility) |
| Task listing | — | new tasks/list / ListTasks (paginated, with filters) |
| Per-skill security | — | AgentSkill.security?: string[] added |
| New errors | — | ExtensionSupportRequiredError, VersionNotSupportedError |
6.2 Well-known path changed
- v0.2.5:
https://{domain}/.well-known/agent.json - v0.3.0+ / v1.0:
https://{domain}/.well-known/agent-card.json
A client that hard-codes the wrong path won't discover the agent.
6.3 JSON-RPC method strings persist across versions
Even in v1.0, the JSON-RPC wire method strings stay slash-delimited (message/send,
tasks/get, …). The PascalCase names (SendMessage, GetTask) are the abstract-operation /
gRPC service names. A live v1.0 implementer (AWS Bedrock AgentCore) still emits
"message/send" while advertising the protocol — confirming the slash strings are the
JSON-RPC transport's wire format. (The v1.0 JSON-RPC binding section restating this could not
be fetched directly during research — treat the v1.0 slash-string continuation as well-supported
inference rather than a verbatim quote.)
6.4 SDK reality
The official Python SDK (a2a-sdk) implements v1.0 with a v0.3 compatibility mode
(compat/v0_3/ shims), across all three transports. The v1.0 SDK also renamed/removed
classes (e.g. A2AStarletteApplication and the single-transport A2AClient are gone,
replaced by route factories + ClientFactory/Client). So "which version" affects not just
the wire format but the SDK API you code against. Details in
07-ecosystem-and-samples.md.
6.5 Recommendation for a new integration
- If you need maximum interoperability today, target v0.3.x wire semantics (lowercase
enums,
kind,/.well-known/agent-card.json) — most deployed agents and tutorials assume it. - If you're building green-field against current SDKs, target v1.0 and rely on the SDK's v0.3 compatibility mode for older peers.
- Either way, read the AgentCard's
protocolVersionand adapt; don't assume.