Skip to content

V03Compat: silent regression for v0.3 clients sending configuration without explicit blocking: true #386

Description

@xu-shanshan

Summary

After upgrading a server from a2a-dotnet v0.3 to v1 with the V03Compat layer, v0.3 clients that send a configuration field (without explicitly setting blocking: true) silently lose the final agent message and any artifacts enqueued after task completion. The response returns at the first Task event (state Submitted) with no final data, and no exception is raised.

Root cause

  1. V03TypeConverter.ToV1SendMessageRequest maps ReturnImmediately = !cfg.Blocking (src/A2A.V0_3Compat/V03TypeConverter.cs:500).
  2. The v0.3 MessageSendConfiguration.Blocking property defaults to false and is serialized unconditionally (non-nullable bool, default JsonIgnoreCondition.WhenWritingNullsrc/A2A.V0_3/A2AJsonUtilities.cs:55).
  3. The v0.3 server SDK's TaskManager.SendMessageAsync never read Blocking — it always awaited OnTaskCreated (src/A2A.V0_3/Server/TaskManager.cs:144-210). Historically, every v0.3 client got blocking semantics regardless of what they sent.

Net result: any v0.3 client that sends configuration without blocking: true now gets ReturnImmediately = true through the compat layer. The v1 server breaks on the first Task event (src/A2A/Server/A2AServer.cs:638-641), which in typical handler patterns is the Submitted snapshot from TaskUpdater.SubmitAsync. Subsequent Working, artifact, and Completed events are applied to the task store in the background but do not reach the SendMessage response on this call.

Requests

  1. Other known v0.3 SDK consumers — we've already notified the maintainers of work-iq-cli (the one v0.3 client we're aware of), and they will patch it to set blocking: true. Do you know of other teams or projects building on A2A.V0_3 that we should reach? Since the failure mode is silent (no exception, missing data), we'd like to proactively notify any we can before they hit this in production.

  2. Release notes / breaking-change entry on V03Compat — for consumers we can't reach directly, a note calling out the Blocking semantic change (from "ignored" in v0.3 SDK to "honored" in v1 via compat) would let them discover the required change on their own upgrade path.

What we're doing on our side

Notified the maintainers of work-iq-cli; they will patch it to send blocking: true. That's the only v0.3 consumer on our radar, which is why we'd like help identifying others.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions