ai-sdk-core

AI SDK Core

Vercel AI SDK v5 および v6 Beta を使用したバックエンド AI。

インストール：

npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod
# Beta: npm install ai@beta @ai-sdk/openai@beta

---

AI SDK 6 Beta（2025年11月）

ステータス： ベータ版（2025年末に安定版のリリースを予定） 最新： [email protected]（2025年11月22日）

新機能

1. エージェントの抽象化 ToolLoopAgent クラスを使ったエージェント構築の統一インターフェース：

• 実行フロー、ツールループ、状態管理を完全に制御できます
• 手動でのツール呼び出しのオーケストレーションを置き換えます

2. ツール実行の承認（ヒューマン・イン・ザ・ループ） ツール実行前にユーザーの確認を求めます：

• 静的承認：特定のツールについて常に確認を求めます
• 動的承認：ツールの入力に応じて条件付きで確認を求めます
• ネイティブのヒューマン・イン・ザ・ループパターン

3. 再ランキングのサポート ドキュメントの順序を並べ替えて、検索の関連性を高めます：

• 対応プロバイダー：Cohere、Amazon Bedrock、Together.ai
• RAG ワークフロー向けの専用再ランキングモデル

4. 構造化出力（安定版） 複数ステップのツール呼び出しと構造化データ生成を組み合わせます：

• 複数の出力方式：オブジェクト、配列、選択肢、テキスト形式
• v6 で安定版となり、本番環境で利用できるようになりました

5. 呼び出しオプション 実行時に動的な設定を行えます：

• 型安全なパラメーターの受け渡し
• RAG 統合、モデル選択、ツールのカスタマイズ
• プロバイダー固有の設定調整

6. 画像編集（近日公開） 画像変換ワークフローをネイティブでサポートします。

v5 からの移行

v4→v5 とは異なり、v6 の破壊的変更は最小限です：

• v3 Language Model Specification を基盤としています
• ほとんどのユーザーはコードを変更する必要がありません
• エージェントの抽象化は追加機能です（オプトイン）

ベータ版をインストール：

npm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta

公式ドキュメント： https://ai-sdk.dev/docs/announcing-ai-sdk-6-beta

---

最新の AI モデル（2025年）

OpenAI

GPT-5（2025年8月7日）：

• GPT-4o よりハルシネーションを45％削減
• 数学、コーディング、視覚認識、医療分野で最先端
• ChatGPT、API、GitHub Models、Microsoft Copilot で利用可能

GPT-5.1（2025年11月13日）：

• GPT-5 より速度と効率性が向上
• API プラットフォームで利用可能

import { openai } from '@ai-sdk/openai';
const gpt5 = openai('gpt-5');
const gpt51 = openai('gpt-5.1');

Anthropic

Claude 4 ファミリー（2025年5月～10月）：

• Opus 4（5月22日）：複雑な推論に最適。100万トークンあたり $15/$75
• Sonnet 4（5月22日）：バランスの取れた性能。100万トークンあたり $3/$15
• Opus 4.1（8月5日）：エージェントタスクと実環境でのコーディングを強化
• Sonnet 4.5（9月29日）：コーディング、エージェント、コンピューター操作で最も高性能
• Haiku 4.5（10月15日）：小型で高速、低レイテンシのモデル

import { anthropic } from '@ai-sdk/anthropic';
const sonnet45 = anthropic('claude-sonnet-4-5-20250929');  // Latest
const opus41 = anthropic('claude-opus-4-1-20250805');
const haiku45 = anthropic('claude-haiku-4-5-20251015');

Google

Gemini 2.5 ファミリー（2025年3月～9月）：

• Pro（2025年3月）：最も高い知能を備え、リリース時に LMArena で1位
• Pro Deep Think（2025年5月）：推論モードを強化
• Flash（2025年5月）：高速で費用対効果に優れています
• Flash-Lite（2025年9月）：効率性を向上

import { google } from '@ai-sdk/google';
const pro = google('gemini-2.5-pro');
const flash = google('gemini-2.5-flash');
const lite = google('gemini-2.5-flash-lite');

---

v5 のコア関数（基本）

