Skip to content

fix(a2a): give RemoteA2aAgent's own error events an error_code - #8163

Open
fponsse wants to merge 2 commits into
google:mainfrom
fponsse:fix/remote-a2a-agent-error-code
Open

fponsse wants to merge 2 commits into
google:mainfrom
fponsse:fix/remote-a2a-agent-error-code

Conversation

@fponsse

@fponsse fponsse commented Nov 15, 2026 •

Copy link
Copy Markdown

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

Problem:

When RemoteA2aAgent itself fails to talk to its peer, it yields an Event with only an error_message: no content and no error_code. A task the remote agent reports as failed does carry an error_code (A2A_TASK_FAILED). So a caller can key off error_code for one kind of failure and has to match error_message for the rest. The a2a:error metadata key was also only on the request-failure paths, not on the card/initialization or authentication failures.

Solution:

  • New constant A2A_CLIENT_ERROR_CODE ("A2A_CLIENT_ERROR") in a2a/converters/utils.py, next to A2A_TASK_FAILED_ERROR_CODE.
  • One helper, _create_client_error_event, builds every error event for a failure of the A2A exchange itself: error_code, error_message, no content, the message under a2a:error, and the request under a2a:request when one was already built (a2a:status_code stays on HTTP errors).
  • It replaces the nine places that built those events by hand: card/initialization failure, authentication failure, HTTP error, any other exception while sending or reading, stream ended before a terminal state, A2AClientError while handling a response (both handlers), unknown response type (both handlers).

What does not change: the error_message texts, the order of the events, the finish_task events of task mode, _create_task_failure_events (a remote task reported as failed in task mode, which #7251 touches), and the events of a failed remote task (A2A_TASK_FAILED). is_final_response() is True for these events before and after.

Effects worth a look (from reading the code, and measured where it says so):

  1. _agent_router._event_filter already skips an event with an error_code and no content when it decides which agent owns the conversation ("A node failure is recorded as an error event without content. It is not a reply..."). These events now fall under that rule. I did not test a setup where the remote agent is transferable.

  2. In a Workflow, a node that emits an event with an error_code is recovered as a failed node, as for a failed task. A new test covers it.

  3. A served agent that contains a failing RemoteA2aAgent (measured: an agent served with to_a2a whose sub-agent is a RemoteA2aAgent with an unreachable card, and a second RemoteA2aAgent as its caller):

    executor of the served agent the caller sees before the caller sees after
    the one selected by default task COMPLETED, no text task FAILED, the failure text, A2A_TASK_FAILED
    A2aAgentExecutor(force_new_version=True) task FAILED, the failure text, A2A_TASK_FAILED task FAILED, the failure text, A2A_CLIENT_ERROR

    So with the default executor a failure the caller never heard about now reaches it, and with the new one the code that crosses is the more specific one. The text is the error_message, which can include the card URL or the exception text; that is already what the new executor forwards for an error_message-only event, and what a failed remote task does. Sanitizing it is the subject of A2aAgentExecutor sends the raw exception text to the A2A caller when the run fails #7385 and fix(a2a): sanitize error message on executor failure to prevent data leak #7402, not of this PR.

Testing Plan

Unit Tests:

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

pytest tests/unittests/a2a/agent: 373 passed. pytest tests/unittests/{a2a,agents,workflow,flows,events,runners,tools}: 8658 passed, 59 skipped, 6 xfailed, 0 failed.

The tests assert error_code == A2A_CLIENT_ERROR_CODE on the existing failure tests (card/initialization, authentication, HTTP error, other exception, stream ended early, A2AClientError, unknown response type), assert the a2a:error metadata on the initialization failure, and add one Workflow test modeled on test_failed_remote_task_in_workflow_is_not_promoted_to_output (node failed, no output, recovered with the new code). Two more cover the client-error paths of the older _handle_a2a_response handler, which had none (the existing tests for those paths only called _handle_a2a_response_v2). The two generic send_message failure tests now raise from a real async generator and pin A2A request failed: Send failed: before, the AsyncMock returned a coroutine, so they failed through 'coroutine' object has no attribute 'aclose' instead of the configured exception. With the constant defined but the behavior left as it was, 15 of them fail.

pre-commit passes on the changed files.

Manual End-to-End (E2E) Tests:

The repro of #8160 (scripted models, no API key). Before, on main (d05e482), cases A (card unreachable) and B (HTTP 500) had error_code=None, and A had no custom_metadata. After:

A. nothing listens on the card URL
  [refunds_remote] content=False error_code=A2A_CLIENT_ERROR custom_metadata=['a2a:error']
      error_message='Failed to initialize remote A2A agent: Failed to initialize remote A2A a'
  events with text for the user in the whole turn: 0
B. card served, message request answered with HTTP 500
  [refunds_remote] content=False error_code=A2A_CLIENT_ERROR custom_metadata=['a2a:error', 'a2a:request', 'a2a:status_code']
      error_message="A2A request failed: HTTP Error 500: Server error '500 Internal Server Er"
  events with text for the user in the whole turn: 0
C. the peer's task ends `failed` (its model raises)
  [refunds_remote] content=False error_code=None            custom_metadata=['a2a:context_id', 'a2a:request', 'a2a:response', 'a2a:task_id']
      error_message='-'
  [refunds_remote] content=True  error_code=None            custom_metadata=['a2a:context_id', 'a2a:request', 'a2a:response', 'a2a:task_id']
      error_message='-'
  [refunds_remote] content=True  error_code=A2A_TASK_FAILED custom_metadata=['a2a:context_id', 'a2a:request', 'a2a:response', 'a2a:task_id']
      error_message='Agent execution failed. (error_id: 3505bf4aee23)'
  events with text for the user in the whole turn: 2

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.

Additional context

The code name is open to change: one code per kind of failure would be a small step from here if the maintainers prefer it.

@google-cla

google-cla Bot commented Nov 15, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

When RemoteA2aAgent itself failed to talk to its peer it yielded an Event
with only an error_message: the agent card or the credential could not be
resolved, the request failed, the stream ended before a terminal task
state, or a response could not be handled. A task the remote agent reports
as failed already carried A2A_TASK_FAILED, so a caller could key off
error_code for that one failure and had to match error_message for the
rest.

These events are now built in one place. They carry the new
A2A_REQUEST_FAILED error code and the message under the a2a:error metadata
key (before, only the request-failure paths had it), plus the request under
a2a:request when one was already built.

Closes google#8160
…r the older handler

Rename the code that RemoteA2aAgent puts on the error events of its own
failures from A2A_REQUEST_FAILED to A2A_CLIENT_ERROR. Those events cover the
agent card, the credential, the request and the stream, so "request" named
only part of them. The new name sits next to A2A_TASK_FAILED as its
counterpart: a failure on the caller's side vs. a failure the peer reported
for its task. The helper that builds the events is renamed to match.

Tests: add the two client-error paths of the older _handle_a2a_response,
which had none (the tests for those paths only called
_handle_a2a_response_v2), and make the two generic send_message failure tests
raise from a real async generator. They used to fail through an AsyncMock
artifact ('coroutine' object has no attribute 'aclose') instead of the
configured exception; they now pin "A2A request failed: Send failed".
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