跳至主要內容

chatRoute()

建立聊天路由處理器，以 AI SDK 格式串流 Agent 對話。此函數會註冊 HTTP POST 端點；端點會接收訊息、執行 Agent，並以 AI SDK 相容格式將回應串流傳回 client。你必須在自訂 API 路由內使用此函數。

如需與框架無關的處理器，請使用 handleChatStream()。

chatRoute() 會保留現有的 AI SDK v5／預設行為。如果你的應用程式是按 AI SDK v6 定型，請傳入 version: 'v6'。

中斷連線時的行為

chatRoute() 會將連入請求的 AbortSignal 轉送至 agent.stream()。如果 client 中斷連線，Mastra 會中止正在進行的生成作業。

如果你希望伺服器在中斷連線後繼續生成並持久保存最終回應，請圍繞 agent.stream() 建立自訂 API 路由，並對傳回的 MastraModelOutput 呼叫 consumeStream()。

使用範例
使用範例 的直接連結

以下範例說明如何在 /chat 端點設定聊天路由，並使用 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 串流規範。如要使用現有的預設行為，請省略此項或傳入 'v5'。如果你的應用程式是按 AI SDK v6 回應輔助函數定型，請傳入 'v6'。

path:

string
= '/chat/:agentId'
路由路徑（例如 /chat 或 /chat/:agentId）。如需動態 Agent 路由，請加入 :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 執行程序的預設選項。這些選項可包括指示、記憶體設定、maxSteps 及其他執行設定。

sendStart?:

boolean
= true
是否在串流中傳送開始事件。

sendFinish?:

boolean
= true
是否在串流中傳送完成事件。

sendReasoning?:

boolean
= false
是否在串流中包括推理步驟。

sendSources?:

boolean
= false
是否在串流中包括來源引文。

heartbeatMs?:

number
SSE 心跳的間隔（毫秒），讓連線通過設有閒置逾時的基礎架構時仍保持連接。

其他設定
其他設定 的直接連結

你可使用 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',
          },
        },
      }
    },
  }),
})
On this page