generateText() - ツールを使ったテキスト生成 streamText() - リアルタイムストリーミング generateObject() - 構造化出力（Zod スキーマ） streamObject() - 構造化データのストリーミング

使い方については公式ドキュメントを参照してください：https://ai-sdk.dev/docs/ai-sdk-core

---

Cloudflare Workers の起動時間に関する修正

問題： AI SDK v5 と Zod を併用すると、起動に270msを超える時間がかかります（Workers の400ms制限を超過）。

解決策：

// ❌ BAD: Top-level imports cause startup overhead
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });

// ✅ GOOD: Lazy initialization inside handler
app.post('/chat', async (c) => {
  const { createWorkersAI } = await import('workers-ai-provider');
  const workersai = createWorkersAI({ binding: c.env.AI });
  // ...
});

その他：

• トップレベルの Zod スキーマを最小限にします
• 複雑なスキーマをルートハンドラーに移します
• Wrangler で起動時間を監視します

---

v5 のツール呼び出しに関する変更

破壊的変更：

• parameters → inputSchema（Zod スキーマ）
• ツールのプロパティ：args → input、result → output
• ToolExecutionError を削除（現在は tool-error コンテンツパーツを使用）
• maxSteps パラメーターを削除 → stopWhen(stepCountIs(n)) を使用

v5 の新機能：

• 動的ツール（コンテキストに応じて実行時にツールを追加）
• エージェントクラス（ツールを使った複数ステップの実行）

---

重要な v4→v5 の移行

AI SDK v5 では、多くの破壊的変更が導入されました。v4 から移行する場合は、このガイドに従ってください。

破壊的変更の概要

1. パラメーター名の変更

   • maxTokens → maxOutputTokens
   • providerMetadata → providerOptions

2. ツール定義

   • parameters → inputSchema
   • ツールのプロパティ：args → input、result → output

3. メッセージの型

   • CoreMessage → ModelMessage
   • Message → UIMessage
   • convertToCoreMessages → convertToModelMessages

4. ツールのエラー処理

   • ToolExecutionError クラスを削除
   • tool-error コンテンツパーツを使用
   • 自動再試行が可能に

5. マルチステップ実行

   • maxSteps → stopWhen
   • stepCountIs() または hasToolCall() を使用

6. メッセージ構造

   • 単純な content 文字列 → parts 配列
   • パーツ：text、file、reasoning、tool-call、tool-result

7. ストリーミングアーキテクチャ

   • 単一チャンク → start/delta/end のライフサイクル
   • 並行ストリームには一意の ID を付与

8. ツールのストリーミング

   • デフォルトで有効
   • toolCallStreaming オプションを削除

9. パッケージの再編成

   • ai/rsc → @ai-sdk/rsc
   • ai/react → @ai-sdk/react
   • LangChainAdapter → @ai-sdk/langchain

移行例

移行前（v4）：

import { generateText } from 'ai';

const result = await generateText({
  model: openai.chat('gpt-4'),
  maxTokens: 500,
  providerMetadata: { openai: { user: 'user-123' } },
  tools: {
    weather: {
      description: 'Get weather',
      parameters: z.object({ location: z.string() }),
      execute: async (args) => { /* args.location */ },
    },
  },
  maxSteps: 5,
});

移行後（v5）：

import { generateText, tool, stopWhen, stepCountIs } from 'ai';

const result = await generateText({
  model: openai('gpt-4'),
  maxOutputTokens: 500,
  providerOptions: { openai: { user: 'user-123' } },
  tools: {
    weather: tool({
      description: 'Get weather',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => { /* input.location */ },
    }),
  },
  stopWhen: stepCountIs(5),
});

移行チェックリスト

• すべての maxTokens を maxOutputTokens に更新する
• providerMetadata を providerOptions に更新する
• ツールの parameters を inputSchema に変換する
• ツールの execute 関数を更新する：args → input
• maxSteps を stopWhen(stepCountIs(n)) に置き換える
• メッセージの型を更新する：CoreMessage → ModelMessage
• ToolExecutionError の処理を削除する
• パッケージのインポートを更新する（ai/rsc → @ai-sdk/rsc）
• ストリーミングの動作をテストする（アーキテクチャが変更されています）
• TypeScript の型を更新する

自動移行

