> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# handleChatStream()

与框架无关的处理程序，用于以 AI SDK 兼容格式流式传输 Agent 聊天。当需要在 Hono 或 Mastra 自有的 [apiRoutes](https://mastra.zisheng.pro/docs/server/custom-api-routes) 功能之外处理聊天 stream 时，请直接使用此函数。

`handleChatStream()` 返回一个 `ReadableStream`，可使用 [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) 对其进行封装。

`handleChatStream()` 保留现有的 AI SDK v5 默认行为。如果应用使用 AI SDK v6 类型，请传入 `version: 'v6'`。

如果要在 Mastra server 中创建聊天路由，请使用 [`chatRoute()`](https://mastra.zisheng.pro/reference/ai-sdk/chat-route)。

## UI stream 中的结构化输出

将 `structuredOutput` 传递给底层 Agent 执行时，最终的结构化输出对象会作为自定义 data part 发送到 AI SDK 兼容的 UI stream 中：

```json
{
  "type": "data-structured-output",
  "data": {
    "object": {}
  }
}
```

`object` 字段包含完整的结构化输出值。Mastra 仅为最终结构化输出对象发送此事件；UI stream 不会公开部分结构化输出 chunk。

可通过 AI SDK UI 的自定义数据处理机制（如 `onData`）读取此事件，或从消息 data part 渲染它。

## 使用示例

Next.js App Router 示例：

```typescript
import { handleChatStream } from '@mastra/ai-sdk'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/src/mastra'

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weatherAgent',
    params,
    messageMetadata: () => ({ createdAt: new Date().toISOString() }),
  })
  return createUIMessageStreamResponse({ stream })
}
```

## 参数

**version** (`'v5' | 'v6'`): 选择要输出的 AI SDK stream 协议。省略此项或传入 'v5' 可使用现有默认行为；当应用使用 AI SDK v6 response helper 的类型时，传入 'v6'。 (Default: `'v5'`)

**mastra** (`Mastra`): 包含已注册 Agent 的 Mastra 实例。

**agentId** (`string`): 用于聊天的 Agent ID。

**agentVersion** (`{ versionId: string } | { status?: 'draft' | 'published' }`): 选择特定的 Agent 版本。传入 { versionId: '\<id>' } 可指定确切版本，或传入 { status: 'draft' } / { status: 'published' } 按状态解析。需要配置 Editor。

**params** (`ChatStreamHandlerParams`): 聊天 stream 的参数，包括消息和可选的恢复数据。

**params.messages** (`UIMessage[]`): 对话中的消息数组。

**params.resumeData** (`Record<string, any>`): 用于恢复已暂停 Agent 执行的数据。必须设置 runId。

**params.runId** (`string`): run ID。提供 resumeData 时为必填。

**params.providerOptions** (`Record<string, Record<string, unknown>>`): 传递给语言模型的 Provider 专用选项（例如 { openai: { reasoningEffort: "high" } }）。它会与 defaultOptions.providerOptions 合并，且 params 优先。

**params.requestContext** (`RequestContext`): 传递给 Agent 执行的 request context。

**defaultOptions** (`AgentExecutionOptions`): 传递给 Agent 执行的默认选项。这些选项会与 params 合并，且 params 优先。

**sendStart** (`boolean`): 是否在 stream 中发送开始事件。 (Default: `true`)

**sendFinish** (`boolean`): 是否在 stream 中发送结束事件。 (Default: `true`)

**sendReasoning** (`boolean`): 是否在 stream 中包含推理步骤。 (Default: `false`)

**sendSources** (`boolean`): 是否在 stream 中包含来源引用。 (Default: `false`)

**onError** (`(error: unknown) => string`): stream 遇到错误时调用。返回的字符串将作为错误消息发送给客户端。可用它在错误到达客户端前进行清理，例如防止内部基础设施详情泄露给最终用户。

**messageMetadata** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): 接收当前 stream part 并返回 metadata 的函数，返回值将附加到开始和结束 chunk。详情请参阅 AI SDK 消息 metadata 文档。