Repository navigation
Description
🔴 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:
- the agent card cannot be resolved, e.g. the peer is down (
Failed to initialize remote A2A agent, L2008-L2017); - the credential cannot be resolved (L1992);
- the request fails, HTTP error or any other exception (
A2A request failed, L2229 and L2251); - the stream ends before a terminal task state (L2208);
- an unknown response type, or an A2A client error while handling a response (L1864, L1881).
Two smaller things in the same code:
- Metadata is not the same on every path. The request-failure paths add
a2a:error,a2a:requestand, for HTTP errors,a2a:status_codetocustom_metadata. The card/initialization failure and the authentication failure add nothing, so that event has noa2a:requesteither. - Other agents in the repo do set a code.
ManagedAgent._error_eventalways setserror_codeandturn_complete=True(agents/_managed_agent.pyL329-L346), and a failed remote task getsA2A_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:
pip install google-adk(I ran it onmain, d05e482, and on 2.14.0, with the same result; a2a-sdk 1.3.0).- 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:
maind05e482 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
Bensonluo commentedon Nov 15, 2026
I'll take this up — stamped a new
A2A_CLIENT_ERROR_CODEon every failure event the agent itself produces (card resolution, auth, the outbound request, response processing) and gave those events the samea2a:errormetadata the request-failure paths already set. Opened #8162 with tests.fix(a2a): give RemoteA2aAgent's own error events an error_code
surajksharma07 commentedon Nov 16, 2026
@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.
fponsse commentedon Nov 16, 2026
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 froma2a:error(the message) anda2a:status_code(HTTP), and one code mirrorsA2A_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:errorin both (initialization, authentication and HTTP errors in task mode; the stream ending inworkingand inunknownstate), 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_responsehandler, 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).