AI SDK には移行ツールが用意されています：

npx ai migrate

これにより、ほとんどの破壊的変更が自動的に更新されます。変更内容を注意深く確認してください。

公式移行ガイド： https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0

---

よくあるエラーと解決策トップ 12

1. AI_APICallError

原因： API リクエストに失敗しました（ネットワーク、認証、レート制限）。

解決策：

import { AI_APICallError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_APICallError) {
    console.error('API call failed:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Response:', error.responseBody);

    // Check common causes
    if (error.statusCode === 401) {
      // Invalid API key
    } else if (error.statusCode === 429) {
      // Rate limit - implement backoff
    } else if (error.statusCode >= 500) {
      // Provider issue - retry
    }
  }
}

予防策：

• 起動時に API キーを検証する
• 指数バックオフによる再試行ロジックを実装する
• レート制限を監視する
• ネットワークエラーを適切に処理する

---

2. AI_NoObjectGeneratedError

原因： モデルがスキーマに一致する有効なオブジェクトを生成しませんでした。

解決策：

import { AI_NoObjectGeneratedError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({ /* complex schema */ }),
    prompt: 'Generate data',
  });
} catch (error) {
  if (error instanceof AI_NoObjectGeneratedError) {
    console.error('No valid object generated');

    // Solutions:
    // 1. Simplify schema
    // 2. Add more context to prompt
    // 3. Provide examples in prompt
    // 4. Try different model (gpt-4 better than gpt-3.5 for complex objects)
  }
}

予防策：

• シンプルなスキーマから始め、段階的に複雑さを加える
• プロンプトに例を含める：「次のような人物を生成してください：{ name: 'Alice', age: 30 }」
• 複雑な構造化出力には GPT-4 を使用する
• まずサンプルデータでスキーマをテストする

---

3. Worker の起動時間制限（270ms 以上）

原因： Cloudflare Workers では、AI SDK v5 と Zod の初期化オーバーヘッドにより起動時間制限を超過します。

解決策：

// BAD: Top-level imports cause startup overhead
import { createWorkersAI } from 'workers-ai-provider';
import { complexSchema } from './schemas';

const workersai = createWorkersAI({ binding: env.AI });

// GOOD: Lazy initialization inside handler
export default {
  async fetch(request, env) {
    const { createWorkersAI } = await import('workers-ai-provider');
    const workersai = createWorkersAI({ binding: env.AI });

    // Use workersai here
  }
}

予防策：

• AI SDK のインポートをルートハンドラー内に移動する
• トップレベルの Zod スキーマを最小限にする
• Worker の起動時間を監視する（400ms 未満である必要があります）
• Wrangler の起動時間レポートを使用する

GitHub の Issue： Vercel AI SDK の Issue で「Workers startup limit」を検索してください

---

4. streamText がエラーを出さずに失敗する

原因： createDataStreamResponse によってストリームエラーが握りつぶされることがあります。

ステータス： ✅ 解決済み - [email protected] で修正済み（2025 年 2 月）

解決策（推奨）：

// Use the onError callback (added in v4.1.22)
const stream = streamText({
  model: openai('gpt-4'),
  prompt: 'Hello',
  onError({ error }) {
    console.error('Stream error:', error);
    // Custom error logging and handling
  },
});

// Stream safely
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

代替案（手動の try-catch）：

// Fallback if not using onError callback
try {
  const stream = streamText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });

  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk);
  }
} catch (error) {
  console.error('Stream error:', error);
}

予防策：

• 適切にエラーを捕捉するため、onError コールバックを使用する（推奨）
• サーバー側のエラー監視を実装する
• ストリームのエラー処理を明示的にテストする
• 本番環境では必ずサーバー側でログを記録する

GitHub の Issue： #4726（解決済み）

---

5. AI_LoadAPIKeyError

原因： API キーがないか、無効です。

解決策：

import { AI_LoadAPIKeyError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_LoadAPIKeyError) {
    console.error('API key error:', error.message);

    // Check:
    // 1. .env file exists and loaded
    // 2. Correct env variable name (OPENAI_API_KEY)
    // 3. Key format is valid (starts with sk-)
  }
}

予防策：

