在本地运行 AG-UI 协议,最简单的方式是用 Python SDK 和 FastAPI 启动一个 SSE 端点,再用 curl 发送 RunAgentInput。这个固定回复示例不需要模型密钥,看到三段文本和 RUN_FINISHED 就能验收。
创建 Python 环境并保存端点代码
先装好 python 3.9 及以上版本。在 macos 或者 linux 系统里新建一个空目录,直接跑下面几条命令就行。我们全程用 1.0.0 版本的 ag-ui-protocol sdk 做验证,固定这个版本能保证所有字段和后续步骤完全对应。
python3 -m venv .venv source .venv/bin/activate python -m pip install ag-ui-protocol==1.0.0 fastapi uvicorn
在当前目录新建一个叫 server.py 的文件,把下面这段代码粘进去。代码把完整的运行流程拆成启动、文本输出、结束三个阶段,每个事件之间加了短延时,方便你直观看到流式响应的效果。
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
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

这个终端窗口别关,保持服务运行。再新开一个终端,切到刚才的同一个目录,把下面的 JSON 内容存成 run.json 文件就行。这里的请求消息只是用来触发运行,服务端会直接返回预设好的固定内容。
{
"threadId": "demo-thread",
"runId": "demo-run-01",
"state": {},
"messages": [{"id":"u1","role":"user","content":"Hello"}],
"tools": [],
"context": [],
"forwardedProps": {}
}
接下来发POST请求测试就行。这里用的--data-binary参数会完整读取JSON文件内容不做修改,-N参数关掉curl的输出缓冲,内容一返回就会直接显示出来,方便你实时看流式输出。
curl -fsSN -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' --data-binary @run.json \ http://127.0.0.1:8000/

核对启动、文本和结束三个状态
先看第一帧返回的 threadId 和 runId 是不是和你请求里填的一致,再检查三个 TEXT_MESSAGE_CONTENT 的 delta 内容拼起来正好是 Hello from AG-UI!,之后还能看到 TEXT_MESSAGE_END 和 RUN_FINISHED 事件。如果只看到 HTTP 200 和部分内容,一定要确认有没有收到最后那个运行终止的事件。
连接失败或收到 422 时怎么查
如果提示连接被拒绝,先看跑服务的那个终端是不是意外退出了,或者有没有自己改默认端口。要是提示8000端口被占用,换个没用过的端口就行,注意启动服务的命令和后面curl的访问地址要同步改。另外直接在浏览器地址栏输地址会发GET请求,这个示例只支持POST请求,当然访问不通。
要是FastAPI返回422报错,用下面这条命令跑,会把完整响应内容打出来,直接看detail里的字段提示就能定位错误。先确认你当前终端是在run.json所在的目录,再检查JSON里的属性名大小写对不对,比如是不是写对了threadId、runId这类驼峰命名。
curl -iSN -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' --data-binary @run.json \ http://127.0.0.1:8000/

















