Skip to content

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

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

XianReallyHot-ZZH wants to merge 7 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).

@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.

Two terminal-state gaps remain:

  1. A status-update with state=rejected and final=true bypasses remoteTaskFailure(), emits "Agent State: rejected", and completes successfully. Propagate rejection as a structured remote failure before honoring final.
  2. A valid SSE response containing one kind=message result followed by EOF emits its text, then throws "ended without a terminal state". A standalone A2A Message completes the interaction and needs neither final nor [DONE]. Recognize that outcome and add regression tests for both cases.

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

Both gaps fixed in 1c4346f, test-first (both regression tests were written first and verified red against the previous code, reproducing your two reported outcomes exactly, then green after the fix).

  1. rejected is now part of remoteTaskFailure()'s failure states alongside failed/canceled, so a rejected status-update — with or without final:true — propagates as a structured A2aRemoteTaskException (taskState rejected) before the terminal check runs. Since the classifier is shared, single-body Task results with rejected classify identically.

  2. A standalone kind:message result now terminates the stream successfully: its parts text is extracted and delivered, then done — no final flag or [DONE] sentinel required, and no missing-terminal-state error at EOF. The three successful-termination shapes (completed status, final event, standalone Message) are consolidated behind one isTerminalEvent() predicate in dispatchSseEvent().

Regression tests: rejectedStatusWithFinalFlagFailsTheStreamWithRemoteTaskError (red: completed successfully with placeholder text → green: A2aRemoteTaskException) and standaloneMessageResultTerminatesTheStreamWithoutProtocolError (red: your exact A2A event stream ended without a terminal state at EOF → green: text + done + final reply). Test class 28/28; full argi-agent-framework suite green locally (1410 tests, 0 failures).

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

The red license-check in run 44430136605 is an infrastructure failure, not a license problem: the job failed while downloading the checker (make tools) because sum.golang.org returned INTERNAL_ERROR serving a go-git checksum tile — the check itself never ran. No files were added in 1c4346f, and the other six checks (including test) are green. Retriggered with an empty commit (c52ed72).

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

The test check in run 44434068638 is another flake in the same concurrency-sensitive package: NeutralToolRuntimeTest.interruptionCancelsSourceAndPreservesInterruptFlag — the same test that flaked on main itself in run 43727198824 on Nov 15 and went green on the next run without any change. Note this red is on the empty retrigger commit c52ed72, whose tree is identical to 1c4346f — the same tree passed test green one hour earlier in run 44430136438, so the outcome is provably independent of any code. Retriggered once more (198d3dd); if this keeps recurring I will open an issue with the full incident history for the node package flakes.

@XianReallyHot-ZZH

Copy link
Copy Markdown
Contributor Author

Follow-up: filed #379 with the full incident ledger for the agent.orchestration.node flakes (including the main-branch occurrence and the same-tree green-then-red proof), plus an offer to work on determinism if maintainers want it.

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