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

# handleChatStream()

AI SDK 互換形式で Agent のチャットをストリーミングする、フレームワークに依存しないハンドラーです。Hono または Mastra 独自の [apiRoutes](https://mastra.zisheng.pro/ja/docs/server/custom-api-routes) 機能の外部でチャットストリーミングを処理する必要がある場合は、この関数を直接使用します。

`handleChatStream()` は、[`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) でラップできる `ReadableStream` を返します。

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

Mastra サーバー内にチャットルートを作成する場合は、[`chatRoute()`](https://mastra.zisheng.pro/ja/reference/ai-sdk/chat-route) を使用してください。

## UI ストリームでの構造化出力

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

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

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

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

## 使用例

Next.js App Router の例:

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

**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`): ストリームで開始イベントを送信するかどうか。 (Default: `true`)

**sendFinish** (`boolean`): ストリームで終了イベントを送信するかどうか。 (Default: `true`)

**sendReasoning** (`boolean`): ストリームに推論ステップを含めるかどうか。 (Default: `false`)

**sendSources** (`boolean`): ストリームに出典の引用を含めるかどうか。 (Default: `false`)

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

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