AG-UI 的流式文本由 TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT 和 TEXT_MESSAGE_END 组成。客户端按 messageId 创建文本槽、依次追加 delta,再结束这条消息。运行是否成功结束,要另外检查 RUN_FINISHED。
用 POST 请求捕获 SSE 文本流
先准备好能返回ag-ui sse流的接口。下面例子用的是监听127.0.0.1:8000的固定返回演示服务,你要是已经有现成服务,直接替换对应url就行。
没有现成端点时,启动独立练习服务
先新建一个空目录装依赖,把后面的Python代码存成server.py,再启动服务就好。
python3 -m venv .venv source .venv/bin/activate python -m pip install ag-ui-protocol==1.0.0 fastapi uvicorn
import asyncio
from uuid import uuid4
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from ag_ui.core import (
RunAgentInput, RunStartedEvent, RunFinishedEvent,
TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent,
)
from ag_ui.encoder import EventEncoder
app = FastAPI()
def stream(data, payloads):
encoder = EventEncoder()
identifiers = {"thread_id": data.thread_id, "run_id": data.run_id}
async def events():
yield encoder.encode(RunStartedEvent(**identifiers))
for event in payloads:
yield encoder.encode(event)
await asyncio.sleep(0.3)
yield encoder.encode(RunFinishedEvent(**identifiers))
return StreamingResponse(events(), media_type=encoder.get_content_type())
@app.post("/")
async def run_text(data: RunAgentInput):
mid = str(uuid4())
return stream(data, [
TextMessageStartEvent(message_id=mid, role="assistant"),
*(TextMessageContentEvent(message_id=mid, delta=part)
for part in ("Hello ", "from ", "AG-UI!")),
TextMessageEndEvent(message_id=mid),
])python -m uvicorn server:app --host 127.0.0.1 --port 8000
新开一个终端,进入刚才的目录,把下面的JSON内容存成run.json。同一个对话要发起新一轮运行的话,记得换个新的runId。
{
"threadId": "demo-thread",
"runId": "demo-run-01",
"state": {},
"messages": [{"id":"u1","role":"user","content":"Hello"}],
"tools": [],
"context": [],
"forwardedProps": {}
}
curl -fsSN -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' --data-binary @run.json \ http://127.0.0.1:8000/
第一次运行直接看终端输出,能直观看到文本逐段出来的节奏,确认流是持续推送的。第二次可以先改个新的runId,把输出存到本地文件,方便逐一核对每个data帧和空行的边界。
curl -fsSN -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' --data-binary @run.json \ http://127.0.0.1:8000/ > text.sse
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

按 messageId 把 delta 拼成完整回答
下面的脚本适配刚才演示生成的、每条JSON单独占一行的SSE文件。把代码存成text_reader.py,和之前生成的text.sse放在同一个目录。逻辑很简单:收到START事件就初始化对应缓冲区,收到CONTENT就原样追加内容,所以千万不要给每段delta加strip处理,等收到END事件再取出整条完整消息。
import json
from pathlib import Path
messages = {}
finished = False
for line in Path("text.sse").read_text().splitlines():
if not line.startswith("data: "):
continue
event = json.loads(line[6:])
kind = event["type"]
if kind == "TEXT_MESSAGE_START":
messages[event["messageId"]] = ""
elif kind == "TEXT_MESSAGE_CONTENT":
messages[event["messageId"]] += event["delta"]
elif kind == "TEXT_MESSAGE_END":
print(messages.pop(event["messageId"]))
elif kind == "RUN_ERROR":
raise SystemExit(event["message"])
elif kind == "RUN_FINISHED":
finished = True
if not finished or messages:
raise SystemExit("Incomplete event stream")
print("RUN_FINISHED")
python3 text_reader.py

要是做网页端对接,内容事件一到就可以直接更新页面上的消息组件,等整条消息结束再执行保存、提交最终结果的逻辑就行。线上正式用的客户端一定要用完整的SSE解帧能力,兼容空行、多data行、注释这类情况。因为浏览器自带的EventSource接口默认发GET请求,对接POST类型的AG-UI端点,要么用官方协议SDK,要么自己通过fetch读取响应流,再交给专门的SSE解析器处理。
已收到部分文字,为什么仍可能失败
RUN_ERROR属于流内主动抛出的错误。要是连接中途断开,全程没收到运行终止事件,要把这次流判定为截断异常做好日志记录。界面上可以保留已经生成的文字,同时标注这条消息未完成。如果你发现直连接口时内容是逐段出来的,走代理之后所有内容才一次性返回,可以先同一个接口分别走直连、走代理两种方式,用curl的-N参数观察输出情况,再排查代理的缓冲设置,以及应用侧每次yield推送事件的时机。
当前HTTP+SSE的对接方案没有用Last-Event-ID做断流续传,重试请求相当于发起全新的运行,得用新的runId。如果这个运行会触发实际的业务写入操作,服务端一定要根据请求参数做幂等校验,判断对应逻辑有没有已经执行过,避免重跑的时候重复写入数据。

















