ai-sdk-7

AI SDK 7 の実装と移行

このスキルは ai@7 に適用してください。不明なバージョンの確認には ai-sdk を、v6 のメンテナンスには ai-sdk-6 を使用してください。 プロバイダーと UI パッケージのバージョンは、プロジェクトに合わせてください。 AI SDK 7 には Node.js 22 以降が必要で、AI SDK パッケージは ESM 専用です。

まず、解決済みの ai/docs/、プロバイダーのドキュメント、インストール済みのソース／型を確認してください。 このスキル内の各 ai-sdk.dev/docs/... リンクには、ai/docs/ にオフラインコピーがあります （パスの対応付けは ai-sdk にあります）。Harness、WorkflowAgent、移行ガイドは ai/docs/03-ai-sdk-harnesses/、03-agents/07-workflow-agent.mdx、 08-migration-guides/23-migration-guide-7-0.mdx にあります。コンパニオンパッケージに含まれるのは型のみです。 ローカルドキュメントを利用できない場合は、公式ドキュメント または対応する リポジトリのタグを参照してください。実験的なパッケージ API を長期利用するラッパーに追加する前に、必ず最新の情報を確認してください。

必要なもの	エントリーポイント
メモリ内エージェントループ	ai の ToolLoopAgent
永続化可能なエージェント	@ai-sdk/workflow の WorkflowAgent ＋ workflow 5
Claude Code/Codex/Pi ランタイム	@ai-sdk/harness/agent の HarnessAgent ＋アダプター＋サンドボックスパッケージ
OpenTelemetry	registerTelemetry(new OpenTelemetry())、@ai-sdk/otel
停滞した呼び出し	timeout：ミリ秒、または { totalMs, stepMs, firstChunkMs, chunkMs, toolMs }

重要な境界

• テキスト関数と ToolLoopAgent では instructions を使用し、ループの上限には isStepCount を使用します。Core、agent、server の UI ストリームヘルパーでは onEnd／onStepEnd を使用します（onFinish は引き続き非推奨のエイリアスです）。クライアントの useChat／Chat では onFinish を引き続き使用します。
• prepareStep による指示／メッセージのオーバーライドは、後続のステップにも引き継がれます。 usage やツール配列などの結果は全ステップを集計します。finalStep を使うと最終ステップにアクセスでき、 ストリームではこれを await します。
• サーバーのループ状態には runtimeContext を、ツールごとの状態にはスキーマ検証済みの toolsContext を使用します。どちらも、コンテキストであるだけではモデルから参照できません。
• 承認、永続化、ライフサイクルは ToolLoopAgent、 WorkflowAgent、HarnessAgent、プロバイダー実行のツールで異なります。実際に必要な永続性／権限に応じてランタイムを選択してください。
• モデル ID と機能は、設定済みのプロバイダーから解決してください。推論設定が重複しないようにしてください。プロバイダーオプションがトップレベルの reasoning を上書きすることがあります。

基本構成

[email protected]、@ai-sdk/[email protected]、[email protected]、React 19、 TypeScript 5.9 で確認済みです。tsc --noEmit を実行し、モックモデルでツールのステップを 1 回実行した後、 続けて回答を生成しました。文字列モデルは AI Gateway を通じて解決されます。

// app/api/chat/route.ts
import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, streamText, tool,
  toUIMessageStream, validateUIMessages, type InferUITools, type UIDataTypes, type UIMessage } from 'ai';
import { z } from 'zod';

const tools = {
  weather: tool({
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => ({ city, celsius: 21 }),
  }),
};
export type ChatMessage = UIMessage<never, UIDataTypes, InferUITools<typeof tools>>;

export async function POST(req: Request) {
  const { messages } = await req.json();
  const uiMessages = await validateUIMessages<ChatMessage>({ messages, tools });
  const result = streamText({
    model: 'provider/model-id', // configured gateway ID, or a provider instance
    instructions: 'Answer briefly.',
    messages: await convertToModelMessages(uiMessages),
    tools,
    stopWhen: isStepCount(5),
  });
  return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) });
}

// app/page.tsx
'use client';
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';
import type { ChatMessage } from './api/chat/route';

const transport = new DefaultChatTransport<ChatMessage>({ api: '/api/chat' });

export default function Chat() {
  const { messages, sendMessage, status } = useChat<ChatMessage>({ transport });
  return (
    <form action={(form) => void sendMessage({ text: String(form.get('text')) })}>
      {messages.map((m) => <div key={m.id}>{m.parts.map((part, i) =>
        part.type === 'text' ? <p key={i}>{part.text}</p>
        : part.type === 'tool-weather' && part.state === 'output-available'
          ? <p key={i}>{part.output.city}: {part.output.celsius} °C</p> : null)}</div>)}
      <input name="text" disabled={status === 'submitted' || status === 'streaming'} />
    </form>
  );
}

v6 の表記（system、stepCountIs、result.toUIMessageStreamResponse()）は、7.0.124 でも引き続きコンパイルできますが、system とレスポンスメソッドは非推奨です。

機能に応じた参照先

• エージェント：メモリ内／永続化可能な実行とコンテキスト。
• Harness：ランタイムが管理するセッションと権限。
• Core 関数：出力、ストリーム、結果の契約。
• ツール：承認の境界、MCP Apps、サンドボックスハンドル。
• UI フック：UI ストリーム、承認、再開。
• 移行：意味上の変更とコードモッド。
• テレメトリー：登録とデータ制御。
• メディア／ファイル：プロバイダーの参照情報と機能のゲート。
• 例：現在の公式実装。

型チェックを行い、変更したマルチターン、ツール、ストリーム、または再開の経路を実際に試してください。 コンパイルに成功しても、承認ポリシーや永続化の動作が正しいとは限りません。