Skip to content

Build and run agents you can see, understand and trust.

fix(app): convert AG-UI SSE stream events (#1917)

YingchaoX8ae700edd5cb
diff --git a/src/agentscope/app/middleware/_protocol/_base.py b/src/agentscope/app/middleware/_protocol/_base.py
index be093bd8b..691836b84 100644
--- a/src/agentscope/app/middleware/_protocol/_base.py
+++ b/src/agentscope/app/middleware/_protocol/_base.py
@@ -1,6 +1,7 @@
# -*- coding: utf-8 -*-
"""Protocol middleware base class for converting AgentEvent stream to
various protocols."""
+
import json
from abc import ABC, abstractmethod
from typing import AsyncGenerator, Callable
@@ -16,9 +17,9 @@ from agentscope.event import AgentEvent
class ProtocolMiddlewareBase(BaseHTTPMiddleware, ABC):
"""Base middleware for converting AgentEvent stream to protocol format.
- This middleware intercepts streaming responses that yield AgentEvent
- objects, deserializes them, and converts them to a specific protocol
- format.
+ This middleware intercepts ``text/event-stream`` responses, deserializes
+ AgentEvent objects from SSE ``data:`` frames, and converts them to a
+ specific protocol format.
Subclasses should implement the `_convert_to_protocol` method to define
the conversion logic for their specific protocol (e.g., AGUI, A2A).
@@ -61,11 +62,15 @@ class ProtocolMiddlewareBase(BaseHTTPMiddleware, ABC):
# Call the next middleware or endpoint
response = await call_next(request)
- # Check if the response is a streaming response
- if isinstance(response, StreamingResponse):
+ content_type = response.headers.get("content-type", "")
+ body_iterator = getattr(response, "body_iterator", None)
+
+ if (
+ content_type.startswith("text/event-stream")
+ and body_iterator is not None
+ ):
# Wrap the original stream with our conversion logic
- original_stream = response.body_iterator
- converted_stream = self._convert_stream(original_stream)
+ converted_stream = self._convert_stream(body_iterator)
# Create a new StreamingResponse with the converted stream
return StreamingResponse(
@@ -91,36 +96,106 @@ class ProtocolMiddlewareBase(BaseHTTPMiddleware, ABC):
Bytes in protocol format.
"""
async for chunk in original_stream:
- # Decode the chunk if it's bytes
if isinstance(chunk, bytes):
chunk_str = chunk.decode("utf-8")
else:
chunk_str = chunk
- # Try to deserialize the chunk as AgentEvent
- try:
- # Parse the JSON string to dict
- event_dict = json.loads(chunk_str)
+ converted = self._convert_sse_frame(chunk_str)
+ if converted is not None:
+ yield converted
+ continue
+
+ # Fallback for subclasses that may override dispatch() to handle
+ # non-SSE streams while still reusing this converter.
+ converted = self._convert_event_json(chunk_str)
+ if converted is not None:
+ yield converted
+ continue
+
+ if isinstance(chunk, bytes):
+ yield chunk
+ else:
+ yield chunk.encode("utf-8")
+
+ def _convert_sse_frame(self, frame: str) -> bytes | None:
+ """Convert AgentEvent payloads inside an SSE frame.
+
+ Note:
+ This method targets the AgentScope service's SSE stream shape:
+ each ``data:`` line contains a complete JSON payload, and each
+ input ``frame`` contains one or more complete SSE frames. SSE
+ multi-line ``data:`` concatenation and cross-chunk frame
+ reassembly are intentionally out of scope here.
- # Deserialize to AgentEvent based on the 'type' field
- agent_event = self._deserialize_event(event_dict)
+ Args:
+ frame: A server-sent event frame.
+
+ Returns:
+ Converted frame bytes if at least one ``data:`` payload was
+ converted, otherwise ``None``.
+ """
+ lines = frame.splitlines(keepends=True)
+ converted_lines: list[str] = []
+ converted_any = False
+
+ for line in lines:
+ if not line.startswith("data:"):
+ converted_lines.append(line)
+ continue
+
+ line_content, line_ending = self._split_line_ending(line)
+ payload = line_content.removeprefix("data:")
+ if payload.startswith(" "):
+ payload = payload[1:]
+
+ converted = self._convert_event_json(payload)
+ if converted is None:
+ converted_lines.append(line)
+ continue
+
+ converted_json = converted.decode("utf-8").rstrip("\n")
+ converted_lines.append(f"data: {converted_json}{line_ending}")
+ converted_any = True
+
+ if not converted_any:
+ return None
+
+ return "".join(converted_lines).encode("utf-8")
+
+ @staticmethod
+ def _split_line_ending(line: str) -> tuple[str, str]:
+ """Split a line into content and its original line ending."""
+ if line.endswith("\r\n"):
+ return line[:-2], "\r\n"
+ if line.endswith("\n"):
+ return line[:-1], "\n"
+ if line.endswith("\r"):
+ return line[:-1], "\r"
+ return line, ""
+
+ def _convert_event_json(self, chunk_str: str) -> bytes | None:
+ """Convert a serialized AgentEvent JSON string.
- # Convert AgentEvent to protocol format
- protocol_data = self._convert_to_protocol(agent_event)
+ Args:
+ chunk_str: Serialized AgentEvent JSON.
- # Serialize and yield the protocol data
- yield json.dumps(protocol_data, ensure_ascii=False).encode(
+ Returns:
+ Converted protocol JSON bytes with trailing newline, or ``None``
+ when ``chunk_str`` is not a valid AgentEvent payload.
+ """
+ try:
+ event_dict = json.loads(chunk_str)
+ agent_event = self._deserialize_event(event_dict)
+ protocol_data = self._convert_to_protocol(agent_event)
+ return (
+ json.dumps(protocol_data, ensure_ascii=False).encode(
"utf-8",
- ) + b"\n"
-
- except (json.JSONDecodeError, KeyError, ValueError):
- # If deserialization fails, pass through the original chunk
- # or log the error
- # For now, we'll pass through the original chunk
- if isinstance(chunk, bytes):
- yield chunk
- else:
- yield chunk.encode("utf-8")
+ )
+ + b"\n"
+ )
+ except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+ return None
def _deserialize_event(self, event_dict: dict) -> AgentEvent:
"""Deserialize event dictionary to AgentEvent object.
diff --git a/tests/agui_protocol_test.py b/tests/agui_protocol_test.py
index 4a1746541..fa6b36ca3 100644
--- a/tests/agui_protocol_test.py
+++ b/tests/agui_protocol_test.py
@@ -1,9 +1,17 @@
# -*- coding: utf-8 -*-
# pylint: disable=protected-access
"""Test cases for AGUI protocol middleware."""
+
+import json
+from typing import AsyncGenerator
from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from fastapi.responses import StreamingResponse
+from fastapi.testclient import TestClient
+
from agentscope.app.middleware import AGUIProtocolMiddleware
from agentscope.event import (
ConfirmResult,
@@ -36,6 +44,148 @@ from agentscope.event import (
from agentscope.message import ToolCallBlock, ToolResultBlock, ToolResultState
+async def _collect_stream(
+ mw: AGUIProtocolMiddleware,
+ chunks: list[str],
+) -> str:
+ """Collect converted stream chunks as text."""
+
+ async def _stream() -> AsyncGenerator[str, None]:
+ """Yield the provided chunks."""
+ for chunk in chunks:
+ yield chunk
+
+ out: list[str] = []
+ async for item in mw._convert_stream(_stream()):
+ out.append(item.decode("utf-8"))
+ return "".join(out)
+
+
+class AGUIProtocolStreamTest(IsolatedAsyncioTestCase):
+ """Test stream-level conversion behavior."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_raw_json_stream_is_converted(self) -> None:
+ """Test raw AgentEvent JSON stream conversion."""
+ event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+
+ body = await _collect_stream(self.mw, [event.model_dump_json()])
+ data = json.loads(body)
+
+ self.assertEqual(data["type"], "RUN_STARTED")
+ self.assertEqual(data["threadId"], "sess_1")
+ self.assertEqual(data["runId"], "reply_1")
+
+ async def test_sse_data_frame_is_converted(self) -> None:
+ """Test AgentEvent JSON inside an SSE data frame is converted."""
+ event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+
+ body = await _collect_stream(
+ self.mw,
+ [f"data: {event.model_dump_json()}\n\n"],
+ )
+ self.assertTrue(body.startswith("data: "))
+
+ data = json.loads(body.removeprefix("data: ").strip())
+ self.assertEqual(data["type"], "RUN_STARTED")
+ self.assertEqual(data["threadId"], "sess_1")
+ self.assertEqual(data["runId"], "reply_1")
+ self.assertNotIn("session_id", data)
+
+ async def test_sse_heartbeat_is_passed_through(self) -> None:
+ """Test SSE heartbeat frames are not modified."""
+ self.assertEqual(
+ await _collect_stream(self.mw, [":\n\n"]),
+ ":\n\n",
+ )
+
+ async def test_sse_data_frame_with_crlf_is_converted(self) -> None:
+ """Test AgentEvent JSON inside a CRLF SSE frame is converted."""
+ event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+
+ body = await _collect_stream(
+ self.mw,
+ [f"data: {event.model_dump_json()}\r\n\r\n"],
+ )
+ self.assertTrue(body.startswith("data: "))
+ self.assertTrue(body.endswith("\r\n\r\n"))
+
+ data = json.loads(body.removeprefix("data: ").strip())
+ self.assertEqual(data["type"], "RUN_STARTED")
+ self.assertEqual(data["threadId"], "sess_1")
+ self.assertEqual(data["runId"], "reply_1")
+
+ async def test_fastapi_sse_response_is_converted(self) -> None:
+ """Test middleware converts a real FastAPI SSE response."""
+ app = FastAPI()
+ app.add_middleware(AGUIProtocolMiddleware)
+
+ @app.get("/sessions/sess_1/stream")
+ async def stream() -> StreamingResponse:
+ event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+
+ async def gen() -> AsyncGenerator[str, None]:
+ yield f"data: {event.model_dump_json()}\n\n"
+
+ return StreamingResponse(gen(), media_type="text/event-stream")
+
+ client = TestClient(app)
+ with client.stream("GET", "/sessions/sess_1/stream") as response:
+ body = "".join(response.iter_text())
+
+ self.assertTrue(body.startswith("data: "))
+ data = json.loads(body.removeprefix("data: ").strip())
+ self.assertEqual(data["type"], "RUN_STARTED")
+ self.assertEqual(data["threadId"], "sess_1")
+ self.assertEqual(data["runId"], "reply_1")
+ self.assertNotIn("session_id", data)
+
+ async def test_fastapi_json_response_is_not_converted(self) -> None:
+ """Test non-SSE responses are outside protocol conversion scope."""
+ app = FastAPI()
+ app.add_middleware(AGUIProtocolMiddleware)
+
+ @app.get("/event")
+ def event() -> JSONResponse:
+ agent_event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+ return JSONResponse(agent_event.model_dump(mode="json"))
+
+ client = TestClient(app)
+ response = client.get("/event")
+
+ self.assertEqual(response.status_code, 200)
+ data = response.json()
+ self.assertEqual(data["type"], "REPLY_START")
+ self.assertEqual(data["session_id"], "sess_1")
+ self.assertNotIn("RUN_STARTED", response.text)
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
class AGUIProtocolLifecycleTest(IsolatedAsyncioTestCase):
"""Test lifecycle event conversions."""