diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_client.py b/python/packages/ag-ui/agent_framework_ag_ui/_client.py index 1fbb2901693..323f7689b42 100644 --- a/python/packages/ag-ui/agent_framework_ag_ui/_client.py +++ b/python/packages/ag-ui/agent_framework_ag_ui/_client.py @@ -16,6 +16,8 @@ import httpx from agent_framework import ( + AgentResponse, + AgentResponseUpdate, BaseChatClient, ChatResponse, ChatResponseUpdate, @@ -29,7 +31,7 @@ from agent_framework._tools import FunctionInvocationConfiguration, FunctionInvocationLayer from agent_framework.observability import ChatTelemetryLayer -from ._event_converters import AGUIEventConverter, _finalize_agui_response +from ._event_converters import AGUIEventConverter, _finalize_agui_response, _finalize_agui_updates from ._feature_usage import FeatureIndex from ._http_service import AGUIHttpService, _serialize_available_interrupts, _serialize_resume from ._message_adapters import agent_framework_messages_to_agui @@ -326,6 +328,28 @@ def _get_thread_id(self, options: Mapping[str, Any]) -> str: return thread_id + @override + def _finalize_function_invocation_updates( + self, + updates: Sequence[ChatResponseUpdate], + *, + response_format: Any | None = None, + ) -> ChatResponse[Any]: + """Keep message-linked annotations attached across the complete tool loop.""" + return _finalize_agui_response(updates, response_format=response_format) + + @override + def _finalize_agent_response_updates( + self, + updates: Sequence[AgentResponseUpdate], + *, + response_format: Any | None = None, + ) -> AgentResponse[Any]: + """Preserve message-linked annotations after chat updates are mapped to an agent.""" + return _finalize_agui_updates( + updates, lambda items: AgentResponse.from_updates(items, output_format_type=response_format) + ) + @override def _inner_get_response( self, diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py b/python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py index 08b3614a37b..1560a899b18 100644 --- a/python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py +++ b/python/packages/ag-ui/agent_framework_ag_ui/_event_converters.py @@ -5,10 +5,13 @@ from __future__ import annotations import logging -from collections.abc import Sequence -from typing import Any, cast +from collections.abc import Callable, Sequence +from copy import copy +from typing import Any, TypeVar, cast from agent_framework import ( + AgentResponse, + AgentResponseUpdate, Annotation, ChatResponse, ChatResponseUpdate, @@ -16,42 +19,96 @@ Message, ) +AGUIUpdateT = TypeVar("AGUIUpdateT", ChatResponseUpdate, AgentResponseUpdate) +AGUIResponseT = TypeVar("AGUIResponseT", bound=ChatResponse[Any] | AgentResponse[Any]) + logger = logging.getLogger(__name__) -def _annotation_batch_from_update(update: ChatResponseUpdate) -> tuple[str, list[Annotation]] | None: +def _annotation_batch_from_update( + update: ChatResponseUpdate | AgentResponseUpdate, +) -> tuple[str, list[Annotation]] | None: """Extract a message-linked annotation batch produced by this converter.""" + # Replacement snapshots must keep their message identity during aggregation. + if update.merge_mode == "replace": + return None + custom_event = (update.additional_properties or {}).get("ag_ui_custom_event") if not isinstance(custom_event, dict) or custom_event.get("name") != "annotations" or not update.message_id: return None + # Buffered middleware can copy this response-level event metadata onto a rebuilt message. + # Only the original annotation-only update should be excluded from message aggregation. + value = custom_event.get("value") + if not isinstance(value, dict) or value.get("messageId") != update.message_id: + return None + if any( + content.type != "text" or content.text or content.additional_properties or content.merge_mode == "replace" + for content in update.contents + ): + return None annotations = [ annotation for content in update.contents if content.type == "text" for annotation in content.annotations or [] ] return update.message_id, annotations -def _finalize_agui_response(updates: Sequence[ChatResponseUpdate]) -> ChatResponse: - """Aggregate AG-UI updates while attaching annotation events by message ID.""" +def _finalize_agui_response( + updates: Sequence[ChatResponseUpdate], *, response_format: Any | None = None +) -> ChatResponse[Any]: + """Aggregate chat updates while attaching annotation events by message ID.""" + return _finalize_agui_updates( + updates, lambda items: ChatResponse.from_updates(items, output_format_type=response_format) + ) + + +def _finalize_agui_updates( + updates: Sequence[AGUIUpdateT], aggregate: Callable[[Sequence[AGUIUpdateT]], AGUIResponseT] +) -> AGUIResponseT: + """Attach citations while preserving the response type and original update metadata.""" annotation_batches: list[tuple[str, list[Annotation]]] = [] - aggregatable_updates: list[ChatResponseUpdate] = [] + aggregatable_updates: list[AGUIUpdateT] = [] + run_id: str | None = None + scope = 0 + local_tool_result_pending = False + scoped_message_ids: dict[tuple[int, str], str] = {} + original_message_ids: dict[str, str] = {} for update in updates: + # A local result separates model turns even if middleware removes run markers. + # Server-side AG-UI tool results have no local occurrence id and stay in the run. + if update.role == "tool" and any( + content.type == "function_result" and content.id for content in update.contents + ): + local_tool_result_pending = True + elif local_tool_result_pending and update.message_id: + scope += 1 + run_id = None + local_tool_result_pending = False + update_run_id = (update.additional_properties or {}).get("run_id") + if isinstance(update_run_id, str): + if run_id is not None and update_run_id != run_id: + scope += 1 + local_tool_result_pending = False + # The first observed id names the existing scope; it may arrive after text. + run_id = update_run_id annotation_batch = _annotation_batch_from_update(update) + if update.message_id: + # A later model turn can reuse a protocol ID. Scope aggregation copies only. + key = (scope, update.message_id) + scoped_id = scoped_message_ids.setdefault(key, str(len(scoped_message_ids))) + original_message_ids[scoped_id] = update.message_id + update = copy(update) + update.message_id = scoped_id if annotation_batch is None: aggregatable_updates.append(update) else: - annotation_batches.append(annotation_batch) + annotation_batches.append((cast("str", update.message_id), annotation_batch[1])) + # Keep response-level fields from the event without changing any message. + metadata_update = copy(update) + metadata_update.contents = [] + metadata_update.message_id = metadata_update.role = metadata_update.author_name = None + aggregatable_updates.append(metadata_update) - response = ChatResponse.from_updates(aggregatable_updates) - - # Annotation events are excluded from message aggregation, but their response metadata - # and raw representations retain their original stream ordering. - response.additional_properties.clear() - for update in updates: - if update.additional_properties: - response.additional_properties.update(update.additional_properties) - if updates: - response.raw_representation = [update.raw_representation for update in updates] - response.continuation_token = updates[-1].continuation_token + response = aggregate(aggregatable_updates) for message_id, batch_annotations in annotation_batches: if not batch_annotations: @@ -72,6 +129,9 @@ def _finalize_agui_response(updates: Sequence[ChatResponseUpdate]) -> ChatRespon else: text_content.annotations = [*(text_content.annotations or []), *batch_annotations] + for message in response.messages: + if message.message_id is not None and message.message_id in original_message_ids: + message.message_id = original_message_ids[message.message_id] return response diff --git a/python/packages/ag-ui/tests/ag_ui/test_ag_ui_client.py b/python/packages/ag-ui/tests/ag_ui/test_ag_ui_client.py index 730d011e518..4279d972075 100644 --- a/python/packages/ag-ui/tests/ag_ui/test_ag_ui_client.py +++ b/python/packages/ag-ui/tests/ag_ui/test_ag_ui_client.py @@ -4,7 +4,7 @@ import asyncio import json -from collections.abc import AsyncGenerator, Awaitable, Mapping, MutableSequence +from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, MutableSequence from contextlib import AbstractContextManager, nullcontext from typing import Any, cast @@ -14,6 +14,8 @@ from agent_framework import ( Agent, AgentResponseUpdate, + ChatContext, + ChatMiddleware, ChatOptions, ChatResponse, ChatResponseUpdate, @@ -166,6 +168,20 @@ async def aclose(self) -> None: raise self._close_error +class _OmitRunMetadata(ChatMiddleware): + """Omit optional run markers without changing streamed content.""" + + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + await call_next() + + def omit(update: ChatResponseUpdate) -> ChatResponseUpdate: + if not update.contents and "run_id" in (update.additional_properties or {}): + return ChatResponseUpdate() + return update + + context.stream_update_transforms.append(omit) + + class TestAGUIChatClient: """Test suite for AGUIChatClient.""" @@ -1198,6 +1214,430 @@ async def mock_post_run(*args: object, **kwargs: Any) -> AsyncGenerator[dict[str assert len(response.messages) > 0 assert "Complete response" in response.text + @pytest.mark.parametrize( + "stream,invocation_enabled,consume_stream,strip_run_metadata", + [ + (True, True, True, False), + (True, True, False, False), + (False, True, False, False), + (True, False, True, False), + (True, False, False, False), + (True, True, True, True), + (True, False, False, True), + ], + ids=[ + "loop_iterated", + "loop_final_only", + "nonstream", + "direct_iterated", + "direct_final_only", + "filtered_loop", + "filtered_direct", + ], + ) + @pytest.mark.parametrize("late_annotations", [False, True], ids=["before_later_message", "after_later_message"]) + @pytest.mark.parametrize("as_agent", [False, True], ids=["client", "agent"]) + async def test_public_response_attaches_annotations_to_the_referenced_message( + self, + stream: bool, + invocation_enabled: bool, + consume_stream: bool, + strip_run_metadata: bool, + late_annotations: bool, + as_agent: bool, + ) -> None: + """Public finalization must attach annotations by message ID after later text arrives.""" + annotations = [ + { + "type": "citation", + "url": "https://example.test/source", + "annotated_regions": [{"type": "text_span", "start_index": 0, "end_index": 5}], + } + ] + annotation_event = { + "type": "CUSTOM", + "name": "annotations", + "value": {"messageId": "m1", "annotations": annotations}, + } + + async def handler(request: httpx.Request) -> httpx.Response: + payload = json.loads(await request.aread()) + events: list[dict[str, Any]] = [ + {"type": "RUN_STARTED", "threadId": payload["thread_id"], "runId": payload["run_id"]}, + {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "First"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m1"}, + ] + if not late_annotations: + events.append(annotation_event) + events.extend( + [ + {"type": "TEXT_MESSAGE_START", "messageId": "m2", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m2", "delta": "Second"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m2"}, + ] + ) + if late_annotations: + events.append(annotation_event) + events.append({"type": "RUN_FINISHED", "threadId": payload["thread_id"], "runId": payload["run_id"]}) + return httpx.Response( + 200, + headers={"content-type": "text/event-stream"}, + content="".join(f"data: {json.dumps(event)}\n\n" for event in events).encode(), + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client: + async with AGUIChatClient( + endpoint="https://agui.example.test/", + http_client=http_client, + function_invocation_configuration={"enabled": invocation_enabled}, + middleware=[_OmitRunMetadata()] if strip_run_metadata else [], + ) as client: + get_response = Agent(client=client).run if as_agent else client.get_response + messages = [Message(role="user", contents=["Question"])] + if stream: + response_stream = get_response(messages, stream=True) + updates = [update async for update in response_stream] if consume_stream else [] + response = await response_stream.get_final_response() + annotation_updates = [ + update + for update in updates + if (update.additional_properties or {}).get("ag_ui_custom_event", {}).get("name") + == "annotations" + ] + if consume_stream: + assert len(annotation_updates) == 1 + assert "".join(update.text for update in updates) == "FirstSecond" + else: + response = await get_response(messages) + + assert [(message.message_id, message.text) for message in response.messages] == [ + ("m1", "First"), + ("m2", "Second"), + ] + assert response.messages[0].contents[0].annotations == annotations + assert response.messages[1].contents[0].annotations is None + assert response.additional_properties["ag_ui_custom_event"]["value"] == annotation_event["value"] + + @pytest.mark.parametrize("reuse_message_id", [False, True], ids=["distinct_ids", "reused_id"]) + @pytest.mark.parametrize( + "stream,strip_run_metadata", + [(False, False), (True, False), (True, True)], + ids=["nonstream", "stream", "filtered_stream"], + ) + @pytest.mark.parametrize("as_agent", [False, True], ids=["client", "agent"]) + async def test_public_annotations_preserve_a_completed_client_tool_round( + self, stream: bool, as_agent: bool, reuse_message_id: bool, strip_run_metadata: bool + ) -> None: + """Late annotations must retain one executed call/result pair and the next request's history.""" + executed: list[str] = [] + requests: list[dict[str, Any]] = [] + annotations = [{"type": "citation", "url": "https://example.test/source"}] + earlier_annotations = [{"type": "citation", "url": "https://example.test/earlier-source"}] + planning_id = "m1" if reuse_message_id else "planning" + + @tool(approval_mode="never_require") + def echo(value: str) -> str: + """Return the requested value.""" + executed.append(value) + return value + + async def handler(request: httpx.Request) -> httpx.Response: + payload = json.loads(await request.aread()) + requests.append(payload) + events: list[dict[str, Any]] = [ + {"type": "RUN_STARTED", "threadId": payload["thread_id"], "runId": payload["run_id"]}, + ] + if len(requests) == 1: + events.extend( + [ + {"type": "TEXT_MESSAGE_START", "messageId": planning_id, "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": planning_id, "delta": "Checking"}, + {"type": "TEXT_MESSAGE_END", "messageId": planning_id}, + {"type": "TOOL_CALL_START", "toolCallId": "call-echo", "toolName": "echo"}, + {"type": "TOOL_CALL_ARGS", "toolCallId": "call-echo", "delta": '{"value":"done"}'}, + {"type": "TOOL_CALL_END", "toolCallId": "call-echo"}, + ] + ) + if reuse_message_id: + events.append( + { + "type": "CUSTOM", + "name": "annotations", + "value": {"messageId": "m1", "annotations": earlier_annotations}, + } + ) + else: + annotated_events: list[dict[str, Any]] = [ + {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "First"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m1"}, + {"type": "TEXT_MESSAGE_START", "messageId": "m2", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m2", "delta": "Second"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m2"}, + { + "type": "CUSTOM", + "name": "annotations", + "value": {"messageId": "m1", "annotations": annotations}, + }, + ] + events.extend(annotated_events) + events.append({"type": "RUN_FINISHED", "threadId": payload["thread_id"], "runId": payload["run_id"]}) + return httpx.Response( + 200, + headers={"content-type": "text/event-stream"}, + content="".join(f"data: {json.dumps(event)}\n\n" for event in events).encode(), + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client: + async with AGUIChatClient( + endpoint="https://agui.example.test/", + http_client=http_client, + middleware=[_OmitRunMetadata()] if strip_run_metadata else [], + ) as client: + get_response = Agent(client=client).run if as_agent else client.get_response + messages = [Message(role="user", contents=["Question"])] + options: ChatOptions[None] = ChatOptions(tools=[echo], metadata={"thread_id": "thread-1"}) + if stream: + response_stream = get_response(messages, stream=True, options=options) + updates = [update async for update in response_stream] + response = await response_stream.get_final_response() + assert ( + sum(content.type == "function_result" for update in updates for content in update.contents) == 1 + ) + else: + response = await get_response(messages, options=options) + + assert len(requests) == 2 + assert [request["thread_id"] for request in requests] == ["thread-1", "thread-1"] + assert executed == ["done"] + assert len(messages) == 1 + call_contents = [ + content for message in response.messages for content in message.contents if content.type == "function_call" + ] + result_contents = [ + content + for message in response.messages + for content in message.contents + if content.type == "function_result" + ] + assert len(call_contents) == len(result_contents) == 1 + assert call_contents[0].call_id == result_contents[0].call_id == "call-echo" + text_messages = [(message.message_id, message.text) for message in response.messages if message.text] + assert text_messages == [(planning_id, "Checking"), ("m1", "First"), ("m2", "Second")] + first = next(message for message in response.messages if message.message_id == "m1" and message.text == "First") + assert first.contents[0].annotations == annotations + assert sum(message.message_id == "m1" for message in response.messages) == (2 if reuse_message_id else 1) + if reuse_message_id: + earlier = next(message for message in response.messages if message.text == "Checking") + assert earlier.contents[0].annotations == earlier_annotations + history = requests[1]["messages"] + results = [message for message in history if message.get("role") == "tool"] + assert len(results) == 1 + assert results[0]["toolCallId"] == "call-echo" + assert results[0]["content"] == "done" + + @pytest.mark.parametrize("as_agent", [False, True], ids=["client", "agent"]) + async def test_public_annotation_stream_preserves_structured_output( + self, monkeypatch: MonkeyPatch, as_agent: bool + ) -> None: + """The AG-UI whole-loop finalizer retains the requested structured response type.""" + from pydantic import BaseModel + + class Answer(BaseModel): + reply: str + + annotations = [{"type": "citation", "url": "https://example.test/source"}] + events: list[dict[str, Any]] = [ + {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": '{"reply":"First"}'}, + {"type": "TEXT_MESSAGE_END", "messageId": "m1"}, + {"type": "TEXT_MESSAGE_START", "messageId": "m2", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m2", "delta": '{"reply":"Second"}'}, + {"type": "TEXT_MESSAGE_END", "messageId": "m2"}, + {"type": "CUSTOM", "name": "annotations", "value": {"messageId": "m1", "annotations": annotations}}, + ] + + async def post_run(**kwargs: Any) -> AsyncGenerator[dict[str, Any], None]: + for event in events: + yield event + + async with StubAGUIChatClient(endpoint="https://agui.example.test/") as client: + get_response = Agent(client=client).run if as_agent else client.get_response + monkeypatch.setattr(client.http_service, "post_run", post_run) + messages: list[Message] = [Message(role="user", contents=["Question"])] + options: ChatOptions[Any] = ChatOptions() + options["response_format"] = Answer + response_stream = get_response(messages, stream=True, options=options) + async for _ in response_stream: + pass + response = await response_stream.get_final_response() + + assert [message.message_id for message in response.messages] == ["m1", "m2"] + assert response.messages[0].contents[0].annotations == annotations + assert isinstance(response.value, Answer) + assert response.value.reply == "Second" + + @pytest.mark.parametrize("as_agent", [False, True], ids=["client", "agent"]) + @pytest.mark.parametrize("consume_stream", [False, True], ids=["final_only", "iterated"]) + @pytest.mark.parametrize("replacement", [False, True], ids=["default_merge", "replace"]) + async def test_buffered_final_message_redaction_preserves_previous_text_and_citations( + self, as_agent: bool, consume_stream: bool, replacement: bool + ) -> None: + """An authoritative empty final message must not replace an earlier message.""" + + class RedactFinalMessage(ChatMiddleware): + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + await call_next() + context.stream_buffer_updates = True + + def to_updates(response: ChatResponse[Any]) -> list[ChatResponseUpdate]: + updates = response.to_updates() + if replacement: + for update in updates: + update.merge_mode = "replace" + return updates + + context.stream_result_to_updates = to_updates + + def redact(response: ChatResponse[Any]) -> ChatResponse[Any]: + for message in response.messages: + if message.message_id == "m2": + for content in message.contents: + if content.type == "text": + content.text = "" + return response + + context.stream_result_transforms.append(redact) + + annotations = [{"type": "citation", "url": "https://example.test/final-source"}] + + async def handler(request: httpx.Request) -> httpx.Response: + payload = json.loads(await request.aread()) + events: list[dict[str, Any]] = [ + {"type": "RUN_STARTED", "threadId": payload["thread_id"], "runId": payload["run_id"]}, + {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "First"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m1"}, + {"type": "TEXT_MESSAGE_START", "messageId": "m2", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m2", "delta": "Second"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m2"}, + {"type": "CUSTOM", "name": "annotations", "value": {"messageId": "m2", "annotations": annotations}}, + {"type": "RUN_FINISHED", "threadId": payload["thread_id"], "runId": payload["run_id"]}, + ] + wire = "".join("data: " + json.dumps(event) + "\n\n" for event in events).encode() + return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=wire) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client: + async with AGUIChatClient( + endpoint="https://agui.example.test/", http_client=http_client, middleware=[RedactFinalMessage()] + ) as client: + run = Agent(client=client).run if as_agent else client.get_response + messages: list[Message] = [Message(role="user", contents=["Question"])] + stream = run(messages, stream=True) + updates = [update async for update in stream] if consume_stream else [] + response = await stream.get_final_response() + + actual = [(message.message_id, message.text) for message in response.messages] + assert actual == [("m1", "First"), ("m2", "")], actual + assert response.messages[0].contents[0].annotations is None + assert response.messages[1].contents[0].annotations == annotations + assert response.additional_properties["ag_ui_custom_event"]["value"] == { + "messageId": "m2", + "annotations": annotations, + } + if consume_stream: + assert "".join(update.text for update in updates) == "First" + + @pytest.mark.parametrize("transform_mode", ["uppercase", "redacted", "replacement"]) + @pytest.mark.parametrize("message_count", [1, 2], ids=["same_message", "later_message"]) + @pytest.mark.parametrize("batch_count", [1, 2], ids=["one_batch", "two_batches"]) + @pytest.mark.parametrize("as_agent", [False, True], ids=["client", "agent"]) + async def test_buffered_middleware_preserves_rebuilt_text_and_annotations( + self, monkeypatch: MonkeyPatch, as_agent: bool, message_count: int, batch_count: int, transform_mode: str + ) -> None: + """Response-level annotation metadata must not hide text rebuilt by middleware.""" + from collections.abc import Callable + + from agent_framework import ChatContext, ChatMiddleware + + redact_text = transform_mode != "uppercase" + + class TransformMiddleware(ChatMiddleware): + async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None: + await call_next() + context.stream_buffer_updates = True + + def to_updates(response: ChatResponse[Any]) -> list[ChatResponseUpdate]: + updates = response.to_updates() + if transform_mode == "replacement": + for update in updates: + update.merge_mode = "replace" + return updates + + context.stream_result_to_updates = to_updates + + def transform_text(response: ChatResponse[Any]) -> ChatResponse[Any]: + for message in response.messages: + for content in message.contents: + if content.type == "text" and content.text is not None: + content.text = "" if redact_text else content.text.upper() + if transform_mode == "redacted": + content.additional_properties["redacted"] = True + return response + + context.stream_result_transforms.append(transform_text) + + annotations = [ + {"type": "citation", "url": f"https://example.test/source-{index}"} for index in range(batch_count) + ] + events: list[dict[str, Any]] = [ + {"type": "TEXT_MESSAGE_START", "messageId": "m1", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "First"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m1"}, + ] + if message_count == 2: + events.extend( + [ + {"type": "TEXT_MESSAGE_START", "messageId": "m2", "role": "assistant"}, + {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m2", "delta": "Second"}, + {"type": "TEXT_MESSAGE_END", "messageId": "m2"}, + ] + ) + events.extend( + {"type": "CUSTOM", "name": "annotations", "value": {"messageId": "m1", "annotations": [annotation]}} + for annotation in annotations + ) + + async def post_run(**kwargs: Any) -> AsyncGenerator[dict[str, Any], None]: + for event in events: + yield event + + async with StubAGUIChatClient( + endpoint="https://agui.example.test/", middleware=[TransformMiddleware()] + ) as client: + get_response = Agent(client=client).run if as_agent else client.get_response + monkeypatch.setattr(client.http_service, "post_run", post_run) + messages: list[Message] = [Message(role="user", contents=["Question"])] + response_stream = get_response(messages, stream=True) + updates = [update async for update in response_stream] + response = await response_stream.get_final_response() + + expected = [("m1", "" if redact_text else "FIRST")] + ( + [("m2", "" if redact_text else "SECOND")] if message_count == 2 else [] + ) + assert [(message.message_id, message.text) for message in response.messages] == expected + assert "".join(update.text for update in updates) == "".join(text for _, text in expected) + assert response.messages[0].contents[0].annotations == annotations + if transform_mode == "redacted": + assert all( + content.additional_properties["redacted"] + for message in response.messages + for content in message.contents + if content.type == "text" + ) + assert response.additional_properties["ag_ui_custom_event"]["value"]["messageId"] == "m1" + async def test_tool_handling(self, monkeypatch: MonkeyPatch) -> None: """Test that client tool metadata is sent to server. diff --git a/python/packages/ag-ui/tests/ag_ui/test_event_converters.py b/python/packages/ag-ui/tests/ag_ui/test_event_converters.py index ba4be008879..e3320a8fbf2 100644 --- a/python/packages/ag-ui/tests/ag_ui/test_event_converters.py +++ b/python/packages/ag-ui/tests/ag_ui/test_event_converters.py @@ -6,9 +6,9 @@ from typing import Any, cast import pytest -from agent_framework import ChatResponse +from agent_framework import Annotation, ChatResponse, Content, Message -from agent_framework_ag_ui._event_converters import AGUIEventConverter, _finalize_agui_response +from agent_framework_ag_ui._event_converters import AGUIEventConverter, _finalize_agui_response, _finalize_agui_updates class TestAGUIEventConverter: @@ -484,6 +484,91 @@ def test_malformed_annotations_custom_event_preserves_metadata( assert update.additional_properties["ag_ui_custom_event"]["value"] == value assert "annotations" in caplog.text + def test_finalizer_preserves_rebuilt_empty_message_with_response_event_metadata(self) -> None: + """Metadata copied to a different message is not a message-linked annotation event.""" + annotations = [Annotation(type="citation", url="https://example.test/source")] + original = ChatResponse( + messages=[ + Message( + role="assistant", message_id="m1", contents=[Content.from_text("First", annotations=annotations)] + ), + Message(role="assistant", message_id="m2", contents=[Content.from_text("")]), + ], + additional_properties={ + "ag_ui_custom_event": {"name": "annotations", "value": {"messageId": "m1", "annotations": annotations}} + }, + ) + + response = _finalize_agui_response(original.to_updates()) + + assert [(message.message_id, message.text) for message in response.messages] == [("m1", "First"), ("m2", "")] + assert response.messages[0].contents[0].annotations == annotations + assert response.additional_properties == original.additional_properties + + def test_agent_finalizer_preserves_metadata_from_annotation_only_update(self) -> None: + """Mapped annotation events retain agent-only fields without creating an empty duplicate.""" + from agent_framework import AgentResponse, AgentResponseUpdate, ContinuationToken + from pydantic import BaseModel + + class CursorToken(ContinuationToken): + cursor: str + + class Answer(BaseModel): + reply: str + + token = CursorToken(cursor="next") + annotations = [Annotation(type="citation", url="https://example.test/source")] + updates = [ + AgentResponseUpdate( + role="assistant", + message_id="m1", + contents=[Content.from_text("First")], + raw_representation={"index": 0}, + ), + AgentResponseUpdate( + role="assistant", + message_id="m2", + contents=[Content.from_text('{"reply":"Second"}')], + raw_representation={"index": 1}, + ), + AgentResponseUpdate( + role="assistant", + message_id="m1", + contents=[Content.from_text("", annotations=annotations)], + agent_id="agent-2", + response_id="response-2", + finish_reason="stop", + continuation_token=token, + additional_properties={ + "ag_ui_custom_event": { + "name": "annotations", + "value": {"messageId": "m1", "annotations": annotations}, + } + }, + raw_representation={"index": 2}, + ), + ] + + response = _finalize_agui_updates( + updates, lambda items: AgentResponse.from_updates(items, output_format_type=Answer) + ) + + assert [(message.message_id, message.text) for message in response.messages] == [ + ("m1", "First"), + ("m2", '{"reply":"Second"}'), + ] + assert response.messages[0].contents[0].annotations == annotations + assert response.agent_id == "agent-2" + assert response.response_id == "response-2" + assert response.finish_reason == "stop" + assert response.continuation_token == token + assert response.raw_representation == [{"index": 0}, {"index": 1}, {"index": 2}] + assert response.additional_properties == updates[-1].additional_properties + assert isinstance(response.value, Answer) + assert response.value.reply == "Second" + assert updates[-1].message_id == "m1" + assert updates[-1].contents[0].annotations == annotations + def test_full_conversation_flow(self) -> None: """Test complete conversation flow with multiple event types.""" converter = AGUIEventConverter() diff --git a/python/packages/core/agent_framework/_agents.py b/python/packages/core/agent_framework/_agents.py index 38ee6a3cb38..54b313a4247 100644 --- a/python/packages/core/agent_framework/_agents.py +++ b/python/packages/core/agent_framework/_agents.py @@ -1517,6 +1517,10 @@ def _finalize_response_updates( response_format: Any | None = None, ) -> AgentResponse[Any]: """Finalize response updates into a single AgentResponse.""" + if isinstance(self.client, BaseChatClient): + return self.client._finalize_agent_response_updates( # pyright: ignore[reportPrivateUsage] + updates, response_format=response_format + ) return AgentResponse.from_updates( updates, output_format_type=response_format, diff --git a/python/packages/core/agent_framework/_clients.py b/python/packages/core/agent_framework/_clients.py index ccd1a8ee26e..7c0b8c00d59 100644 --- a/python/packages/core/agent_framework/_clients.py +++ b/python/packages/core/agent_framework/_clients.py @@ -31,6 +31,8 @@ from ._docstrings import apply_layered_docstring from ._serialization import SerializationMixin from ._types import ( + AgentResponse, + AgentResponseUpdate, ChatResponse, ChatResponseUpdate, EmbeddingGenerationOptions, @@ -393,6 +395,15 @@ def _finalize_response_updates( output_format_type=response_format, ) + def _finalize_agent_response_updates( + self, + updates: Sequence[AgentResponseUpdate], + *, + response_format: Any | None = None, + ) -> AgentResponse[Any]: + """Aggregate mapped agent updates without reapplying per-model-turn processing.""" + return AgentResponse.from_updates(updates, output_format_type=response_format) + def _build_response_stream( self, stream: AsyncIterable[ChatResponseUpdate] | Awaitable[AsyncIterable[ChatResponseUpdate]], diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 8aa177ec117..826fcc38feb 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -5644,6 +5644,17 @@ def __init__( kwargs["middleware"] = chat_middleware super().__init__(**kwargs) + def _finalize_function_invocation_updates( + self, + updates: Sequence[ChatResponseUpdate], + *, + response_format: Any | None = None, + ) -> ChatResponse[Any]: + """Aggregate all model turns and tool results without reapplying per-turn processing.""" + from ._types import ChatResponse + + return ChatResponse.from_updates(updates, output_format_type=response_format) + def _update_function_invocation_continuation_state( self, kwargs: dict[str, Any], @@ -6386,10 +6397,7 @@ def get_response( client_kwargs: Mapping[str, Any] | None = None, ) -> Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]]: from ._middleware import _as_middleware_list, categorize_middleware # pyright: ignore[reportPrivateUsage] - from ._types import ( - ChatResponse, - ResponseStream, - ) + from ._types import ResponseStream super_get_response = cast( Callable[..., Any], @@ -6515,7 +6523,7 @@ def get_response( def finalize_stream(updates: Sequence[ChatResponseUpdate]) -> ChatResponse[Any]: if invalidation_error: raise invalidation_error[0] - return ChatResponse.from_updates(updates, output_format_type=response_format) + return self._finalize_function_invocation_updates(updates, response_format=response_format) return ResponseStream( self._stream_response_with_function_invocation( diff --git a/python/packages/core/tests/core/test_agents.py b/python/packages/core/tests/core/test_agents.py index 28924882830..79f6736e17a 100644 --- a/python/packages/core/tests/core/test_agents.py +++ b/python/packages/core/tests/core/test_agents.py @@ -5197,3 +5197,81 @@ async def test_psc_flag_on_storing_without_conversation_id_warns_every_call( # Two service calls -> the warning is emitted twice (one per call, not deduped). missing_id_warnings = [r for r in caplog.records if "returned no conversation_id" in r.message] assert len(missing_id_warnings) == 2 + + +@pytest.mark.parametrize("base_client", [False, True], ids=["non_base_client", "base_client"]) +@pytest.mark.parametrize("custom_agent", [False, True], ids=["default_agent", "custom_agent"]) +async def test_stream_finalization_preserves_client_and_agent_extension_points( + client: Any, base_client: bool, custom_agent: bool +) -> None: + """Client delegation preserves the protocol fallback and an agent's existing override.""" + from pydantic import BaseModel + + from agent_framework import ContinuationToken, UsageDetails + + class CursorToken(ContinuationToken): + cursor: str + + class Answer(BaseModel): + reply: str + + calls: list[str] = [] + + class TrackingClient(MockBaseChatClient): + def _finalize_agent_response_updates( + self, updates: Sequence[AgentResponseUpdate], *, response_format: Any | None = None + ) -> AgentResponse[Any]: + calls.append("client") + return super()._finalize_agent_response_updates(updates, response_format=response_format) + + class TrackingAgent(Agent): + def _finalize_response_updates( + self, updates: Sequence[AgentResponseUpdate], *, response_format: Any | None = None + ) -> AgentResponse[Any]: + calls.append("agent") + return AgentResponse.from_updates(updates, output_format_type=response_format) + + chat_client = TrackingClient() if base_client else client + token = CursorToken(cursor="next") + chat_client.streaming_responses = [ + [ + ChatResponseUpdate( + role="assistant", + message_id="m1", + contents=[Content.from_text("First"), Content.from_usage(UsageDetails(input_token_count=3))], + ), + ChatResponseUpdate( + role="assistant", + message_id="m2", + response_id="response-2", + finish_reason="stop", + contents=[ + Content.from_text('{"reply":"Second"}'), + Content.from_usage(UsageDetails(output_token_count=2)), + ], + continuation_token=token, + additional_properties={"custom": "kept"}, + ), + ] + ] + agent = (TrackingAgent if custom_agent else Agent)(client=chat_client, name="example-agent") + options: ChatOptions[Any] = ChatOptions() + options["response_format"] = Answer + response_stream = agent.run("Question", stream=True, options=options) + updates = [update async for update in response_stream] + response = await response_stream.get_final_response() + + assert calls == (["agent"] if custom_agent else ["client"] if base_client else []) + assert len([update for update in updates if update.contents]) == 2 + assert [(message.message_id, message.text) for message in response.messages] == [ + ("m1", "First"), + ("m2", '{"reply":"Second"}'), + ] + assert all(message.author_name == "example-agent" for message in response.messages) + assert response.response_id == "response-2" + assert response.finish_reason == "stop" + assert response.continuation_token == token + assert response.usage_details == {"input_token_count": 3, "output_token_count": 2} + assert response.additional_properties["custom"] == "kept" + assert isinstance(response.value, Answer) + assert response.value.reply == "Second" diff --git a/python/packages/core/tests/core/test_function_invocation_logic.py b/python/packages/core/tests/core/test_function_invocation_logic.py index 73544412e05..54fafe4c72b 100644 --- a/python/packages/core/tests/core/test_function_invocation_logic.py +++ b/python/packages/core/tests/core/test_function_invocation_logic.py @@ -13983,3 +13983,79 @@ def get_streaming_response( assert source.aclose_calls >= 1 assert source.aclose_completed == source.aclose_calls assert source.closed + + +async def test_whole_loop_finalization_preserves_per_turn_metadata_and_response_format(client: Any) -> None: + """Whole-loop aggregation keeps token metadata local and supports clients without BaseChatClient.""" + from agent_framework import ContinuationToken, UsageDetails + + class CursorToken(ContinuationToken): + cursor: str + + class Answer(BaseModel): + reply: str + + token = CursorToken(cursor="next") + executed: list[str] = [] + + @tool(approval_mode="never_require") + def echo(value: str) -> str: + """Return the requested value.""" + executed.append(value) + return value + + first_logprobs = [{"token": "First", "logprob": -0.1}] + last_logprobs = [{"token": "Second", "logprob": -0.2}] + client.streaming_responses = [ + [ + ChatResponseUpdate( + role="assistant", + message_id="first-message", + contents=[Content.from_text("First", additional_properties={"logprobs": first_logprobs})], + ), + ChatResponseUpdate( + role="assistant", + message_id="first-message", + contents=[Content.from_function_call(call_id="call-1", name="echo", arguments='{"value":"done"}')], + ), + ChatResponseUpdate(contents=[Content.from_usage(UsageDetails(input_token_count=3, output_token_count=1))]), + ], + [ + ChatResponseUpdate( + role="assistant", + message_id="last-message", + response_id="response-2", + model="test-model", + contents=[ + Content.from_text('{"reply":"Second"}', additional_properties={"logprobs": last_logprobs}), + Content.from_usage(UsageDetails(input_token_count=5, output_token_count=2)), + ], + continuation_token=token, + finish_reason="stop", + additional_properties={"custom": "kept"}, + ), + ], + ] + messages = [Message(role="user", contents=["Question"])] + response_stream = client.get_response(messages, stream=True, options={"tools": [echo], "response_format": Answer}) + assert isinstance(response_stream, ResponseStream) + updates = [update async for update in response_stream] + response = await response_stream.get_final_response() + + assert executed == ["done"] + assert client.call_count == 2 + assert messages[0].text == "Question" + assert len(messages) == 1 + texts = [content for message in response.messages for content in message.contents if content.type == "text"] + assert [content.additional_properties["logprobs"] for content in texts] == [first_logprobs, last_logprobs] + assert sum(content.type == "function_call" for message in response.messages for content in message.contents) == 1 + assert sum(content.type == "function_result" for message in response.messages for content in message.contents) == 1 + assert response.response_id == "response-2" + assert response.model == "test-model" + assert response.finish_reason == "stop" + assert response.continuation_token == token + assert response.additional_properties["custom"] == "kept" + assert response.usage_details == {"input_token_count": 8, "output_token_count": 3} + assert isinstance(response.value, Answer) + assert response.value.reply == "Second" + assert len(updates) > 0