Repository navigation
Conversation
A failure of the RemoteA2aAgent itself -- resolving the agent card, authenticating, sending the request, or processing a response -- yielded an event with only an error_message, while a failure the remote peer reported for its task carries error_code A2A_TASK_FAILED. Callers had no stable field to tell these failures from normal events and had to string-match error_message. Every such event now carries error_code A2A_CLIENT_ERROR_CODE and the same a2a:error custom metadata the request-failure paths already set, so all failure events expose a code and a uniform metadata key. The finish_task synthetic events, the empty no-parts event, and interceptor events are unchanged. Fixes google#8160
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Link to Issue or Description of Change
Problem
When
RemoteA2aAgentitself fails — resolving the agent card, authenticating, sending the request, or processing a response — the event it yields carrieserror_messagebut noerror_code, while a failure the remote peer reports for its task does carry one (A2A_TASK_FAILED). A caller that wants to tell a failed remote call from a normal event has a stable field for one kind of failure and has to string-matcherror_messagefor the others.Solution
A2A_CLIENT_ERROR_CODE = "A2A_CLIENT_ERROR"(defined next toA2A_METADATA_PREFIX, re-exported fromgoogle.adk.agents.remote_a2a_agent) and stamp it on every event for a failure of the agent itself:_handle_a2a_response/_handle_a2a_response_v2: unknown response type, and anA2AClientErrorraised while processing a response;_run_async_impl: credential resolution failure, card initialization failure, the response stream ending before a terminal task state, and bothA2A request failedhandlers (HTTP error and any other exception).a2a:errorcustom metadata the request-failure paths already set, so every failure event now carries both a code and a uniform metadata key. The stream-end event keeps its existinga2a:requestalongside the newa2a:error.A2A_TASK_FAILEDconvention: that code marks a failure the peer reported for its task, this one marks a failure on the caller's side. Happy to rename if a different value is preferred.Deliberately unchanged:
finish_taskevents (function-response carriers; a code would also flipEvent.is_final_response()for them);A2A_TASK_FAILED).Behavior notes from auditing
error_codeconsumers:Event.is_final_response(): these events already returnedTruethrough the content-less fall-through, so the new code does not change the result._promote_response_to_output: these events carry no content, so workflow output promotion is unaffected.AgentRouter: an event witherror_codeand no content is now excluded from ownership decisions, which matches the documented intent of that filter ("a node failure ... must not decide which agent owns the conversation").Testing Plan
Unit Tests:
Extended the existing failure-path tests in
tests/unittests/a2a/agent/test_remote_a2a_agent.pyto assert the code and metadata, and added direct tests for the legacy_handle_a2a_responseerror paths, which had none:A2AClientErrorwhile processing a response;A2A request failedfor the HTTP error and the generic exception handler (message mode and task mode);a2a:erroranda2a:requestare present.The two generic
send_messagefailure tests now drive a real async generator that raises the configured exception. Previously theAsyncMockwithside_effectnever reached that exception — the production path wrapssend_messageincontextlib.aclosing, so the surfaced error was a coroutine/aclosemock artifact — and the assertion now pinsA2A request failed: Send failedso the tests exercise the intended path.Results (Python 3.14, a2a-sdk 1.x):
pytest tests/unittests/a2a/— 1025 passed, 57 skippedpytest tests/unittests/agents/— 998 passed, 1 xfailedpytest tests/unittests/events/— 256 passedpyink --checkandruff checkon the three changed files — cleanManual End-to-End (E2E) Tests:
Ran the issue's scenario A end to end with no mocks on the resolution path: a
RemoteA2aAgentwhose card URL points at a dead port (http://127.0.0.1:9/agent.json), driven through_run_async_impl. The real httpx card fetch fails, and the yielded event carrieserror_code="A2A_CLIENT_ERROR"andcustom_metadata["a2a:error"]equal to the error message:The issue's other two scenarios (HTTP 500 on the message POST, peer task failed) are covered by the unit tests through the mocked client, with the same assertions on
error_codeand metadata.Checklist