ai-sdk-ui

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

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

バージョン: AI SDK v5.0.116（安定版） フレームワーク: React 18 以降、Next.js 15 以降 最終更新日: 2025-12-22

目次

1. クイックスタート
2. リファレンスを読み込むタイミング
3. useChat フック
4. useCompletion フック
5. useObject フック
6. Next.js との統合
7. よくある UI エラーと解決策
8. ストリーミングのベストプラクティス
9. このスキルを使用する場面
10. パッケージバージョン

---

クイックスタート（5 分）

インストール

bun add ai @ai-sdk/openai  # preferred
# or: bun add ai @ai-sdk/openai

基本的なチャットコンポーネント（v5）

// app/chat/page.tsx
'use client';
import { useChat } from 'ai/react';
import { useState, FormEvent } from 'react';

export default function Chat() {
  const { messages, sendMessage, isLoading } = useChat({
    api: '/api/chat',
  });
  const [input, setInput] = useState('');

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

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

API ルート（Next.js App Router）

// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai('gpt-4-turbo'),
    messages,
  });

  return result.toDataStreamResponse();
}

結果: フロントエンドコード約 10 行で、AI の応答をストリーミング表示する機能的なチャットインターフェースを作成できます。

---

リファレンスを読み込むタイミング

詳細な実装ガイド、API リファレンス、高度なパターンについては、以下のリファレンスファイルを読み込んでください。

リファレンスファイル	読み込む場面
references/use-chat-migration.md	v4 から v5 への移行、破壊的変更の理解
references/streaming-patterns.md	UI ストリーミングのベストプラクティス、パフォーマンス最適化
references/top-ui-errors.md	よくある UI エラーのデバッグ、エラーの予防
references/nextjs-integration.md	Next.js のセットアップパターン、App Router と Pages Router の違い
references/links-to-official-docs.md	Vercel AI SDK の公式ドキュメントを探す
references/tool-calling-ui.md	チャット UI でのツール／関数呼び出しの実装
references/file-attachments-guide.md	チャットへのファイルのアップロード／添付機能の追加
references/message-persistence.md	localStorage を使用したチャット履歴の永続化
references/use-completion-full-reference.md	useCompletion API の完全なリファレンスと例
references/use-object-full-reference.md	Zod スキーマを使用した useObject API の完全なリファレンス
references/nextjs-app-router-full.md	Next.js App Router の完全な実装
references/nextjs-pages-router-full.md	Next.js Pages Router の完全な実装

---

useChat フック - 完全なリファレンス

基本的な使い方（v5 パターン）

'use client';
import { useChat } from 'ai/react';
import { useState, FormEvent } from 'react';

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

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    if (!input.trim()) return;

    sendMessage({ content: input });
    setInput('');
  };

  return (
    <div className="flex flex-col h-screen">
      {/* Messages */}
      <div className="flex-1 overflow-y-auto p-4">
        {messages.map(message => (
          <div
            key={message.id}
            className={message.role === 'user' ? 'text-right' : 'text-left'}
          >
            <div className="inline-block p-2 rounded bg-gray-100">
              {message.content}
            </div>
          </div>
        ))}
        {isLoading && <div className="text-gray-500">AI is thinking...</div>}
      </div>

      {/* Input */}
      <form onSubmit={handleSubmit} className="p-4 border-t">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
          disabled={isLoading}
          className="w-full p-2 border rounded"
        />
      </form>

      {/* Error */}
      {error && <div className="text-red-500 p-4">{error.message}</div>}
    </div>
  );
}

API リファレンス全文

const {
  // Messages
  messages,           // Message[] - Chat history
  setMessages,        // (messages: Message[]) => void - Update messages

  // Actions
  sendMessage,        // (message: { content: string }) => void - Send message (v5)
  reload,             // () => void - Reload last response
  stop,               // () => void - Stop current generation

  // State
  isLoading,          // boolean - Is AI responding?
  error,              // Error | undefined - Error if any

  // Data
  data,               // any[] - Custom data from stream
  metadata,           // object - Response metadata
} = useChat({
  // Required
  api: '/api/chat',   // API endpoint

  // Optional
  id: 'chat-1',       // Chat ID for persistence
  initialMessages: [], // Initial messages (controlled mode)

  // Callbacks
  onFinish: (message, options) => {},  // Called when response completes
  onError: (error) => {},              // Called on error

  // Configuration
  headers: {},        // Custom headers
  body: {},           // Additional body data
  credentials: 'same-origin', // Fetch credentials

  // Streaming
  streamProtocol: 'data', // 'data' | 'text' (default: 'data')
});

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 を参照してください。

高度な機能: useChat は、ツール呼び出し（message.toolInvocations を表示）、ファイル添付（experimental_attachments）、メッセージの永続化（id + initialMessages を使用した localStorage）に対応しています。実装例については、公式ドキュメントを参照してください。

---

useCompletion および useObject フック

useCompletion: 単一プロンプトの補完向け（複数ターンのチャットには使用しません）。{ completion, complete, isLoading } を返します。生成するには complete(prompt) を呼び出します。API ルートでは streamText() を使用します。

useObject: Zod スキーマを使用して、構造化 JSON をライブ更新付きでストリーミングします。object は段階的に更新される Partial<T> で、{ object, submit, isLoading } を返します。API ルートでは streamObject() を使用します。

API リファレンスと例の全文については、公式ドキュメントを参照してください。

---

Next.js 統合

App Router と Pages Router の両方について、完全なチャット UI コンポーネント、API ルート、適切なストリーミング設定を含む、動作するサンプルを紹介します。

📖 完全な実装コードについては、references/nextjs-integration.md を読み込んでください。内容は以下のとおりです。

• App Router：自動スクロール、読み込み状態、エラー処理、API ルートを含む完全なチャットページ
• Pages Router：適切なストリーミング設定を含む、完全なチャット実装
• 主な違い：toDataStreamResponse() と pipeDataStreamToResponse()

---

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 オプションは初回レンダー時のみ取得されます。

解決方法：

// ❌ 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 アプリケーションには、両方を組み合わせてください

---

パッケージのバージョン

必須：

{
  "dependencies": {
    "ai": "^5.0.116",
    "@ai-sdk/openai": "^2.0.88",
    "react": "^18.2.0",
    "zod": "^3.23.8",
    "isomorphic-dompurify": "^2.16.0"
  }
}

Next.js：

{
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

バージョンに関する注意事項：

• AI SDK v5.0.116+（安定版）
• 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-10-22