Skip to content

fix(a2a): propagate transport, protocol and remote task failures as structured errors (issue #213) - #371

Open
XianReallyHot-ZZH wants to merge 4 commits into
agentic-ai-java:mainfrom
XianReallyHot-ZZH:feat/issue-213-a2a-structured-error-propagation
Open

XianReallyHot-ZZH wants to merge 4 commits into
agentic-ai-java:mainfrom
XianReallyHot-ZZH:feat/issue-213-a2a-structured-error-propagation

Conversation

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor

Contributing to ARGI: propagate A2A streaming and single-body transport, protocol and remote task failures as structured terminal errors (A2aTransportException/A2aProtocolException/A2aRemoteTaskException extending IllegalStateException for legacy catch compatibility) instead of error text followed by a normal done completion — SSE wire-format framing (comments/unknown fields ignored, multi-data lines joined, [DONE] or completed status terminates, missing terminal state fails), JSON-RPC error frames, corrupt frames and remote failed/canceled tasks (both status-update events and Task objects) surface through the existing GraphResponse.error channel with at most one terminal state and partial output identity preserved, error-looking remote body text never treated as a control signal (issue #213).

@yuluo-yx yuluo-yx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dispatchSseEvent() returns on completed status before extracting Task artifacts. Reproduced an SSE frame containing a completed Task with artifact text "answer": only done is emitted and the final result is {reply=""}. Extract the completed Task output before terminating and add a regression test.

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

Thanks for the repro — confirmed and fixed in b0c8557.

Root cause: dispatchSseEvent() returned as soon as isCompletedStatus(result) held, before the frame's output was ever extracted, so a terminal frame carrying the task's final artifacts (a completed Task) delivered only done and the final reply stayed empty.

Fix: the completed flag is now evaluated first and the frame's output is extracted and delivered (accumulated + emitted) before the event terminates the stream. A terminal frame with no extractable output still terminates cleanly, and plain status-update completed frames (which carry no artifacts) behave exactly as before — extractResponseText returns an empty string for them, so nothing extra is emitted or duplicated.

Regression test completedTaskFrameInSseStreamDeliversItsArtifactsBeforeTerminating mirrors the repro: a single SSE frame containing a completed Task with artifact text "answer". It asserts the streamed chunk answer, the done response, and that the final result carries reply=answer instead of an empty string. Full argi-agent-framework suite passes locally (1406 tests, 0 failures).

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

Note on the red test check in run 43885490710: the failure is AgentToolNodeExecutionLeaseTest.parallelDispatchStopsPermitWaiterAfterLeaseLoss (expected: <0> but was: <1>), which is unrelated to this change — nothing here touches tool-node lease dispatch.

Evidence so far:

  • The same class passes 10/10 consecutive local runs on this branch.
  • Upstream main itself hit a different flaky failure in the same concurrency-sensitive package (NeutralToolRuntimeTest.interruptionCancelsSourceAndPreservesInterruptFlag) in run 43727198824 on Nov 15, and the following runs on main went green without any change.
  • This test class already needed a determinism fix before (668d157 "test(agent): make lease-loss cancellation checks deterministic").

The failure mode is a permit-waiter race: with maxParallelTools=1, the queued second tool can acquire the released permit and start before the dispatch loop observes the lease loss and stops the waiters — a window that widens under CI load.

I pushed an empty commit (ec8a289) to re-run the suite. If it flakes again I'm happy to open an upstream issue with this analysis, or to look at making the waiter stop deterministic.

@yuluo-yx yuluo-yx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dispatchSseEvent() ignores final:true. A valid status-update with state=input-required and final=true is followed by A2aProtocolException at EOF because only completed or [DONE] terminates successfully. Honor the final flag after classifying remote failures and add a regression test for this normal interaction boundary.

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

Fixed in 3541a9c.

dispatchSseEvent() now treats an event marked final as terminating, so a valid input-required status-update with final:true ends the stream successfully (the frame's fallback text is still delivered, then done) instead of hitting A2aProtocolException at EOF. The ordering you asked for is explicit in the code: remoteTaskFailure() is classified first, and only a payload that is not a remote failure reaches the completed || final termination check — so failed/canceled with final:true still raise the structured A2aRemoteTaskException.

Two regression tests added:

  • finalStatusUpdateTerminatesTheStreamWithoutProtocolError — your repro shape (input-required + final:true): asserts streamed output then done, no error.
  • finalFlagDoesNotMaskARemoteTaskFailure — failed + final:true: asserts A2aRemoteTaskException with taskState failed.

Test class 26/26, full argi-agent-framework suite green locally (1408 tests, 0 failures).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants