diff --git a/src/google/adk/a2a/agent/_remote_a2a_agent.py b/src/google/adk/a2a/agent/_remote_a2a_agent.py index fb386377411..31df826a367 100644 --- a/src/google/adk/a2a/agent/_remote_a2a_agent.py +++ b/src/google/adk/a2a/agent/_remote_a2a_agent.py @@ -85,6 +85,7 @@ from ..converters.to_adk_event import MOCK_FUNCTION_CALL_FOR_REQUIRED_USER_AUTH from ..converters.to_adk_event import MOCK_FUNCTION_CALL_FOR_REQUIRED_USER_INPUT from ..converters.utils import _is_failed_status +from ..converters.utils import A2A_CLIENT_ERROR_CODE from ..converters.utils import A2A_TASK_FAILED_ERROR_CODE from ..converters.utils import A2A_TASK_FAILED_ERROR_MESSAGE from ..logs.log_utils import build_a2a_request_log @@ -536,6 +537,39 @@ def _create_task_failure_events( return error_event, finish_event +def _create_client_error_event( + ctx: InvocationContext, + agent_name: str, + error_message: str, + *, + a2a_request: Any = None, + extra_metadata: Optional[dict[str, Any]] = None, +) -> Event: + """Creates the error event for a failure of the A2A exchange itself. + + This is for failures on the caller's side of the wire: the agent card or the + credential cannot be resolved, the request fails, the stream is cut, or a + response cannot be handled. A task the remote agent reports as failed is a + different case and carries ``A2A_TASK_FAILED_ERROR_CODE``. + + Every such event has the same shape: ``error_code``, ``error_message`` and no + content, with the message also under the ``a2a:error`` metadata key and the + request under ``a2a:request`` when one was already built. + """ + metadata: dict[str, Any] = {A2A_METADATA_PREFIX + "error": error_message} + metadata.update(extra_metadata or {}) + if a2a_request: + metadata[A2A_METADATA_PREFIX + "request"] = _compat.a2a_to_dict(a2a_request) + return Event( + author=agent_name, + invocation_id=ctx.invocation_id, + branch=ctx.branch, + error_code=A2A_CLIENT_ERROR_CODE, + error_message=error_message, + custom_metadata=metadata, + ) + + def _add_mock_function_call(event: Event, state: TaskState) -> None: """Generates a mock function call for input-required events if applicable.""" if event.content is None: @@ -1859,11 +1893,8 @@ async def _handle_a2a_response( a2a_response.context_id ) else: - event = Event( - author=self.name, - error_message="Unknown A2A response type", - invocation_id=ctx.invocation_id, - branch=ctx.branch, + event = _create_client_error_event( + ctx, self.name, "Unknown A2A response type" ) # Filter out thought parts from user-facing response content. # Intermediate (submitted/working) events have all parts marked as @@ -1876,11 +1907,8 @@ async def _handle_a2a_response( return event except A2AClientError as e: logger.error("Failed to handle A2A response: %s", e) - return Event( - author=self.name, - error_message=f"Failed to process A2A response: {e}", - invocation_id=ctx.invocation_id, - branch=ctx.branch, + return _create_client_error_event( + ctx, self.name, f"Failed to process A2A response: {e}" ) async def _handle_a2a_response_v2( @@ -1958,20 +1986,14 @@ async def _handle_a2a_response_v2( a2a_response.context_id ) else: - event = Event( - author=self.name, - error_message="Unknown A2A response type", - invocation_id=ctx.invocation_id, - branch=ctx.branch, + event = _create_client_error_event( + ctx, self.name, "Unknown A2A response type" ) return event except A2AClientError as e: logger.error("Failed to handle A2A response: %s", e) - return Event( - author=self.name, - error_message=f"Failed to process A2A response: {e}", - invocation_id=ctx.invocation_id, - branch=ctx.branch, + return _create_client_error_event( + ctx, self.name, f"Failed to process A2A response: {e}" ) async def _run_async_impl( @@ -1991,12 +2013,7 @@ async def _run_async_impl( except Exception as e: # pylint: disable=broad-except task_error_message = f"Failed to authenticate remote A2A agent: {e}" should_release_task_control = True - yield Event( - author=self.name, - error_message=task_error_message, - invocation_id=ctx.invocation_id, - branch=ctx.branch, - ) + yield _create_client_error_event(ctx, self.name, task_error_message) return if auth_request_event: # A pause, not a failure: the invocation resumes once the client @@ -2009,12 +2026,7 @@ async def _run_async_impl( except Exception as e: task_error_message = f"Failed to initialize remote A2A agent: {e}" should_release_task_control = True - yield Event( - author=self.name, - error_message=task_error_message, - invocation_id=ctx.invocation_id, - branch=ctx.branch, - ) + yield _create_client_error_event(ctx, self.name, task_error_message) return # Create A2A request for function response or regular message @@ -2210,19 +2222,8 @@ async def _run_async_impl( ) logger.error(task_error_message) should_release_task_control = True - yield Event( - author=self.name, - error_message=task_error_message, - invocation_id=ctx.invocation_id, - branch=ctx.branch, - custom_metadata=( - { - A2A_METADATA_PREFIX - + "request": _compat.a2a_to_dict(a2a_request), - } - if a2a_request - else None - ), + yield _create_client_error_event( + ctx, self.name, task_error_message, a2a_request=a2a_request ) except _compat.A2A_HTTP_ERRORS as e: @@ -2231,20 +2232,14 @@ async def _run_async_impl( should_release_task_control = True logger.error(error_message) status_code: object = getattr(e, "status_code", None) - custom_metadata: dict[str, Any] = { - A2A_METADATA_PREFIX + "error": error_message, - A2A_METADATA_PREFIX + "status_code": str(status_code), - } - if a2a_request: - custom_metadata[A2A_METADATA_PREFIX + "request"] = ( - _compat.a2a_to_dict(a2a_request) - ) - yield Event( - author=self.name, - error_message=error_message, - invocation_id=ctx.invocation_id, - branch=ctx.branch, - custom_metadata=custom_metadata, + yield _create_client_error_event( + ctx, + self.name, + error_message, + a2a_request=a2a_request, + extra_metadata={ + A2A_METADATA_PREFIX + "status_code": str(status_code) + }, ) except Exception as e: @@ -2252,19 +2247,8 @@ async def _run_async_impl( task_error_message = error_message should_release_task_control = True logger.error(error_message) - custom_metadata = { - A2A_METADATA_PREFIX + "error": error_message, - } - if a2a_request: - custom_metadata[A2A_METADATA_PREFIX + "request"] = ( - _compat.a2a_to_dict(a2a_request) - ) - yield Event( - author=self.name, - error_message=error_message, - invocation_id=ctx.invocation_id, - branch=ctx.branch, - custom_metadata=custom_metadata, + yield _create_client_error_event( + ctx, self.name, error_message, a2a_request=a2a_request ) finally: diff --git a/src/google/adk/a2a/converters/utils.py b/src/google/adk/a2a/converters/utils.py index d38f6363175..0579d17125d 100644 --- a/src/google/adk/a2a/converters/utils.py +++ b/src/google/adk/a2a/converters/utils.py @@ -23,6 +23,10 @@ ADK_CONTEXT_ID_SEPARATOR = "/" A2A_TASK_FAILED_ERROR_CODE = "A2A_TASK_FAILED" A2A_TASK_FAILED_ERROR_MESSAGE = "Remote agent task failed" +# A failure of the A2A exchange itself, on the caller's side: the agent card or +# the credential cannot be resolved, the request fails, the stream is cut. A task +# the remote agent reports as failed carries A2A_TASK_FAILED_ERROR_CODE instead. +A2A_CLIENT_ERROR_CODE = "A2A_CLIENT_ERROR" def _is_failed_status(status: Any) -> bool: diff --git a/tests/unittests/a2a/agent/test_remote_a2a_agent.py b/tests/unittests/a2a/agent/test_remote_a2a_agent.py index c3ea93f6afc..90596c9a807 100644 --- a/tests/unittests/a2a/agent/test_remote_a2a_agent.py +++ b/tests/unittests/a2a/agent/test_remote_a2a_agent.py @@ -60,6 +60,7 @@ from google.adk.a2a.converters.from_adk_event import convert_event_to_a2a_events from google.adk.a2a.converters.part_converter import convert_genai_part_to_a2a_part from google.adk.a2a.converters.utils import _get_adk_metadata_key +from google.adk.a2a.converters.utils import A2A_CLIENT_ERROR_CODE from google.adk.a2a.converters.utils import A2A_TASK_FAILED_ERROR_CODE from google.adk.agents.context import Context from google.adk.agents.invocation_context import InvocationContext @@ -2233,6 +2234,53 @@ async def test_handle_a2a_response_success_with_message(self): assert result.custom_metadata is not None assert A2A_METADATA_PREFIX + "context_id" in result.custom_metadata + @pytest.mark.asyncio + async def test_handle_a2a_response_unknown_response_type(self): + """An unknown response type is reported as a client error event.""" + result = await self.agent._handle_a2a_response(object(), self.mock_context) + + assert result is not None + assert result.author == self.agent.name + assert result.error_message == "Unknown A2A response type" + assert result.error_code == A2A_CLIENT_ERROR_CODE + assert result.custom_metadata == { + A2A_METADATA_PREFIX + "error": "Unknown A2A response type" + } + assert result.content is None + assert result.invocation_id == self.mock_context.invocation_id + assert result.branch == self.mock_context.branch + + @pytest.mark.asyncio + async def test_handle_a2a_response_handles_client_error(self): + """An A2AClientError while converting a response is a client error event.""" + from google.adk.agents.remote_a2a_agent import A2AClientError + + mock_a2a_message = Mock(spec=A2AMessage) + mock_a2a_message.metadata = {} + + with patch( + "google.adk.a2a.agent._remote_a2a_agent.convert_a2a_message_to_event" + ) as mock_convert: + mock_convert.side_effect = A2AClientError("Test client error") + + result = await self.agent._handle_a2a_response( + mock_a2a_message, self.mock_context + ) + + assert result is not None + assert result.author == self.agent.name + assert ( + result.error_message + == "Failed to process A2A response: Test client error" + ) + assert result.error_code == A2A_CLIENT_ERROR_CODE + assert result.custom_metadata == { + A2A_METADATA_PREFIX + "error": result.error_message + } + assert result.content is None + assert result.invocation_id == self.mock_context.invocation_id + assert result.branch == self.mock_context.branch + @pytest.mark.asyncio async def test_handle_a2a_response_message_converter_returns_none(self): """Test _handle_a2a_response returns None when message converter returns None.""" @@ -4520,6 +4568,7 @@ async def test_handle_a2a_response_impl_unknown_response_type(self): assert result is not None assert result.author == self.agent.name assert result.error_message == "Unknown A2A response type" + assert result.error_code == A2A_CLIENT_ERROR_CODE assert result.invocation_id == self.mock_context.invocation_id assert result.branch == self.mock_context.branch @@ -4546,6 +4595,7 @@ async def test_handle_a2a_response_impl_handles_client_error(self): "Failed to process A2A response: Test client error" in result.error_message ) + assert result.error_code == A2A_CLIENT_ERROR_CODE assert result.invocation_id == self.mock_context.invocation_id assert result.branch == self.mock_context.branch @@ -4786,6 +4836,10 @@ async def test_run_async_impl_initialization_failure(self): assert len(events) == 1 assert "Failed to initialize remote A2A agent" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE + assert events[0].custom_metadata == { + A2A_METADATA_PREFIX + "error": events[0].error_message + } @pytest.mark.asyncio async def test_run_async_impl_no_message_parts(self): @@ -5235,7 +5289,12 @@ async def test_run_async_impl_a2a_client_error(self): # Mock A2A client that throws an exception mock_a2a_client = AsyncMock() - mock_a2a_client.send_message.side_effect = Exception("Send failed") + + async def failing_send_message(*args, **kwargs): + raise Exception("Send failed") + yield # An async generator, like the real client's stream. + + mock_a2a_client.send_message = failing_send_message self.agent._a2a_client = mock_a2a_client # _ensure_resolved now returns the client to use for the run. self.agent._ensure_resolved.return_value = mock_a2a_client @@ -5251,7 +5310,8 @@ async def test_run_async_impl_a2a_client_error(self): events.append(event) assert len(events) == 1 - assert "A2A request failed" in events[0].error_message + assert events[0].error_message == "A2A request failed: Send failed" + assert events[0].error_code == A2A_CLIENT_ERROR_CODE @pytest.mark.asyncio async def test_run_async_impl_task_mode_rejects_missing_trigger_fc(self): @@ -5302,6 +5362,7 @@ def set_agent_state_side_effect(agent_name, **kwargs): assert len(events) == 3 assert "Failed to initialize remote A2A agent" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE assert ( events[1].content.parts[0].function_response.name == FINISH_TASK_TOOL_NAME @@ -5428,6 +5489,7 @@ def set_agent_state_side_effect(agent_name, **kwargs): assert len(events) == 3 assert "A2A request failed" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE # The second event should be the finish_task error event assert events[1].content is not None @@ -5574,6 +5636,7 @@ async def test_run_async_impl_initialization_failure(self): assert len(events) == 1 assert "Failed to initialize remote A2A agent" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE @pytest.mark.asyncio async def test_run_async_impl_no_message_parts(self): @@ -5696,7 +5759,12 @@ async def test_run_async_impl_a2a_client_error(self): # Mock A2A client that throws an exception mock_a2a_client = AsyncMock() - mock_a2a_client.send_message.side_effect = Exception("Send failed") + + async def failing_send_message(*args, **kwargs): + raise Exception("Send failed") + yield # An async generator, like the real client's stream. + + mock_a2a_client.send_message = failing_send_message self.agent._a2a_client = mock_a2a_client # _ensure_resolved now returns the client to use for the run. self.agent._ensure_resolved.return_value = mock_a2a_client @@ -5712,7 +5780,8 @@ async def test_run_async_impl_a2a_client_error(self): events.append(event) assert len(events) == 1 - assert "A2A request failed" in events[0].error_message + assert events[0].error_message == "A2A request failed: Send failed" + assert events[0].error_code == A2A_CLIENT_ERROR_CODE @pytest.mark.asyncio async def test_run_live_impl_not_implemented(self): @@ -7069,6 +7138,7 @@ async def test_reports_stream_that_ends_while_task_is_working(self): assert events[1].error_message == ( "A2A response stream ended before task task-1 reached a terminal state." ) + assert events[1].error_code == A2A_CLIENT_ERROR_CODE @pytest.mark.asyncio async def test_reports_stream_that_ends_on_unknown_task_state(self): @@ -7078,6 +7148,7 @@ async def test_reports_stream_that_ends_on_unknown_task_state(self): assert events[1].error_message == ( "A2A response stream ended before task task-1 reached a terminal state." ) + assert events[1].error_code == A2A_CLIENT_ERROR_CODE @pytest.mark.asyncio async def test_accepts_stream_that_ends_on_completed_task(self): @@ -8583,6 +8654,7 @@ async def test_run_async_impl_reports_auth_failure(self): assert len(events) == 1 assert "Failed to authenticate remote A2A agent" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE ensure_resolved.assert_not_called() def _task_context(self): @@ -8610,6 +8682,7 @@ async def test_run_async_impl_releases_task_control_on_auth_failure(self): ) assert "Failed to authenticate remote A2A agent" in events[0].error_message + assert events[0].error_code == A2A_CLIENT_ERROR_CODE assert ( events[1].content.parts[0].function_response.name == FINISH_TASK_TOOL_NAME @@ -9422,6 +9495,46 @@ async def send_message(client, **kwargs): assert recovered["currency@1"].output is None +async def test_unreachable_remote_agent_in_workflow_is_a_failed_node(): + """A card that cannot be resolved fails the node: error code, no output.""" + from google.adk.apps.app import App + from google.adk.workflow._join_node import JoinNode + from google.adk.workflow._workflow import Workflow + from google.adk.workflow.utils import _rehydration_utils + + from tests.unittests import testing_utils + + agent = RemoteA2aAgent( + name="currency", + agent_card=create_test_agent_card(name="currency"), + ) + workflow = Workflow( + name="wf", + edges=[("START", agent, JoinNode(name="join"))], + ) + runner = testing_utils.InMemoryRunner(app=App(name="t", root_agent=workflow)) + with patch.object( + agent, "_ensure_resolved", side_effect=RuntimeError("card unreachable") + ): + events = await runner.run_async(testing_utils.get_user_content("start")) + + failures = [e for e in events if e.error_code == A2A_CLIENT_ERROR_CODE] + assert len(failures) == 1 + assert "card unreachable" in failures[0].error_message + assert failures[0].output is None + join_outputs = [ + e.output + for e in events + if e.output is not None and "join" in (e.node_info.path or "") + ] + assert join_outputs == [{"currency": None}] + recovered = _rehydration_utils._reconstruct_node_states( + events, base_path="wf@1", invocation_id="", group_by_direct_child=True + ) + assert recovered["currency@1"].error_code == A2A_CLIENT_ERROR_CODE + assert recovered["currency@1"].output is None + + @pytest.mark.parametrize("streaming", [True, False], ids=["streaming", "unary"]) async def test_task_mode_sub_agent_returns_remote_task_output( streaming: bool,