ai-sdk-ui

AI SDK UI - フロントエンド React フック

Vercel AI SDK v5/v6 を使用した、AI 搭載ユーザーインターフェース向けのフロントエンド React フックです。

バージョン: AI SDK v5.0.99（安定版） / v6.0.0-beta.108（ベータ版） フレームワーク: React 18+, Next.js 14+ 最終更新日: 2025-11-22

---

AI SDK 6 ベータ版（2025年11月）

ステータス: ベータ版（安定版リリースは2025年末を予定） 最新: [email protected]（2025年11月22日） 移行: v5 から v6 への破壊的変更は最小限です

v6 ベータ版の新しい UI 機能

1. エージェントとの連携 InferAgentUIMessage<typeof agent> を使用した、エージェントとの型安全なメッセージングです。

import { useChat } from '@ai-sdk/react';
import type { InferAgentUIMessage } from 'ai';
import { myAgent } from './agent';

export default function AgentChat() {
  const { messages, sendMessage } = useChat<InferAgentUIMessage<typeof myAgent>>({
    api: '/api/chat',
  });
  // messages are now type-checked against agent schema
}

2. ツールの承認ワークフロー（Human-in-the-Loop） ツールを実行する前に、ユーザーに確認を求めます。

import { useChat } from '@ai-sdk/react';
import { useState } from 'react';

export default function ChatWithApproval() {
  const { messages, sendMessage, addToolApprovalResponse } = useChat({
    api: '/api/chat',
  });

  const handleApprove = (toolCallId: string) => {
    addToolApprovalResponse({
      toolCallId,
      approved: true,  // or false to deny
    });
  };

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.toolInvocations?.map(tool => (
            tool.state === 'awaiting-approval' && (
              <div key={tool.toolCallId}>
                <p>Approve tool call: {tool.toolName}?</p>
                <button onClick={() => handleApprove(tool.toolCallId)}>
                  Approve
                </button>
                <button onClick={() => addToolApprovalResponse({
                  toolCallId: tool.toolCallId,
                  approved: false
                })}>
                  Deny
                </button>
              </div>
            )
          ))}
        </div>
      ))}
    </div>
  );
}

3. 自動送信機能 承認を処理した後、会話を自動的に続行します。

import { useChat, lastAssistantMessageIsCompleteWithApprovalResponses } from '@ai-sdk/react';

export default function AutoSubmitChat() {
  const { messages, sendMessage } = useChat({
    api: '/api/chat',
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
    // Automatically resubmit after all approval responses provided
  });
}

4. チャットでの構造化出力 ツール呼び出しとともに構造化データを生成します（以前は useObject でのみ利用可能でした）。

import { useChat } from '@ai-sdk/react';
import { z } from 'zod';

const schema = z.object({
  summary: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
});

export default function StructuredChat() {
  const { messages, sendMessage } = useChat({
    api: '/api/chat',
    // Server can now stream structured output with chat messages
  });
}

---

useChat フック - v4 → v5 の破壊的変更

重要：v5 の useChat は入力状態を管理しなくなりました！

v4（旧版 - 使用しないでください）：

const { messages, input, handleInputChange, handleSubmit, append } = useChat();

<form onSubmit={handleSubmit}>
  <input value={input} onChange={handleInputChange} />
</form>

v5（新版 - 正しい方法）：

const { messages, sendMessage } = useChat();
const [input, setInput] = useState('');

<form onSubmit={(e) => {
  e.preventDefault();
  sendMessage({ content: input });
  setInput('');
}}>
  <input value={input} onChange={(e) => setInput(e.target.value)} />
</form>

v5 の変更点のまとめ：

1. 入力管理を削除: input、handleInputChange、handleSubmit は存在しなくなりました
2. append() → sendMessage(): メッセージ送信用の新しいメソッドです
3. onResponse を削除: 代わりに onFinish を使用してください
4. initialMessages → 制御モード: 完全に制御するには messages プロパティを使用してください
5. maxSteps を削除: サーバー側でのみ処理してください

移行ガイドの全容は references/use-chat-migration.md を参照してください。

---

useAssistant フック

OpenAI 互換のアシスタント API を、UI 状態を自動管理しながら利用できます。

