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

# chatRoute()

创建使用 AI SDK 格式流式传输 Agent 对话的聊天路由处理程序。此函数会注册一个 HTTP `POST` endpoint，用于接收消息、执行 Agent，并以 AI SDK 兼容格式将响应流式传回客户端。必须在[自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)中使用它。

如果需要与框架无关的处理程序，请使用 [`handleChatStream()`](https://mastra.zisheng.pro/reference/ai-sdk/handle-chat-stream)。

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

> **断开连接行为:** `chatRoute()` 会将传入请求的 `AbortSignal` 转发给 `agent.stream()`。如果客户端断开连接，Mastra 会中止正在进行的生成。
>
> 如果希望服务器在断开连接后继续生成并持久化最终响应，请围绕 `agent.stream()` 构建[自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)，并对返回的 `MastraModelOutput` 调用 `consumeStream()`。

## 使用示例

此示例展示如何在 `/chat` endpoint 设置聊天路由，并使用 ID 为 `weatherAgent` 的 Agent。

```typescript
import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat',
        agent: 'weatherAgent',
      }),
    ],
  },
})
```

也可以根据 `agentId` 使用运行时定义的 Agent 路由。URL `/chat/weatherAgent` 将解析为 ID 为 `weatherAgent` 的 Agent。

```typescript
import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat/:agentId',
      }),
    ],
  },
})
```

## 参数

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

**path** (`string`): 路由路径（例如 /chat 或 /chat/:agentId）。包含 :agentId 可启用动态 Agent 路由。 (Default: `'/chat/:agentId'`)

**agent** (`string`): 此聊天路由所用 Agent 的 ID。如果路径不包含 :agentId，则此项为必填。

**agentVersion** (`{ versionId: string } | { status?: 'draft' | 'published' }`): 选择特定的 Agent 版本。传入 { versionId: '\<id>' } 可指定确切版本，或传入 { status: 'draft' } / { status: 'published' } 按状态解析。调用路由时，查询参数 ?versionId=\<id> 或 ?status=draft|published 的优先级高于此静态值。需要配置 Editor。

**defaultOptions** (`AgentExecutionOptions`): 传递给 Agent 执行的默认选项。其中可包含 instructions、memory 配置、maxSteps 和其他执行设置。

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

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

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

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

**heartbeatMs** (`number`): SSE heartbeat 的间隔（以毫秒为单位），用于在存在空闲超时的基础设施中保持连接活跃。

## 其他配置

可以使用 [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) 自定义发送到聊天路由的请求，例如向 Agent 传递其他配置：

```typescript
const { error, status, sendMessage, messages, regenerate, stop } = useChat({
  transport: new DefaultChatTransport({
    api: 'http://localhost:4111/chat',
    prepareSendMessagesRequest({ messages }) {
      return {
        body: {
          messages,
          // Pass memory config
          memory: {
            thread: 'user-1',
            resource: 'user-1',
          },
        },
      }
    },
  }),
})
```