• アプリケーションの起動時に API キーを検証する
• 環境変数の検証（例：zod）を使用する
• 開発時にわかりやすいエラーメッセージを表示する
• 必要な環境変数をドキュメントに記載する

---

6. AI_InvalidArgumentError

原因： 関数に無効なパラメーターが渡されました。

解決策：

import { AI_InvalidArgumentError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    maxOutputTokens: -1,  // Invalid!
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_InvalidArgumentError) {
    console.error('Invalid argument:', error.message);
    // Check parameter types and values
  }
}

予防策：

• 型チェックには TypeScript を使用します
• AI SDK の関数を呼び出す前に入力を検証します
• 関数シグネチャを注意深く読みます
• パラメーターの制約について公式ドキュメントを確認します

---

7. AI_NoContentGeneratedError

原因： モデルがコンテンツを生成しませんでした（安全フィルターなど）。

解決策：

import { AI_NoContentGeneratedError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Some prompt',
  });
} catch (error) {
  if (error instanceof AI_NoContentGeneratedError) {
    console.error('No content generated');

    // Possible causes:
    // 1. Safety filters blocked output
    // 2. Prompt triggered content policy
    // 3. Model configuration issue

    // Handle gracefully:
    return { text: 'Unable to generate response. Please try different input.' };
  }
}

予防策：

• ユーザー入力をサニタイズします
• 安全フィルターが作動する可能性のあるプロンプトを避けます
• フォールバックメッセージを用意します
• 分析できるよう発生状況をログに記録します

---

8. AI_TypeValidationError

原因： 生成された出力が Zod スキーマの検証に失敗しました。

解決策：

import { AI_TypeValidationError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({
      age: z.number().min(0).max(120),  // Strict validation
    }),
    prompt: 'Generate person',
  });
} catch (error) {
  if (error instanceof AI_TypeValidationError) {
    console.error('Validation failed:', error.message);

    // Solutions:
    // 1. Relax schema constraints
    // 2. Add more guidance in prompt
    // 3. Use .optional() for unreliable fields
  }
}

予防策：

• 最初は緩やかなスキーマを使い、徐々に厳格化します
• 常に存在するとは限らないフィールドには .optional() を使用します
• フィールドの説明に検証のヒントを追加します
• さまざまなプロンプトでテストします

---

9. AI_RetryError

原因： すべての再試行に失敗しました。

解決策：

import { AI_RetryError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
    maxRetries: 3,  // Default is 2
  });
} catch (error) {
  if (error instanceof AI_RetryError) {
    console.error('All retries failed');
    console.error('Last error:', error.lastError);

    // Check root cause:
    // - Persistent network issue
    // - Provider outage
    // - Invalid configuration
  }
}

予防策：

• 失敗の根本原因を調査します
• 必要に応じて再試行の設定を調整します
• プロバイダーの停止に備えてサーキットブレーカーパターンを実装します
• フォールバックプロバイダーを用意します

---

10. レート制限エラー

原因： プロバイダーのレート制限（RPM/TPM）を超過しました。

解決策：

