chatRoute()

创建使用 AI SDK 格式流式传输 Agent 对话的聊天路由处理程序。此函数会注册一个 HTTP POST endpoint，用于接收消息、执行 Agent，并以 AI SDK 兼容格式将响应流式传回客户端。必须在自定义 API 路由中使用它。

如果需要与框架无关的处理程序，请使用 handleChatStream()。

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

断开连接行为

chatRoute() 会将传入请求的 AbortSignal 转发给 agent.stream()。如果客户端断开连接，Mastra 会中止正在进行的生成。

如果希望服务器在断开连接后继续生成并持久化最终响应，请围绕 agent.stream() 构建自定义 API 路由，并对返回的 MastraModelOutput 调用 consumeStream()。

使用示例

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

src/mastra/index.ts

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。

src/mastra/index.ts

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'

= 'v5'

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

path:

string

= '/chat/:agentId'

路由路径（例如 /chat 或 /chat/:agentId）。包含 :agentId 可启用动态 Agent 路由。

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

= true

是否在 stream 中发送开始事件。

sendFinish?:

boolean

= true

是否在 stream 中发送结束事件。

sendReasoning?:

boolean

= false

是否在 stream 中包含推理步骤。

sendSources?:

boolean

= false

是否在 stream 中包含来源引用。

heartbeatMs?:

number

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

其他配置

可以使用 prepareSendMessagesRequest 自定义发送到聊天路由的请求，例如向 Agent 传递其他配置：

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',
          },
        },
      }
    },
  }),
})