インポート：

import { useAssistant } from '@ai-sdk/react';

基本的な使い方：

'use client';
import { useAssistant } from '@ai-sdk/react';
import { useState, FormEvent } from 'react';

export default function AssistantChat() {
  const { messages, sendMessage, isLoading, error } = useAssistant({
    api: '/api/assistant',
  });
  const [input, setInput] = useState('');

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    sendMessage({ content: input });
    setInput('');
  };

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          disabled={isLoading}
        />
      </form>
      {error && <div>{error.message}</div>}
    </div>
  );
}

ユースケース：

• OpenAI Assistant を活用した UI の構築
• アシスタントのスレッドと実行の管理
• UI 状態を管理しながらアシスタントの応答をストリーミング
• ファイル検索とコードインタープリターの連携

API リファレンスの全容については、公式ドキュメントを参照してください：https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-assistant

---

UI でよくあるエラーと解決策

詳細については references/top-ui-errors.md を参照してください。クイックリファレンス：

1. useChat でストリームを解析できない

エラー: SyntaxError: Unexpected token in JSON at position X

原因: API ルートが適切なストリーム形式を返していません。

解決策：

// ✅ CORRECT
return result.toDataStreamResponse();

// ❌ WRONG
return new Response(result.textStream);

2. useChat が応答しない

原因: API ルートが正しくストリーミングしていません。

解決策：

// App Router - use toDataStreamResponse()
export async function POST(req: Request) {
  const result = streamText({ /* ... */ });
  return result.toDataStreamResponse(); // ✅
}

// Pages Router - use pipeDataStreamToResponse()
export default async function handler(req, res) {
  const result = streamText({ /* ... */ });
  return result.pipeDataStreamToResponse(res); // ✅
}

3. デプロイ後にストリーミングが動作しない

原因: デプロイプラットフォームが応答をバッファリングしています。

解決策: Vercel はストリーミングを自動検出します。他のプラットフォームでは設定が必要な場合があります。

4. useChat で body の値が古い

原因: body オプションは最初のレンダリング時にのみ取得されます。

解決策：

// ❌ WRONG - body captured once
const { userId } = useUser();
const { messages } = useChat({
  body: { userId },  // Stale!
});

// ✅ CORRECT - use controlled mode
const { userId } = useUser();
const { messages, sendMessage } = useChat();

sendMessage({
  content: input,
  data: { userId },  // Fresh on each send
});

5. React の最大更新深度エラー

原因: useEffect 内で無限ループが発生しています。

解決策：

// ❌ WRONG
useEffect(() => {
  saveMessages(messages);
}, [messages, saveMessages]); // saveMessages triggers re-render!

// ✅ CORRECT
useEffect(() => {
  saveMessages(messages);
}, [messages]); // Only depend on messages

その他のよくあるエラー7件については references/top-ui-errors.md を参照してください。

---

ストリーミングのベストプラクティス

パフォーマンス

UX 向上のため、常にストリーミングを使用してください：

// ✅ GOOD - Streaming (shows tokens as they arrive)
const { messages } = useChat({ api: '/api/chat' });

// ❌ BAD - Non-streaming (user waits for full response)
const response = await fetch('/api/chat', { method: 'POST' });

UX パターン

読み込み状態を表示する：

{isLoading && <div>AI is typing...</div>}

停止ボタンを用意する：

{isLoading && <button onClick={stop}>Stop</button>}

最新のメッセージまで自動スクロールする：

useEffect(() => {
  messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
}, [messages]);

読み込み中は入力を無効にする：

<input disabled={isLoading} />

ベストプラクティスの詳細については references/streaming-patterns.md を参照してください。

---

このスキルを使用する場面

次のような場合は ai-sdk-ui を使用してください：

• React のチャットインターフェースを構築する
• UI に AI 補完機能を実装する
• AI の応答をフロントエンドにストリーミングする
• Next.js の AI アプリケーションを構築する
• チャットメッセージの状態を処理する
• UI にツール呼び出しを表示する
• AI でファイル添付を管理する
• v4 から v5 に移行する（UI フック）
• useChat/useCompletion のエラーに対処する

