---
title: "中间件（Middleware）"
description: "在 AG-UI 智能体中转换与拦截事件流，实现日志、鉴权、过滤与错误处理。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 中间件（Middleware）

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

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

## 什么是中间件

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

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

## 工作原理

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

```ts
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()`，不会运行中间件。

## 函数式中间件

简单转换可使用函数式中间件，这是最简洁的方式：

```ts
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)
```

## 类式中间件

需要状态或配置的复杂场景使用类式中间件：

```ts
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

按允许/禁止列表过滤工具调用：

```ts
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 中间件参考](https://docs.ag-ui.com/sdk/js/client/middleware)。

## 组合中间件

```ts
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. 最后一个中间件调用实际智能体

```text
agent.use(middleware1, middleware2, middleware3)

→ middleware1
  → middleware2
    → middleware3
      → agent.run()
    ← 事件经 middleware3 返回
  ← 事件经 middleware2 返回
← 事件经 middleware1 返回
```

## `RUN_STARTED` 上的协议版本

每次运行的 `RUN_STARTED.protocolVersion` 表示该运行流所使用的版本，而不是谁在转发它（见 [Versioning](https://docs.ag-ui.com/spec/1-0/basic/versioning#version-negotiation)）。对中间件而言，这由**谁生产了该运行**决定，只有一条规则：

- **转发运行**：当 `RUN_STARTED` 来自链中的下一个智能体时，原样传递其 `protocolVersion`。不要添加、覆盖或移除。若下游智能体早于该字段，缺失的声明就是真实情况。
- **合成运行**：当中间件自己响应请求并发射自己的 `RUN_STARTED`（没有下游智能体运行）时，中间件就是该运行的生产者。使用 SDK 的 `PROTOCOL_VERSION` 常量声明它所基于的版本；不要镜像客户端的 `RunAgentInput.protocolVersion`，也不要省略该字段。
- **翻译运行**：把流转译成不同协议版本的中间件，声明它发射的版本。

合成运行像其他生产者一样使用输入的 `threadId` 与 `runId`：

```ts
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. **考虑性能** —— 注意事件流的处理开销

## 高级用例

### 条件中间件

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

```ts
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 中间件参考](https://docs.ag-ui.com/sdk/js/client/middleware)。

## 结论

中间件提供了一种灵活而强大的方式，在不修改智能体核心逻辑的前提下扩展 AG-UI 智能体。无论你需要简单的事件转换还是复杂的有状态处理，中间件系统都能帮助你构建健壮、可维护的智能体应用。

Source: https://ag-ui.ndjp.net/concepts/middleware/index.mdx
