メインコンテンツへ移動

handleChatStream()

AI SDK 互換形式で Agent のチャットをストリーミングする、フレームワークに依存しないハンドラーです。Hono または Mastra 独自の apiRoutes 機能の外部でチャットストリーミングを処理する必要がある場合は、この関数を直接使用します。

handleChatStream() は、createUIMessageStreamResponse() でラップできる ReadableStream を返します。

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

Mastra サーバー内にチャットルートを作成する場合は、chatRoute() を使用してください。

UI ストリームでの構造化出力
UI ストリームでの構造化出力への直接リンク

基盤となる Agent の実行に structuredOutput を渡すと、最終的な構造化出力オブジェクトがカスタムデータパートとして AI SDK 互換 UI ストリームに出力されます。

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

object フィールドには、構造化出力の完全な値が含まれます。Mastra がこのイベントを出力するのは、最終的な構造化出力オブジェクトに対してのみです。構造化出力の部分的なチャンクは UI ストリームに公開されません。

このイベントは、onData などの AI SDK UI のカスタムデータ処理で読み取るか、メッセージのデータパートからレンダリングします。

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

Next.js App Router の例:

app/api/chat/route.ts
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'
= 'v5'
出力する AI SDK ストリームコントラクトを選択します。既存のデフォルト動作を使用するには、省略するか 'v5' を渡します。アプリが AI SDK v6 のレスポンスヘルパーの型を使用している場合は、'v6' を渡します。

mastra:

Mastra
登録済みの Agent を含む Mastra インスタンス。

agentId:

string
チャットに使用する Agent の ID。

agentVersion?:

{ versionId: string } | { status?: 'draft' | 'published' }
特定の Agent バージョンを選択します。厳密なバージョンを指定するには { versionId: '<id>' } を、ステータスによって解決するには { status: 'draft' } または { status: 'published' } を渡します。Editor の設定が必要です。

params:

ChatStreamHandlerParams
メッセージと任意の再開データを含む、チャットストリームのパラメーター。

params.messages:

UIMessage[]
会話内のメッセージの配列。

params.resumeData?:

Record<string, any>
中断された Agent の実行を再開するためのデータ。runId の設定が必要です。

params.runId?:

string
実行 ID。resumeData を指定する場合は必須です。

params.providerOptions?:

Record<string, Record<string, unknown>>
言語モデルに渡す Provider 固有のオプション（例: { openai: { reasoningEffort: "high" } }）。defaultOptions.providerOptions とマージされ、params が優先されます。

params.requestContext?:

RequestContext
Agent の実行に渡すリクエストコンテキスト。

defaultOptions?:

AgentExecutionOptions
Agent の実行に渡すデフォルトオプション。params とマージされ、params が優先されます。

sendStart?:

boolean
= true
ストリームで開始イベントを送信するかどうか。

sendFinish?:

boolean
= true
ストリームで終了イベントを送信するかどうか。

sendReasoning?:

boolean
= false
ストリームに推論ステップを含めるかどうか。

sendSources?:

boolean
= false
ストリームに出典の引用を含めるかどうか。

onError?:

(error: unknown) => string
ストリームでエラーが発生したときに呼び出されます。エラーメッセージとしてクライアントに送信する文字列を返します。エンドユーザーに届く前にエラーをサニタイズするために使用します。たとえば、内部インフラストラクチャの詳細が漏洩するのを防げます。

messageMetadata?:

(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined
現在のストリームパートを受け取り、開始チャンクと終了チャンクに付加するメタデータを返す関数。詳細は AI SDK のメッセージメタデータに関するドキュメントを参照してください。
On this page