Skip to content

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

Description

@fponsse

🔴 Required Information

Describe the Bug:

When RemoteA2aAgent itself fails to talk to its peer, it reports it as an Event with an error_message, no content and no error_code. When the peer reports that its task failed, the event does carry an error_code (A2A_TASK_FAILED). So a caller that wants to tell "the remote call failed" from a normal event has a stable field for one kind of failure and has to string-match error_message for the others.

The failures that carry no error_code today, all in a2a/agent/_remote_a2a_agent.py:

Two smaller things in the same code:

  • Metadata is not the same on every path. The request-failure paths add a2a:error, a2a:request and, for HTTP errors, a2a:status_code to custom_metadata. The card/initialization failure and the authentication failure add nothing, so that event has no a2a:request either.
  • Other agents in the repo do set a code. ManagedAgent._error_event always sets error_code and turn_complete=True (agents/_managed_agent.py L329-L346), and a failed remote task gets A2A_TASK_FAILED (L195).

This is the client-side counterpart of #6708 (which asked for error_code on a failed remote task and was fixed). The error_message-only events themselves are intended and tested (test_remote_a2a_agent.py asserts "Failed to initialize remote A2A agent" in events[0].error_message); this issue is only about the missing code and the uneven metadata.

Steps to Reproduce:

  1. pip install google-adk (I ran it on main, d05e482, and on 2.14.0, with the same result; a2a-sdk 1.3.0).
  2. Run the script below. It needs no API key: every model is scripted.
"""What does a caller get when a RemoteA2aAgent cannot reach, or cannot finish with, its peer?

A chat root transfers to a `RemoteA2aAgent`. Three ways for the peer call to go wrong; for each, the events the remote agent put on the
caller's stream are printed (content, error_code, error_message, custom_metadata keys). Every model is scripted: no API key needed,
and it prints the same thing every time.

  A. nothing listens on the card URL                 (the agent card cannot be resolved)
  B. the card is served, but the message request gets an HTTP 500
  C. the peer accepts the request and its task ends `failed` (the model of the peer raises)
"""

import asyncio

import uvicorn
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from google.adk.agents import Agent
from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH, RemoteA2aAgent
from google.adk.models.base_llm import BaseLlm
from google.adk.models.llm_response import LlmResponse
from google.adk.runners import InMemoryRunner
from google.genai import types


class ScriptedLlm(BaseLlm):
  model: str = "scripted"
  script: list = []
  calls: list = []

  async def generate_content_async(self, llm_request, stream=False):
    index = len(self.calls)
    self.calls.append(index)
    step = self.script[index]
    if isinstance(step, Exception):
      raise step
    yield LlmResponse(content=types.Content(role="model", parts=step))


class Respond500:
  """ASGI wrapper: the card and everything else pass, the message POST fails."""

  def __init__(self, app):
    self.app = app

  async def __call__(self, scope, receive, send):
    if scope["type"] == "http" and scope["method"] == "POST":
      await send({"type": "http.response.start", "status": 500, "headers": [(b"content-type", b"text/plain")]})
      await send({"type": "http.response.body", "body": b"boom"})
      return
    await self.app(scope, receive, send)


async def serve(app, port):
  server = uvicorn.Server(uvicorn.Config(app, port=port, log_level="critical"))
  task = asyncio.create_task(server.serve())
  while not server.started:
    await asyncio.sleep(0.05)
  return server, task


def remote_agent(model):
  return Agent(name="refunds", description="Answers about orders.", model=model, instruction="Answer.")


async def run_case(title: str, port: int) -> None:
  remote = RemoteA2aAgent(name="refunds_remote", agent_card=f"http://127.0.0.1:{port}{AGENT_CARD_WELL_KNOWN_PATH}")
  root_model = ScriptedLlm(
      script=[[types.Part(function_call=types.FunctionCall(name="transfer_to_agent", args={"agent_name": "refunds_remote"}))]], calls=[]
  )
  root = Agent(name="root", model=root_model, instruction="Transfer.", sub_agents=[remote])
  runner = InMemoryRunner(agent=root)
  session = await runner.session_service.create_session(app_name=runner.app_name, user_id="user")
  print(f"\n{title}")
  user_text = 0
  async for event in runner.run_async(
      user_id="user", session_id=session.id, new_message=types.Content(role="user", parts=[types.Part(text="where is order 42?")])
  ):
    parts = (event.content.parts if event.content else None) or []
    if event.author != "user" and any(p.text for p in parts):
      user_text += 1
    if event.author != "refunds_remote":
      continue
    message = (event.error_message or "-")[:72]
    print(
        f"  [{event.author}] content={bool(parts)!s:5} error_code={event.error_code!s:15} custom_metadata={sorted((event.custom_metadata or {}).keys())}\n"
        f"      error_message={message!r}"
    )
  print(f"  events with text for the user in the whole turn: {user_text}")


