Skip to content

fix(a2a): stamp a client error code on RemoteA2aAgent's own failures - #8162

Closed
Bensonluo wants to merge 1 commit into
google:mainfrom
Bensonluo:fix/a2a-client-error-code
Closed

Bensonluo wants to merge 1 commit into
google:mainfrom
Bensonluo:fix/a2a-client-error-code

Conversation

@Bensonluo

Copy link
Copy Markdown

Link to Issue or Description of Change

Problem

When RemoteA2aAgent itself fails — resolving the agent card, authenticating, sending the request, or processing a response — the event it yields carries error_message but no error_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-match error_message for the others.

Solution

  • Add A2A_CLIENT_ERROR_CODE = "A2A_CLIENT_ERROR" (defined next to A2A_METADATA_PREFIX, re-exported from google.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 an A2AClientError raised while processing a response;
    • _run_async_impl: credential resolution failure, card initialization failure, the response stream ending before a terminal task state, and both A2A request failed handlers (HTTP error and any other exception).
  • Give those events the same a2a:error custom 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 existing a2a:request alongside the new a2a:error.
  • The value follows the A2A_TASK_FAILED convention: 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:

  • the synthetic finish_task events (function-response carriers; a code would also flip Event.is_final_response() for them);
  • the empty "No parts to send to remote A2A agent." event;
  • interceptor events ("Request intercepted");
  • failed remote task events (already A2A_TASK_FAILED).

Behavior notes from auditing error_code consumers:

  • Event.is_final_response(): these events already returned True through 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 with error_code and 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:

  • I have added or updated unit tests for my change.
  • All unit tests pass locally.

Extended the existing failure-path tests in tests/unittests/a2a/agent/test_remote_a2a_agent.py to assert the code and metadata, and added direct tests for the legacy _handle_a2a_response error paths, which had none:

  • legacy and v2 handlers: unknown response type; A2AClientError while processing a response;
  • credential failure and card initialization failure (message mode and task mode);
  • A2A request failed for the HTTP error and the generic exception handler (message mode and task mode);
  • the stream ending before a terminal task state (working and unknown states), including that a2a:error and a2a:request are present.

The two generic send_message failure tests now drive a real async generator that raises the configured exception. Previously the AsyncMock with side_effect never reached that exception — the production path wraps send_message in contextlib.aclosing, so the surfaced error was a coroutine/aclose mock artifact — and the assertion now pins A2A request failed: Send failed so the tests exercise the intended path.

Results (Python 3.14, a2a-sdk 1.x):

  • pytest tests/unittests/a2a/ — 1025 passed, 57 skipped
  • pytest tests/unittests/agents/ — 998 passed, 1 xfailed
  • pytest tests/unittests/events/ — 256 passed
  • pyink --check and ruff check on the three changed files — clean

Manual End-to-End (E2E) Tests:

Ran the issue's scenario A end to end with no mocks on the resolution path: a RemoteA2aAgent whose 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 carries error_code="A2A_CLIENT_ERROR" and custom_metadata["a2a:error"] equal to the error message:

author        : remote_agent
error_code    : A2A_CLIENT_ERROR
error_message : Failed to initialize remote A2A agent: ... All connection attempts failed
custom_meta   : {'a2a:error': 'Failed to initialize remote A2A agent: ...'}

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_code and metadata.

Checklist

  • I have read the CONTRIBUTING.md document.
  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • I have manually tested my changes end-to-end.
  • Any dependent changes have been merged and published in downstream modules.

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

Copy link
Copy Markdown
Author

Closing this one. @fponsse filed the issue and already has his own fix up in #8163 — the reporter's own take on it should take precedence here. Happy to review that PR if a second pair of eyes is useful.

@Bensonluo Bensonluo closed this Nov 15, 2026
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.

RemoteA2aAgent: its own failures carry error_message but no error_code, unlike a failed remote task

1 participant