跳到主要内容

中间件(Middleware)

在 AG-UI 智能体中转换与拦截事件流,实现日志、鉴权、过滤与错误处理。

AG-UI 中的中间件提供了一种强大方式,用于转换、过滤与增强流经智能体的事件流。它让你可以添加日志、鉴权、限流与事件过滤等横切关注点,而无需修改智能体核心逻辑。

以下示例假设已导入相关 RxJS 操作符/工具(map、tap、catchError、switchMap、timer 等)。

什么是中间件

中间件位于智能体执行与事件消费者之间,允许你:

  1. 转换事件 —— 在流经管道时修改或增强事件
  2. 过滤事件 —— 选择性允许或阻止某些事件
  3. 添加元数据 —— 注入额外上下文或跟踪信息
  4. 处理错误 —— 实现自定义错误恢复策略
  5. 监控执行 —— 添加日志、指标或调试能力

工作原理

中间件形成一条链,每个中间件包裹下一个,形成多层功能。智能体运行时,事件流依次经过每个中间件。

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)

执行顺序

中间件按添加顺序执行,每个包裹下一个:

  1. 第一个中间件接收原始输入
  2. 它可在传给下一个之前修改输入
  3. 每个中间件处理来自链中下一个的事件
  4. 最后一个中间件调用实际智能体
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,
}

最佳实践

  1. 保持中间件专注 —— 每个中间件只承担单一职责
  2. 优雅处理错误 —— 使用 RxJS 错误处理操作符
  3. 避免阻塞操作 —— I/O 使用异步模式
  4. 记录副作用 —— 明确说明中间件是否修改状态
  5. 独立测试中间件 —— 为每个中间件编写单元测试
  6. 考虑性能 —— 注意事件流的处理开销

高级用例

条件中间件

根据运行时条件应用中间件:

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 智能体。无论你需要简单的事件转换还是复杂的有状态处理,中间件系统都能帮助你构建健壮、可维护的智能体应用。

Type to search…

↑↓ navigate↵ selectEsc close