async def main() -> None:
  await run_case("A. nothing listens on the card URL", 8139)

  agent = remote_agent(ScriptedLlm(script=[[types.Part(text="unused")]], calls=[]))
  server, task = await serve(Respond500(to_a2a(agent, host="127.0.0.1", port=8140)), 8140)
  await run_case("B. card served, message request answered with HTTP 500", 8140)
  server.should_exit = True
  await task

  agent = remote_agent(ScriptedLlm(script=[RuntimeError("the model of the peer failed")], calls=[]))
  server, task = await serve(to_a2a(agent, host="127.0.0.1", port=8141), 8141)
  await run_case("C. the peer's task ends `failed` (its model raises)", 8141)
  server.should_exit = True
  await task


asyncio.run(main())

Expected Behavior:

Every error event that RemoteA2aAgent emits carries an error_code, so that "the remote call failed" can be detected without parsing error_message. Any stable code would do, one per kind of failure or a single one, and I am happy to follow whatever the maintainers prefer (A2A_TASK_FAILED already exists for the remote's own failure). The card/initialization failure carries the same a2a:error metadata as the request failure.

Observed Behavior:

main (d05e482), a2a-sdk 1.3.0:

A. nothing listens on the card URL
  [refunds_remote] content=False error_code=None            custom_metadata=[]
      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=None            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: 32a68f769ec5)'
  events with text for the user in the whole turn: 2

Cases A and B (both client-side failures) have error_code=None, and A also has no custom_metadata. Only the last event of case C, a failure reported by the peer, has an error_code. Case C also shows two earlier events with error_code=None (the first has no content); they are not what this issue is about.

In cases A and B the turn ends without any event that has text for the user: the caller only learns about the failure by reading error_message (the repro counts the events with text, 0 in both).

Environment Details:

  • ADK Library Version: main d05e482 and 2.14.0 (same output)
  • a2a-sdk: 1.3.0
  • Desktop OS: macOS
  • Python Version: 3.12

Model Information:

  • Are you using LiteLLM: No (scripted models)
  • Which model is being used: none

🟡 Optional Information

Regression:
Not that I know of; the 2.14.0 output is the same.

Related:
#6708 and #7398 (error_code for a failed remote task), #6585 (the unfinished-stream error event), #7918 (task mode, closing the generator at the error event).

Not verified:
How adk web or other front ends render an event that has error_message but no content. What the repro shows is the event itself.

Activity

  1. Bensonluo commented on Nov 15, 2026

    @Bensonluo

    I'll take this up — stamped a new A2A_CLIENT_ERROR_CODE on every failure event the agent itself produces (card resolution, auth, the outbound request, response processing) and gave those events the same a2a:error metadata the request-failure paths already set. Opened #8162 with tests.

  2. added a commit that references this issue on Nov 15, 2026
    da2332a
  3. surajksharma07 commented on Nov 16, 2026

    @surajksharma07
    Collaborator

    @fponsse I can reproduce A and B on 2.14.1 and current main. Both events come back with error_code=None, and the card failure has no a2a:error either.

    As a workaround, wrapping _run_async_impl in a small RemoteA2aAgent subclass that stamps an error_code (plus a2a:error) on the agent’s own content-less error events gave me a stable code for both cases. A2A_TASK_FAILED stays untouched. Could you try that on your side, including task mode and the stream-truncated path, and confirm it holds up before we settle on a direction?

    #8162 and #8163 cover the same ground, so it would help to align on one of them (single code vs one per failure kind) so we can move a single PR forward.

  4. fponsse commented on Nov 16, 2026

    @fponsse
    Author

    Thanks for reproducing it. #8162 was closed by its author in favor of #8163, so #8163 is the only open PR for this.

    On the direction, I'd keep a single code, now named A2A_CLIENT_ERROR. It covers the agent card, the credential, the request and the stream, so the previous name, A2A_REQUEST_FAILED, described only part of it. The kind of failure is still available from a2a:error (the message) and a2a:status_code (HTTP), and one code mirrors A2A_TASK_FAILED: a failure on the caller's side vs. a failure the peer reported for its task. I'm happy to go per kind if you prefer; it is a small change from the shared helper.

    On task mode and the truncated stream: #8163 asserts the code and a2a:error in both (initialization, authentication and HTTP errors in task mode; the stream ending in working and in unknown state), and those tests fail without the change. I have just pushed a commit that renames the code, adds the missing coverage for the older _handle_a2a_response handler, and fixes two existing tests that were passing through an AsyncMock artifact instead of the configured exception. Runs of a2a, agents, workflow, flows, events, runners and tools pass (8658 passed, 0 failed).

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

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions