Investigate A2A v1.0 RC impact on AgentStack

[tomkis]

Is your feature request related to a problem? Please describe.
A2A protocol v1.0 RC introduces breaking changes from v0.3 (our current version). We need to assess the impact and plan migration across all AgentStack components (SDK-py, SDK-ts, UI, server).

Describe the solution you'd like
Investigate each v1.0 change and produce a list of affected areas with potential solutions.

Areas of impact

1. Kind discriminator removal (BREAKING)

   • v0.3: polymorphic types (Part, StreamEvent) use kind field as discriminator ({ "kind": "TextPart", ... })
   • v1.0: uses JSON member name / protobuf oneof semantics — field name IS the discriminator
   • Affected: SDK-py a2a/types.py, SDK-ts protocol/schemas.ts, protocol/types.ts, UI message parsing, all extensions emitting Parts
   • Potential solution: update all Part/Event construction and parsing; support both formats during transition

2. Proto-based normative source

   • v1.0 declares spec/a2a.proto as the single authoritative definition
   • Affected: SDK-ts hand-maintained Zod schemas, SDK-py wrapper types
   • Potential solution: generate types from proto; align Zod schemas with proto definitions

3. Service parameters (A2A-Version, A2A-Extensions headers)

   • New HTTP headers for version negotiation and extension declaration
   • Affected: SDK-py server (app.py request handling), SDK-ts client (a2a/client.ts), UI client
   • Potential solution: add header emission on client side, parsing on server side

4. Formalized extension system at protocol level

   • v1.0 adds AgentExtension objects with versioning, required flag, and ExtensionSupportRequiredError
   • Affected: our entire custom extension framework (extensions/base.py, all 17 extensions)
   • Potential solution: align our extension Spec/Server/Client pattern with the v1.0 extension model; evaluate if our URI-based approach is compatible

5. blocking field on SendMessageConfiguration

   • New sync/async execution mode toggle
   • Affected: SDK-py Executor, SDK-ts client, UI run management
   • Potential solution: support blocking param in server handler; expose in client API

6. Extended Agent Card operation

   • New capabilities.extendedAgentCard flag + dedicated fetch operation for authenticated cards
   • Affected: SDK-py AgentCard construction, SDK-ts agent card resolution
   • Potential solution: implement the operation in server; support in client card resolution flow

7. New error types

   • ExtensionSupportRequiredError, VersionNotSupportedError, ExtendedAgentCardNotConfiguredError
   • Affected: SDK-py error handling, SDK-ts error parsing, UI error display
   • Potential solution: add new error types to both SDKs

8. Push notification lifecycle changes

   • Task-scoped configs with full CRUD, cursor-based pagination
   • Affected: SDK-py push_config_store, server push handling
   • Potential solution: update push notification store interface and handlers

9. application/a2a+json media type + .well-known/a2a URI

   • New IANA-registered content type and discovery endpoint
   • Affected: SDK-py server content-type handling, SDK-ts client content-type expectations, agent card discovery
   • Potential solution: support new media type; ensure well-known endpoint alignment (v0.3 already moved to agent-card.json)

10. Upstream SDK upgrades

    • a2a-sdk (Python) and @a2a-js/sdk (TypeScript) will release v1.0-compatible versions
    • Affected: all components depending on these packages
    • Potential solution: track upstream releases; upgrade when available; assess what breaks in our wrapper layer

Additional context

• Current versions: a2a-sdk==0.3.21 (Python), @a2a-js/sdk@^0.3.10 (TypeScript)
• v1.0 is currently RC status, no final release yet
• Spec: https://a2a-protocol.org/dev/specification/
• Releases: https://github.com/a2aproject/A2A/releases

[dosubot]

Hi, @tomkis. I'm Dosu, and I'm helping the agentstack team manage their backlog and am marking this issue as stale.

Issue Summary

• You asked for an impact assessment of A2A v1.0 RC’s breaking protocol changes across AgentStack components.
• The main areas called out were SDK-py, SDK-ts, UI, server, and extensions.
• The likely migration themes were removing kind discriminators, treating the proto as the source of truth, adopting new version/extension headers, supporting the formal extension model, and handling the new blocking field.
• There haven’t been any follow-up comments or confirmed implementation details yet, so the current status is still unresolved.

Next Steps

• If this is still relevant against the latest version of the agentstack repository, please comment here to keep the discussion open.
• Otherwise, this issue will be automatically closed in 7 days.

Thanks for your understanding and contribution.