ai-sdk

ai-sdk skill の概要

この ai-sdk skill でできること

ai-sdk skill は、Vercel の AI SDK を使って開発する開発者向けの実践ガイドです。とくに、一般的な LLM の助言ではなく、現行バージョンを踏まえた正確な情報が必要な場面で力を発揮します。主な役割は、適切な API 形状の選定、最新構文の確認、古い実装パターンの回避を支援しながら、アプリに chat、streaming、tools、structured generation、embeddings、agents を組み込めるようにすることです。

どんな人に ai-sdk skill は向いているか

特に相性が良いのは、次のような人です。

• ai-sdk for Full-Stack Development を検討しているフルスタック開発者
• 古い AI SDK コードを新しい API へ移行したいチーム
• generateText、streamText、tools、ToolLoopAgent、useChat を使っている開発者
• OpenAI、Anthropic、Google、gateway 経由の利用方法を比較したい人
• 単なる「AI コードを書いて」で始めるより、手戻りを減らしたい開発者

なぜ一般的なプロンプトよりこの skill のほうが有用か

この skill の最大の違いは、AI SDK に関するモデル内部の知識が古くなっていることを明確に警告している点です。記憶頼みではなく、ローカルに入った package docs、ソースコードの確認、さらに API 変更点、gateway の使い方、devtools、型安全な agent パターンといった的を絞った参照先へ導いてくれます。そのため、この ai-sdk skill は、通常のプロンプトよりも導入判断や実装作業において信頼しやすいガイドになっています。

導入前にまず確認したいポイント

多くの人が最初に気にするのは次の点です。

• まず ai だけを入れるべきか
• provider package は後から必要に応じて選ぶべきか、最初からまとめて入れるべきか
• 最近どの API が変わったのか
• ネット上の useChat サンプルが今でも有効か
• tool loop や streaming の実行をどうデバッグするか
• SDK が server route、React UI、その両方に合うか

もしここが導入の詰まりどころなら、このページでかなり時間を節約できます。

ai-sdk skill の使い方

最小構成の ai-sdk install から始める

最初のインストールは、できるだけ小さく始めるのが基本です。

pnpm add ai

ここでの repository guidance には意図があります。最初はコアの ai package だけを入れてください。実際の用途が固まる前に、@ai-sdk/openai、@ai-sdk/react、その他の provider/client package を追加しないほうが安全です。そうすることで思い込みを減らし、実装を現行ドキュメントに沿わせやすくなります。

GitHub skill 自体を agent workflow に追加する場合は、次を使います。

npx skills add vercel/ai --skill ai-sdk

コードを聞く前にローカル docs を確認する

重要なのは、「記憶から聞く」ことではありません。基本の使い方は次の流れです。

1. node_modules/ai/docs/ が存在することを確認する
2. node_modules/ai/docs/ と node_modules/ai/src/ を検索する
3. その後で必要なら ai-sdk.dev や repository references を見る

これがこの ai-sdk guide で最も重要な実務上の振る舞いです。AI SDK の API は変化が速く、公開されているサンプルの多くは現行状態に追いついていません。

最初に読むべきファイル

短時間で全体像をつかみたいなら、次の順で読むのがおすすめです。

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

この順番が有効な理由は次の通りです。

• SKILL.md で発動条件と基本 workflow が分かる
• common-errors.md で API rename の落とし穴を早めに回避できる
• ai-gateway.md でまず動く model まで素早くたどり着ける
• devtools.md でコードが動き始めた後のデバッグ効率が上がる
• type-safe-agents.md は UI と agent の型を揃えたいときに重要になる

コードを書く前に現在の API ずれを把握する

導入時の大きなつまずきは、古いサンプルをそのまま写してしまうことです。reference では、ai-sdk usage に実質的な影響がある変更点として、次のようなものが挙げられています。

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• tool parameters → inputSchema
• 一部の古い object-generation パターンは変更されている
• useChat は大きく変わっているため、流用前に必ず確認が必要

最初の問い合わせで現在の package version と legacy code を一緒に渡すと、移行支援の精度がかなり上がります。

まず最短で成功体験を得たいなら AI Gateway を使う

多くのチームでは、gateway 経由のセットアップが最短ルートになりやすいです。この skill には Vercel AI Gateway の有用な reference があり、たとえば次のように文字列で model を選べます。

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

これは、provider SDK の配線を細かく詰めることよりも、まずプロダクトの挙動を素早く検証したいときに特に有効です。

ただし、model ID を固定で書く前に、現在の model list を取得してください。reference でも、model 名を記憶頼みで扱わないよう明確に注意しています。

ai-sdk skill に渡すべき入力

この skill に必要なのは、適切な package 構成と API パターンを選べるだけの文脈です。良い依頼には通常、次の情報が含まれます。

• runtime: Next.js、Node.js、Vercel、edge/serverless など
• goal: chat UI、agent、RAG、structured extraction、tool calling
• 現在の package versions
• streaming が必要かどうか
• provider の希望、または gateway を使うか
• React hooks が必要か、server-only でよいか
• 失敗しているコードと正確な error text

弱い入力:

• "Help me use AI SDK"

強い入力:

• "I have a Next.js app router project on AI SDK 6, need streaming chat with tool calling, want to start with gateway, and my old useChat code no longer works. Show the minimal server route and UI shape."

後者のようなプロンプトなら、skill 側で見るべき docs と現行 API 名を絞り込みやすくなります。

ざっくりした要件を、より良い ai-sdk prompt に変える

良い依頼の型は次の通りです。

• アプリの文脈
• 実現したいユーザー体験
• 現在の実装状況
• 制約条件
• 期待する出力形式

例:

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

単に「agent を作って」と頼むより、こちらのほうが skill が汎用的な足場コードに流れず、必要な形に絞って案内しやすくなります。

よくある作業ごとに適切な workflow を選ぶ

この skill は、目的に応じて使い分けると効果が高まります。

• 初回 install: 最小 package 構成と、ひとつだけ動く request を聞く
• migration: 古いコードを貼り、API rename と挙動差分を確認する
• tool calling: tool schema の形と stop condition を聞く
• frontend chat: 現在の useChat パターンを明示して聞く
• debugging: DevTools での run の見方と trace の保存先を確認する

こうした「作業別の聞き方」にできる点が、単に repository を流し読みするよりもこの ai-sdk skill が価値を出しやすいところです。

コードは動くのに挙動がおかしいときは DevTools を使う

コードはコンパイルを通るのに model の挙動がおかしい場合、DevTools の reference は非常に役立ちます。SDK calls、steps、tool interactions を記録し、次に保存します。

.devtools/generations.json

特に有効なのは次のようなケースです。

• 見えづらい tool-call loop
• 壊れた structured output
• prompt と tool の不整合
• 分かりにくい streaming 挙動
• agent 実行中の token 数や step の確認

導入判断という観点でも、初期 install 後のデバッグコストを下げられるのは大きな利点です。

UI 描画が重要なら type-safe agent パターンを使う

agent を使った UI を作るなら、type-safe agent の reference は、この skill が単なるおもちゃサンプル以上に使えることを示す強い材料です。agent 定義から推論された UIMessage 型を export するパターンが紹介されており、useChat の描画をより安定させやすくなります。

これは特に ai-sdk for Full-Stack Development に関係が深く、backend 側の agent 設定と frontend 側の message rendering をずらさず保ちたい場合に有効です。

この skill が向いていないケース

主に次のことが必要なら、この skill は第一候補ではありません。

• ai package と無関係な provider 固有 SDK の docs
• 実装を伴わない一般的な prompt engineering の助言
• Python 中心の AI アプリ開発ガイド
• framework 非依存の LLM 理論

この skill が最も向いているのは、JavaScript/TypeScript スタックで AI SDK をどう実装・デバッグするかが具体的な論点になっている場合です。

ai-sdk skill FAQ

この ai-sdk skill は初心者にも向いていますか？

はい。基本的な JavaScript または TypeScript に慣れているなら有用です。最初の一歩を絞ってくれるという意味では初心者向けですが、project files を編集し、package を install し、framework の流儀に従えることは前提になります。

ai-sdk skill があれば docs を読まなくていいですか？

いいえ。これは、どこを見ればよいか、どの現行パターンを信用すべきかを示すルーティング層として使うのが最適です。核となる価値は source docs の代替ではなく、無駄な遠回りを減らすことにあります。

ai-sdk install 前に最大の注意点は何ですか？