次のような場合は使用しないでください：

• バックエンドの AI 機能が必要 → 代わりに ai-sdk-core を使用してください
• React 以外のフロントエンド（Svelte、Vue）を構築する → 公式ドキュメントを確認してください
• Generative UI / RSC が必要 → https://ai-sdk.dev/docs/ai-sdk-rsc を参照してください
• ネイティブアプリを構築する → 別の SDK が必要です

関連スキル：

• ai-sdk-core - バックエンドのテキスト生成、構造化出力、ツール、エージェント
• 両方を組み合わせて、フルスタックの AI アプリケーションを構築します

---

パッケージのバージョン

安定版（v5）：

{
  "dependencies": {
    "ai": "^5.0.99",
    "@ai-sdk/react": "^1.0.0",
    "@ai-sdk/openai": "^2.0.68",
    "react": "^18.2.0",
    "zod": "^3.23.8"
  }
}

ベータ版（v6）：

{
  "dependencies": {
    "ai": "6.0.0-beta.108",
    "@ai-sdk/react": "beta",
    "@ai-sdk/openai": "beta"
  }
}

バージョンに関する注記：

• AI SDK v5.0.99（安定版、2025年11月）
• AI SDK v6.0.0-beta.108（ベータ版、2025年11月22日）- 破壊的変更は最小限です
• React 18 以降（React 19 に対応）
• Next.js 14 以降を推奨（13.4 以降でも動作します）
• スキーマ検証には Zod 3.23.8 以降が必要です

---

公式ドキュメントへのリンク

コア UI フック：

• AI SDK UI の概要：https://ai-sdk.dev/docs/ai-sdk-ui/overview
• useChat：https://ai-sdk.dev/docs/ai-sdk-ui/chatbot
• useCompletion：https://ai-sdk.dev/docs/ai-sdk-ui/completion
• useObject：https://ai-sdk.dev/docs/ai-sdk-ui/object-generation

高度なトピック（リンクのみ）：

• Generative UI（RSC）：https://ai-sdk.dev/docs/ai-sdk-rsc/overview
• ストリームプロトコル：https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocols
• メッセージのメタデータ：https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata

Next.js との統合：

• Next.js App Router：https://ai-sdk.dev/docs/getting-started/nextjs-app-router
• Next.js Pages Router：https://ai-sdk.dev/docs/getting-started/nextjs-pages-router

移行とトラブルシューティング：

• v4→v5 の移行：https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
• トラブルシューティング：https://ai-sdk.dev/docs/troubleshooting
• よくある問題：https://ai-sdk.dev/docs/troubleshooting/common-issues

Vercel へのデプロイ：

• Vercel Functions：https://vercel.com/docs/functions
• Vercel でのストリーミング：https://vercel.com/docs/functions/streaming

---

テンプレート

このスキルには、templates/ に次のテンプレートが含まれています。

1. use-chat-basic.tsx - 手動入力による基本的なチャット（v5 パターン）
2. use-chat-tools.tsx - ツール呼び出しの UI レンダリングに対応したチャット
3. use-chat-attachments.tsx - ファイル添付に対応
4. use-completion-basic.tsx - 基本的なテキスト補完
5. use-object-streaming.tsx - 構造化データのストリーミング
6. nextjs-chat-app-router.tsx - Next.js App Router の完全な例
7. nextjs-chat-pages-router.tsx - Next.js Pages Router の完全な例
8. nextjs-api-route.ts - App Router と Pages Router の両方に対応する API ルート
9. message-persistence.tsx - チャット履歴の保存／読み込み
10. custom-message-renderer.tsx - Markdown に対応したカスタムメッセージコンポーネント
11. package.json - 依存関係のテンプレート

リファレンスドキュメント

references/ にある次のファイルを参照してください。

• use-chat-migration.md - v4→v5 の完全な移行ガイド
• streaming-patterns.md - UI ストリーミングのベストプラクティス
• top-ui-errors.md - よくある UI エラー 12 件と解決策
• nextjs-integration.md - Next.js のセットアップパターン
• links-to-official-docs.md - 公式ドキュメントへのリンク一覧

---

本番環境でのテスト済み：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最終更新日：2025-11-22