AG-UI 中的中间件提供了一种强大方式,用于转换、过滤与增强流经智能体的事件流。它让你可以添加日志、鉴权、限流与事件过滤等横切关注点,而无需修改智能体核心逻辑。
以下示例假设已导入相关 RxJS 操作符/工具(map、tap、catchError、switchMap、timer 等)。
什么是中间件
中间件位于智能体执行与事件消费者之间,允许你:
- 转换事件 —— 在流经管道时修改或增强事件
- 过滤事件 —— 选择性允许或阻止某些事件
- 添加元数据 —— 注入额外上下文或跟踪信息
- 处理错误 —— 实现自定义错误恢复策略
- 监控执行 —— 添加日志、指标或调试能力
工作原理
中间件形成一条链,每个中间件包裹下一个,形成多层功能。智能体运行时,事件流依次经过每个中间件。
import { AbstractAgent } from "@ag-ui/client"
const agent = new MyAgent()
// 中间件链:logging -> auth -> filter -> agent
agent.use(loggingMiddleware, authMiddleware, filterMiddleware)
await agent.runAgent()通过 agent.use(...) 添加的中间件在 runAgent() 中生效。connectAgent() 目前直接调用 connect(),不会运行中间件。
函数式中间件
简单转换可使用函数式中间件,这是最简洁的方式:
import { MiddlewareFunction } from "@ag-ui/client"
import { EventType } from "@ag-ui/core"
const prefixMiddleware: MiddlewareFunction = (input, next) => {
return next.run(input).pipe(
map(event => {
if (
event.type === EventType.TEXT_MESSAGE_CHUNK ||
event.type === EventType.TEXT_MESSAGE_CONTENT
) {
return { ...event, delta: `[AI]: ${event.delta}` }
}
return event
})
)
}
agent.use(prefixMiddleware)类式中间件
需要状态或配置的复杂场景使用类式中间件:
import { Middleware } from "@ag-ui/client"
import { Observable } from "rxjs"
import { tap, finalize } from "rxjs/operators"
class MetricsMiddleware extends Middleware {
private eventCount = 0
constructor(private metricsService: MetricsService) {
super()
}
run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
const startTime = Date.now()
return this.runNext(input, next).pipe(
tap(event => {
this.eventCount++
this.metricsService.recordEvent(event.type)
}),
finalize(() => {
this.metricsService.recordDuration(Date.now() - startTime)
this.metricsService.recordEventCount(this.eventCount)
})
)
}
}
agent.use(new MetricsMiddleware(metricsService))编写类式中间件时,优先使用辅助方法:
runNext(input, next)会把 chunk 事件规范化为完整的TEXT_MESSAGE_*/TOOL_CALL_*序列runNextWithState(input, next)还会在每个事件后提供累积的messages与state
内置中间件
FilterToolCallsMiddleware
按允许/禁止列表过滤工具调用:
import { FilterToolCallsMiddleware } from "@ag-ui/client"
// 仅允许特定工具
const allowedFilter = new FilterToolCallsMiddleware({
allowedToolCalls: ["search", "calculate"],
})
// 或阻止特定工具
const blockedFilter = new FilterToolCallsMiddleware({
disallowedToolCalls: ["delete", "modify"],
})
agent.use(allowedFilter)FilterToolCallsMiddleware 过滤发射的 TOOL_CALL_* 事件,不会阻止上游模型/运行时中的工具执行。
常见模式
常见模式包括日志、通过 forwardedProps 鉴权,以及限流。具体实现见 JS 中间件参考。
组合中间件
const logMiddleware: MiddlewareFunction = (input, next) => next.run(input)
const metricsMiddleware = new MetricsMiddleware(metricsService)
const filterMiddleware = new FilterToolCallsMiddleware({ allowedToolCalls: ["search"] })
agent.use(logMiddleware, metricsMiddleware, filterMiddleware)执行顺序
中间件按添加顺序执行,每个包裹下一个:
- 第一个中间件接收原始输入
- 它可在传给下一个之前修改输入
- 每个中间件处理来自链中下一个的事件
- 最后一个中间件调用实际智能体
agent.use(middleware1, middleware2, middleware3)
→ middleware1
→ middleware2
→ middleware3
→ agent.run()
← 事件经 middleware3 返回
← 事件经 middleware2 返回
← 事件经 middleware1 返回RUN_STARTED 上的协议版本
每次运行的 RUN_STARTED.protocolVersion 表示该运行流所使用的版本,而不是谁在转发它(见 Versioning)。对中间件而言,这由谁生产了该运行决定,只有一条规则:
- 转发运行:当
RUN_STARTED来自链中的下一个智能体时,原样传递其protocolVersion。不要添加、覆盖或移除。若下游智能体早于该字段,缺失的声明就是真实情况。 - 合成运行:当中间件自己响应请求并发射自己的
RUN_STARTED(没有下游智能体运行)时,中间件就是该运行的生产者。使用 SDK 的PROTOCOL_VERSION常量声明它所基于的版本;不要镜像客户端的RunAgentInput.protocolVersion,也不要省略该字段。 - 翻译运行:把流转译成不同协议版本的中间件,声明它发射的版本。
合成运行像其他生产者一样使用输入的 threadId 与 runId:
import { EventType, PROTOCOL_VERSION, type RunStartedEvent } from "@ag-ui/client"
const runStarted: RunStartedEvent = {
type: EventType.RUN_STARTED,
threadId: input.threadId,
runId: input.runId,
protocolVersion: PROTOCOL_VERSION,
}最佳实践
- 保持中间件专注 —— 每个中间件只承担单一职责
- 优雅处理错误 —— 使用 RxJS 错误处理操作符
- 避免阻塞操作 —— I/O 使用异步模式
- 记录副作用 —— 明确说明中间件是否修改状态
- 独立测试中间件 —— 为每个中间件编写单元测试
- 考虑性能 —— 注意事件流的处理开销
高级用例
条件中间件
根据运行时条件应用中间件:
const conditionalMiddleware: MiddlewareFunction = (input, next) => {
if (input.forwardedProps?.debug === true) {
return next.run(input).pipe(tap(event => console.debug(event)))
}
return next.run(input)
}事件转换与流控制变体见 JS 中间件参考。
结论
中间件提供了一种灵活而强大的方式,在不修改智能体核心逻辑的前提下扩展 AG-UI 智能体。无论你需要简单的事件转换还是复杂的有状态处理,中间件系统都能帮助你构建健壮、可维护的智能体应用。