古いサンプルや、モデルの記憶にある AI SDK 構文を信じないことです。repository でも、まずインストール済み docs と source を確認するよう繰り返し強調されています。これは細かい注意ではなく、正しい ai-sdk install と実装の中心にある前提です。

provider package は最初に全部入れるべきですか？

通常は不要です。まずは ai から始め、用途が固まってから provider や client package を追加してください。そのほうが依存関係の選択に意図を持てますし、古い前提をそのまま setup に持ち込まずに済みます。

これは主に chat app 向けですか？

いいえ。chat は代表的な用途ですが、この skill は structured generation、tool calling、agents、embeddings、gateway ベースの model access、streamed server responses にも適しています。

LLM に AI SDK のコードを書かせるのと何が違いますか？

一般的なプロンプトだと、古い API を自信満々に生成してしまうことがあります。この skill が優れているのは、ローカル docs、現行 reference、既知の migration 落とし穴、読むべきファイルを含む検証 workflow に誘導する点です。その結果、信頼性が上がり、やり直しも減ります。

React や useChat にも対応していますか？

はい。ただし注意点があります。useChat は大きく変わっています。古い snippet はそのまま信用せず、UI サンプルを流用する前に、この skill で現行の形を確認するのが安全です。

どんなときはこの ai-sdk guide を使わないほうがよいですか？

課題の中心が vendor の請求、model 評価戦略、非 JS プラットフォーム連携である場合は、優先度は下がります。現在の AI SDK 実装の細部がボトルネックなら、この guide を使う価値があります。

ai-sdk skill をより効果的に使うには

ゴールだけでなく version 情報も渡す

結果を最も速く改善できるのは、正確な version を含めることです。特に ai と関連 package の version は重要です。「AI SDK のコードがほしい」だけでは、新しい release を使っているのか、古いコードを移行中なのかが分からず、精度が落ちます。

まずは最小の動作単位を頼む

「フル機能の agent app を作って」より、次のように段階を切ったほうが有効です。

• "show the smallest generateText example"
• "add one tool"
• "then stream it"
• "then wire useChat"

この段階的な workflow にすると、複雑さが増す前に各ステップを現行 docs と照合できるため、この ai-sdk guide の実用性が大きく上がります。

エラーはそのまま載せる

何か壊れたら、正確な error と該当 snippet をそのまま含めてください。common-errors.md が存在するのは、API 名が少し違うだけで起きる問題が非常に多いためです。ひとつの正確な error があるだけで、古い docs を見ているのか、import が間違っているのか、option 名が古いのかを切り分けやすくなります。

gateway を使いたいのか、provider 直結なのかを明示する

最初に次のどれかを示すだけで、曖昧さがかなり減ります。

• "Use Vercel AI Gateway first"
• "Use direct OpenAI provider package"
• "Keep provider choice abstract for now"

これによって install commands、model 選定、サンプル構成が変わります。

runtime と framework の境界条件を明確にする

より的確な ai-sdk usage 支援を受けるには、次の点を明示してください。

• server-only か、client + server か
• Next.js App Router か、別 framework か
• edge runtime か Node runtime か
• TypeScript の strictness
• tools が internal APIs を呼ぶのか、external services を呼ぶのか

これらは「正しいコード」がどう見えるかに直接影響します。

よくある失敗パターンを把握しておく

品質を大きく落としやすいのは、主に次の点です。

• 古い useChat サンプルに依存する
• 廃止済み option 名をそのまま使う
• 古い model ID を固定で書く
• package を早い段階で入れすぎる
• tools と stop condition を定義せず agent コードを求める
• run traces ではなく console logs だけでデバッグする

これらを避けるだけでも、この ai-sdk skill の信頼性はかなり上がります。

2 つの実装パスを比較させる

改善策として強いのは、単にコードを求めるのではなく、判断そのものを依頼することです。たとえば次のような形です。

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

この種のプロンプトは、「docs を見せて」よりも導入判断に役立つ答えを引き出しやすくなります。

最初の回答のあと、根拠つきでやり取りを続ける

最初の出力のあとに、次のいずれかを返すと精度がさらに上がります。

• 現在の file tree
• install 済み package list
• 実際に失敗している request
• 取得済みの .devtools/generations.json の抜粋
• node_modules/ai/docs/ にあるローカル docs の抜粋

こうした根拠ベースの反復こそが、ai-sdk skill を一般論から実装レベルの支援へ引き上げる最短ルートです。