メインコンテンツへ移動

chatRoute()

AI SDK 形式を使用して Agent の会話をストリーミングするチャットルートハンドラーを作成します。この関数は、メッセージを受け取り、Agent を実行し、レスポンスを AI SDK 互換形式でクライアントへストリーミングする HTTP POST エンドポイントを登録します。カスタム API ルート内で使用する必要があります。

フレームワークに依存しないハンドラーが必要な場合は、handleChatStream() を使用してください。

chatRoute() は、既存の AI SDK v5／デフォルトの動作を維持します。アプリが AI SDK v6 の型を使用している場合は、version: 'v6' を渡します。

切断時の動作

chatRoute() は、受信したリクエストの AbortSignal を agent.stream() に転送します。クライアントが切断すると、Mastra は進行中の生成を中止します。

切断後もサーバーで生成を続行し、最終レスポンスを永続化するには、agent.stream() を使用するカスタム API ルートを作成し、返された MastraModelOutput に対して consumeStream() を呼び出します。

使用例
使用例への直接リンク

次の例では、ID が weatherAgent の Agent を使用するチャットルートを /chat エンドポイントに設定します。

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