Claude Agent SDK TypeScript V2の削除と移行手順

公開 更新 著者 永上裕之仕事の自動化
ロボットが古い鍵付きの箱から新しい通り道へ書類を運び替えている様子のイメージ

この記事の要点

  • TypeScript版Agent SDKのV2セッションAPI(unstable_v2_createSession など)は、0.3.142 で削除された
  • 移行先は query()。複数ターンは AsyncIterable で入力を流し、続きは options.resume で再開する
  • 0.2系を使い続ける場合は、メジャーとマイナーを固定してインストールすれば動き続ける

活用例:TypeScriptで作った社内のAIエージェントを、SDKの更新後も動かし続ける

部署
開発・情報システム
使うもの
Claude Agent SDK(TypeScript)
AIに任せる
旧コードの洗い出し・query() への書き換え案の作成
人が決める
どのバージョンに固定するか・更新の時期

「V2のセッションAPIが便利そうだったので試作に使っていた」という人は、更新の前に確認が必要です。TypeScript版のAgent SDKでは、V2のセッションAPIが削除されました。 更新したら import の時点で動かなくなります。

この記事は、公式ドキュメント「TypeScript SDK V2 session API (removed)」(2026年11月20日確認)にもとづいて、何が消えたのか、どう書き直すのかを整理します。SDK全体の基本は Agent SDKの記事、会話の続き方は セッションの記事 もあわせてご覧ください。

結論:消えたのは3つの関数と2つの型

公式ページの冒頭には、V2はもうサポートされないという警告が出ています。TypeScript版Agent SDKの 0.3.142 で、次のものが取り除かれました。

削除されたもの役割
unstable_v2_createSession新しいセッションを作る
unstable_v2_resumeSession保存したセッションを再開する
unstable_v2_prompt一回きりの質問をする
SDKSession と SDKSessionOptions上の関数が使う型

移行先は、従来からある query() です。複数ターンの会話は、入力を AsyncIterable(SDKUserMessage の流れ)で渡します。続きから再開するときは、options の resume にセッションIDを渡します。

V2とは何だったのか

V2は、実験的に用意されたセッション用の書き方でした。V1の query() は、入力も出力も1つの非同期ジェネレーターを通るため、ターンをまたぐ処理では「次のメッセージをいつ流すか」を自分で調整する必要がありました。V2は、これを send() と stream() の往復に分けて、会話のたびに「送る」「受け取る」を別々に書けるようにしたものです。

公式の説明では、V2はジェネレーターの状態管理を減らすための実験的な書き方でした。つまり、便利だったのは書き味であって、できることが増えたわけではありません。セッションの分岐(forkSession)など、V1でしか使えない機能も最初からありました。

手順1:一回きりの質問を書き直す

V2では unstable_v2_prompt に質問とモデルを渡すだけでした。V1では query() を回して、結果のメッセージが成功かどうかを確かめます。

import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({
  prompt: "What is 2 + 2?",
  options: { model: "claude-opus-4-7" }
});

for await (const msg of q) {
  switch (msg.type) {
    case "result":
      if (["success"].includes(msg.subtype)) console.log(msg.result);
      break;
  }
}

ポイントは、for await で流れてくるメッセージのうち、type が result のメッセージが最終の答えで、subtype が success のときに result の文字列を使うだということです。途中のメッセージも同じ流れに混ざって届きます。

手順2:複数ターンの会話を書き直す

V2では、同じセッションに send() を2回呼べば、前の答えを覚えたまま続きの質問ができました。V1で同じことをするには、入力側を非同期ジェネレーターにして、ユーザーのメッセージを順に流します。

import { query } from "@anthropic-ai/claude-agent-sdk";

async function* createInputStream() {
  yield {
    type: "user",
    session_id: "",
    message: { role: "user", content: [{ type: "text", text: "What is 5 + 3?" }] },
    parent_tool_use_id: null
  };
  yield {
    type: "user",
    session_id: "",
    message: { role: "user", content: [{ type: "text", text: "Multiply by 2" }] },
    parent_tool_use_id: null
  };
}

const q = query({
  prompt: createInputStream(),
  options: { model: "claude-opus-4-7" }
});

出力の受け取り方は、手順1と同じ for await です。公式の例では、アシスタントのメッセージから text のブロックだけを取り出してつなげ、画面に出しています。

注意点があります。上の書き方は、2つ目のメッセージをいつ流すかを、ジェネレーターの中で自分で決める必要があります。V2のように「1ターン終わってから次を送る」を自然に書けないので、ターン間で処理を挟みたい場合は、ジェネレーターの待ち方を設計することになります。

手順3:セッションを保存して再開する

V2では、stream() で受け取ったメッセージから session_id を控えておき、あとで resumeSession に渡していました。V1では、最初の query() のメッセージから session_id を取り出し、次の query() の options に resume として渡します。

let sessionId: string | undefined;
for await (const msg of initialQuery) {
  sessionId = msg.session_id;
}

const resumedQuery = query({
  prompt: "What number did I ask you to remember?",
  options: { model: "claude-opus-4-7", resume: sessionId }
});

公式の例では、最初の質問で「42を覚えて」と伝え、再開した側で「何の数字だった?」と聞いて、前の会話が引き継がれていることを確かめています。アプリを再起動しても会話を続けたいときは、このセッションIDを保存しておくのが基本です。保存の仕組みは セッションの記事 にまとめています。

手順4:後始末の書き方を見直す

V2では、await using(TypeScript 5.2以降)でセッションを自動で閉じるか、session.close() を手で呼んでいました。query() にはセッションを閉じる操作がありません。for await で流れを最後まで受け取れば、それで一区切りです。移行のときは、close() を呼んでいた箇所を消し、代わりに「流れを最後まで読み切っているか」を確認してください。

古いSDKに留まる場合

すぐに書き直せないときは、V2が残っている最後の系列に固定できます。公式によれば、パッケージのバージョンは 0.2.x から 0.3.142 へ直接飛んでいます。 V2対応の最後のリリースを入れるには、メジャーとマイナーを固定します。

npm install @anthropic-ai/claude-agent-sdk@0.2

ただし、これは時間稼ぎです。公式ページは、0.2系以前のコードを保守している人向けの参照として残してある、と書いています。固定したまま放置せず、移行の期限を決めておくのが安全です。

移行チェックリスト

まとめ

  1. TypeScript版Agent SDKのV2セッションAPIは、0.3.142 で削除された
  2. 移行先は query()。複数ターンは AsyncIterable、再開は options.resume
  3. すぐ直せないときは @0.2 で固定できるが、期限つきの時間稼ぎとして使う
  4. 更新前に unstable_v2 を検索し、置き換えと動作確認を済ませておく

SDKの旧版から新版への書き換え全般は 移行ガイドの記事 にもまとめています。

出典:TypeScript SDK V2 session API (removed)(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事