简介
中间件实现允许你将现有协议与应用翻译为 AG-UI 事件。它在现有系统与 AG-UI 之间建立桥梁,非常适合为当前应用添加智能体能力。
何时使用中间件实现
- 将现有协议或 API 进行通用化翻译
- 在现有系统或框架的约束内工作
- 当你在无法直接控制智能体框架或系统时
你将构建什么
一个中间件智能体,它:
- 继承
AbstractAgent类 - 连接 OpenAI 的 GPT-4o 模型
- 将 OpenAI 响应翻译为 AG-UI 事件
- 与你的应用在同一进程内运行
前置条件
- Node.js v16+
- 一个 OpenAI API Key
export OPENAI_API_KEY=your-api-key-here构建工具(按需):brew install protobuf、npm i nx、安装 pnpm。
第 1 步 — 脚手架
git clone git@github.com:ag-ui-protocol/ag-ui.git
cd ag-ui/
cp -r integrations/middleware-starter integrations/openai更新 integrations/openai/package.json 元数据,并修改 src/index.ts 中的类名:
export class OpenAIAgent extends AbstractAgent {}将该集成注册到 Dojo(apps/dojo/src/menu.ts 与 agents.ts)。
第 2 步 — 添加到 Dojo 依赖
在 apps/dojo/package.json 中加入:
"@ag-ui/openai": "workspace:*"第 3 步 — 启动 Dojo
pnpm install
pnpm dev打开 http://localhost:3000,选择 OpenAI。此时 stub 智能体会返回 “Hello world!”。
stub 的核心结构:
export class OpenAIAgent extends AbstractAgent {
run(input: RunAgentInput): Observable<BaseEvent> {
const messageId = Date.now().toString()
return new Observable<BaseEvent>((observer) => {
observer.next({ type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId } as any)
observer.next({ type: EventType.TEXT_MESSAGE_START, messageId } as any)
observer.next({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: "Hello world!" } as any)
observer.next({ type: EventType.TEXT_MESSAGE_END, messageId } as any)
observer.next({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId } as any)
observer.complete()
})
}
}第 4 步 — 打通 OpenAI 与 AG-UI
cd integrations/openai
pnpm install openaiAG-UI 回顾
AG-UI 智能体继承 AbstractAgent 并发射事件来表达:
- 生命周期事件:
RUN_STARTED、RUN_FINISHED、RUN_ERROR - 内容事件:
TEXT_MESSAGE_*、TOOL_CALL_*等
实现流式智能体
在构造函数中初始化 OpenAI 客户端,并把 chat.completions 的流式分片转换为 AG-UI 事件:
this.openai.chat.completions
.create({
model: "gpt-4o",
stream: true,
tools: input.tools.map((tool) => ({
type: "function",
function: {
name: tool.name,
description: tool.description,
parameters: tool.parameters,
},
})),
messages: input.messages.map((message) => ({
role: message.role as any,
content: message.content ?? "",
...(message.role === "assistant" && message.toolCalls
? { tool_calls: message.toolCalls }
: {}),
...(message.role === "tool" ? { tool_call_id: message.toolCallId } : {}),
})),
})
.then(async (response) => {
const messageId = Date.now().toString()
for await (const chunk of response) {
if (chunk.choices[0].delta.content) {
observer.next({
type: EventType.TEXT_MESSAGE_CHUNK,
messageId,
delta: chunk.choices[0].delta.content,
} as any)
} else if (chunk.choices[0].delta.tool_calls) {
const toolCall = chunk.choices[0].delta.tool_calls[0]
observer.next({
type: EventType.TOOL_CALL_CHUNK,
toolCallId: toolCall.id,
toolCallName: toolCall.function?.name,
parentMessageId: messageId,
delta: toolCall.function?.arguments,
} as any)
}
}
observer.next({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId } as any)
observer.complete()
})
.catch((error) => {
observer.next({ type: EventType.RUN_ERROR, message: error.message } as any)
observer.error(error)
})底层发生了什么
- 初始化:创建 OpenAI 客户端并发射
RUN_STARTED - 请求:以
stream: true发送用户消息 - 流式转发:每个分片作为
TEXT_MESSAGE_CHUNK或TOOL_CALL_CHUNK转发 - 结束:发射
RUN_FINISHED(或RUN_ERROR)并完成 observable
第 5 步 — 与你的智能体聊天
刷新 Dojo 页面并开始输入,你会看到 GPT-4o 实时逐词返回。
将 AG-UI 桥接到任意协议
你刚刚实现的模式——翻译输入、转发流式分片、发射 AG-UI 事件——适用于几乎所有后端:
- REST 或 GraphQL API
- WebSocket
- MQTT 等 IoT 协议
将智能体连接到前端
像 CopilotKit 这样的工具已理解 AG-UI 并提供即插即用的 React 组件。将智能体端点指向它即可获得完整的聊天 UI。
分享你的集成
结论
你现在拥有了一个可运行的 OpenAI AG-UI 适配器与本地演练环境。接下来可以添加工具调用、发布到 npm,或将 AG-UI 桥接到其他模型/服务。