AG-UI 用 STATE_SNAPSHOT 发送完整共享状态,再用 STATE_DELTA 发送 JSON Patch。客户端收到快照时建立或替换本地基线,收到补丁时按顺序应用。这个示例会把 count 从 0 改为 1。
把业务状态和聊天文本分开看
用共享表单的时候,你可以直接在界面上编辑偏好设置,下一轮agent运行会自动把当前状态塞进输入里,agent也能主动发状态事件同步更新界面。下面的练习只演示服务端往客户端推送的逻辑:先下发count的初始值,再通过一次replace操作修改对应字段。
启动只发送一次状态变化的本地端点
新建一个空的练习目录,先创建Python虚拟环境,安装好用来处理补丁的jsonpatch库,下面的服务代码保存成server.py。
python3 -m venv .venv source .venv/bin/activate python -m pip install ag-ui-protocol==1.0.0 fastapi uvicorn python -m pip install jsonpatch
import asyncio
from uuid import uuid4
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from ag_ui.core import (
RunAgentInput, RunStartedEvent, RunFinishedEvent,
StateSnapshotEvent, StateDeltaEvent,
)
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("/state")
async def run_state(data: RunAgentInput):
return stream(data, [
StateSnapshotEvent(snapshot={"count": 0}),
StateDeltaEvent(delta=[{"op": "replace", "path": "/count", "value": 1}]),
])
python -m uvicorn server:app --host 127.0.0.1 --port 8000
新开一个终端窗口,切到刚才的同一个目录下,新建run.json写入下面的内容,之后请求/state接口,确认两条状态事件都能被捕获到文件里。
{
"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/state > state.sse grep "STATE_" state.sse
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

先替换基线,再按序应用 JSON Patch
把下面的代码保存为state_reader.py,直接在之前创建的虚拟环境里运行就行。如果新开的终端没激活虚拟环境,先执行source .venv/bin/activate,脚本会按响应文件里的事件顺序,完整处理一次Agent运行的全流程。
import json
from pathlib import Path
import jsonpatch
state = None
for line in Path("state.sse").read_text().splitlines():
if not line.startswith("data: "):
continue
event = json.loads(line[6:])
if event["type"] == "STATE_SNAPSHOT":
state = event["snapshot"]
print("snapshot:", json.dumps(state))
elif event["type"] == "STATE_DELTA":
if state is None:
raise SystemExit("No snapshot")
try:
state = jsonpatch.apply_patch(state, event["delta"])
except jsonpatch.JsonPatchException as error:
raise SystemExit(f"Invalid patch: {error}") from error
print("patched: ", json.dumps(state))
python state_reader.py

这个示例里的replace操作要求路径下的/count字段必须已经存在。想测试异常处理逻辑的话,可以先给state.sse做个备份,删掉快照对应的那行data再重跑脚本,就会触发缺失基线的退出逻辑。把原始SSE文件恢复之后,再确认两次状态输出是按预期顺序打印的。
补丁不匹配时如何恢复同步
实际业务场景里,要保证同一次运行下发的所有补丁按顺序全部生效。如果某条补丁无法正常应用,直接停止处理这批增量,按照之前约定的业务规则拉取一份新的完整快照重新同步就好。反复重试失败的旧补丁,很容易把不同时间点的数据混在一起。遇到并发运行的场景,还要提前明确哪些运行允许修改同一份状态,以及前端提交修改时的冲突检查规则。

















