简介
服务端实现允许你直接从智能体或服务端发射 AG-UI 事件。当你从零构建新智能体,或希望为智能体能力提供独立服务时,这是理想方式。
何时使用服务端实现
- 从零构建新的智能体框架
- 需要对发射哪些事件、如何发射拥有最大控制权
- 将智能体暴露为独立 API
- 尚未使用智能体框架,也还没有为其定义协议
你将构建什么
一个独立的 HTTP 服务端,它:
- 接收 AG-UI 协议请求
- 连接 OpenAI 的 GPT-4o 模型
- 以 AG-UI 事件流式返回响应
- 处理工具调用与状态管理
前置条件
- Python 3.12+
- Poetry(依赖管理)
- 一个 OpenAI API Key
export OPENAI_API_KEY=your-api-key-here构建工具(按需):
brew install protobuf
npm i nx
curl -fsSL https://get.pnpm.io/install.sh | sh -第 1 步 — 脚手架
克隆仓库并复制服务端起始模板:
git clone git@github.com:ag-ui-protocol/ag-ui.git
cd ag-ui
cp -r integrations/server-starter integrations/openai-server更新 integrations/openai-server/package.json 的元数据,并在 src/index.ts 中修改类名:
export class OpenAIServerAgent extends HttpAgent {}将该集成注册到 Dojo(apps/dojo/src/menu.ts 与 agents.ts),便于本地验证。
第 2 步 — 添加到 Dojo 依赖
在 apps/dojo/package.json 的 dependencies 中加入:
"@ag-ui/openai-server": "workspace:*"第 3 步 — 启动 Dojo 与服务端
cd integrations/openai-server/server/python
poetry install && poetry run dev另一个终端:
pnpm install
pnpm dev打开 http://localhost:3000,选择 OpenAI。此时 stub 服务端只会返回 “Hello world!”。
其核心是一个基于 FastAPI 的端点,创建 EventEncoder 并返回 text/event-stream:
@app.post("/")
async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request):
accept_header = request.headers.get("accept")
encoder = EventEncoder(accept=accept_header)
async def event_generator():
yield encoder.encode(
RunStartedEvent(
type=EventType.RUN_STARTED,
thread_id=input_data.thread_id,
run_id=input_data.run_id,
),
)
# ...后续事件
return StreamingResponse(event_generator(), media_type="text/event-stream")第 4 步 — 打通 OpenAI 与 AG-UI
安装 SDK:
poetry add openaiAG-UI 回顾
一个 AG-UI 服务端实现端点并发射一系列事件来表达:
- 生命周期事件:
RUN_STARTED、RUN_FINISHED、RUN_ERROR - 内容事件:
TEXT_MESSAGE_*、TOOL_CALL_*等
实现流式服务端
关键变化:不再返回硬编码消息,而是调用 OpenAI API 并通过 AG-UI 事件流式转发。使用 TEXT_MESSAGE_CHUNK 与 TOOL_CALL_CHUNK 便捷事件可以自动管理消息生命周期:
stream = client.chat.completions.create(
model="gpt-4o",
stream=True,
tools=[...] if input_data.tools else None,
messages=[...],
)
message_id = str(uuid.uuid4())
for chunk in stream:
if chunk.choices[0].delta.content:
yield encoder.encode(
TextMessageChunkEvent(
type=EventType.TEXT_MESSAGE_CHUNK,
message_id=message_id,
delta=chunk.choices[0].delta.content,
)
)
elif chunk.choices[0].delta.tool_calls:
tool_call = chunk.choices[0].delta.tool_calls[0]
yield encoder.encode(
ToolCallChunkEvent(
type=EventType.TOOL_CALL_CHUNK,
tool_call_id=tool_call.id,
tool_call_name=tool_call.function.name if tool_call.function else None,
parent_message_id=message_id,
delta=tool_call.function.arguments if tool_call.function else None,
)
)底层发生了什么
- 初始化:创建 OpenAI 客户端并发射
RUN_STARTED - 请求:以
stream=True将用户消息发送给chat.completions - 流式转发:每个分片作为
TEXT_MESSAGE_CHUNK或TOOL_CALL_CHUNK转发 - 结束:发射
RUN_FINISHED(出错则RUN_ERROR)
测试端点:
curl -X POST http://localhost:8000/ \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"threadId": "thread_123",
"runId": "run_456",
"state": {},
"messages": [
{ "id": "msg_1", "role": "user", "content": "Hello, how are you?" }
],
"tools": [],
"context": [],
"forwardedProps": {}
}'第 5 步 — 与你的服务端聊天
刷新 Dojo 页面并开始输入,你会看到 GPT-4o 逐词流式返回。像 CopilotKit 这样的工具已经理解 AG-UI,将端点指向它即可获得开箱即用的完整聊天 UI。
分享你的集成
结论
你现在拥有了一个可运行的 AG-UI 服务端与本地演练环境。接下来可以:添加工具调用、部署到生产、将 AG-UI 接入其他模型或服务。