// Implement exponential backoff
async function generateWithBackoff(prompt: string, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await generateText({
        model: openai('gpt-4'),
        prompt,
      });
    } catch (error) {
      if (error instanceof AI_APICallError && error.statusCode === 429) {
        const delay = Math.pow(2, i) * 1000;  // Exponential backoff
        console.log(`Rate limited, waiting ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Rate limit retries exhausted');
}

予防策：

• レート制限ヘッダーを監視します
• 制限を超えないようリクエストをキューに入れます
• 必要に応じてプロバイダーのプランをアップグレードします
• リクエストのスロットリングを実装します

---

11. Zod 使用時の TypeScript のパフォーマンス

原因： 複雑な Zod スキーマにより、TypeScript の型チェックが遅くなります。

解決策：

// Instead of deeply nested schemas at top level:
// const complexSchema = z.object({ /* 100+ fields */ });

// Define inside functions or use type assertions:
function generateData() {
  const schema = z.object({ /* complex schema */ });
  return generateObject({ model: openai('gpt-4'), schema, prompt: '...' });
}

// Or use z.lazy() for recursive schemas:
type Category = { name: string; subcategories?: Category[] };
const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    name: z.string(),
    subcategories: z.array(CategorySchema).optional(),
  })
);

予防策：

• トップレベルで複雑なスキーマを避けます
• 再帰型には z.lazy() を使用します
• 大きなスキーマを小さなものに分割します
• 適切な場合は型アサーションを使用します

公式ドキュメント： https://ai-sdk.dev/docs/troubleshooting/common-issues/slow-type-checking

---

12. 無効な JSON レスポンス（プロバイダー固有）

原因： 一部のモデルは、ときどき無効な JSON を返します。

解決策：

// Use built-in retry and mode selection
const result = await generateObject({
  model: openai('gpt-4'),
  schema: mySchema,
  prompt: 'Generate data',
  mode: 'json',  // Force JSON mode (supported by GPT-4)
  maxRetries: 3,  // Retry on invalid JSON
});

// Or catch and retry manually:
try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: mySchema,
    prompt: 'Generate data',
  });
} catch (error) {
  // Retry with different model
  const result = await generateObject({
    model: openai('gpt-4-turbo'),
    schema: mySchema,
    prompt: 'Generate data',
  });
}

予防策：

• 利用可能な場合は mode: 'json' を使用します
• 構造化出力には GPT-4 を優先します
• 再試行ロジックを実装します
• レスポンスを検証します

GitHub の Issue： #4302（Imagen 3.0 の無効な JSON）

---

その他のエラー： https://ai-sdk.dev/docs/reference/ai-sdk-errors （全 28 件）

---

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

次の場合は ai-sdk-core を使用します：

• バックエンドの AI 機能（サーバー側のテキスト生成）を構築する
• サーバー側のテキスト生成（Node.js、Workers、Next.js）を実装する
• 構造化された AI 出力（JSON、フォーム、データ抽出）を作成する
• ツールを使う AI エージェント（複数ステップのワークフロー）を構築する
• 複数の AI プロバイダー（OpenAI、Anthropic、Google、Cloudflare）を統合する
• AI SDK v4 から v5 に移行する
• AI SDK のエラー（AI_APICallError、AI_NoObjectGeneratedError など）が発生した
• Cloudflare Workers で AI を使用する（workers-ai-provider を使用）
• Next.js のサーバーコンポーネント／アクションで AI を使用する
• 異なる LLM プロバイダー間で一貫した API が必要である

次の場合はこのスキルを使用しないでください：

• React のチャット UI を構築する（代わりに ai-sdk-ui スキルを使用します）
• useChat などのフロントエンドフックが必要である（代わりに ai-sdk-ui スキルを使用します）
• 埋め込みや画像生成などの高度なトピックが必要である（公式ドキュメントを確認します）
• 複数プロバイダーを使わず、Cloudflare Workers AI のネイティブアプリを構築する（代わりに cloudflare-workers-ai スキルを使用します）
• Generative UI／RSC が必要である（https://ai-sdk.dev/docs/ai-sdk-rsc を参照します）

---

バージョン

AI SDK：

• 安定版：[email protected]（2025 年 11 月 20 日）
• ベータ版：[email protected]（2025 年 11 月 22 日）
• Zod 3.x／4.x の両方をサポート（3.23.8 を推奨）

最新モデル（2025 年）：

• OpenAI：GPT-5.1、GPT-5、o3
• Anthropic：Claude Sonnet 4.5、Opus 4.1、Haiku 4.5
• Google：Gemini 2.5 Pro／Flash／Lite

最新情報の確認：

npm view ai version
npm view ai dist-tags  # See beta versions

---

Official Docs

Core:

• AI SDK 6 Beta: https://ai-sdk.dev/docs/announcing-ai-sdk-6-beta
• AI SDK Core: https://ai-sdk.dev/docs/ai-sdk-core/overview
• v4→v5 Migration: https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
• All Errors (28): https://ai-sdk.dev/docs/reference/ai-sdk-errors
• Providers (25+): https://ai-sdk.dev/providers/overview

GitHub:

• Repository: https://github.com/vercel/ai
• Issues: https://github.com/vercel/ai/issues

---

Last Updated: 2025-11-22 Skill Version: 1.2.0 AI SDK: 5.0.98 stable / 6.0.0-beta.107