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() の往復に分けて、会話のたびに「送る」「受け取る」を別々に書けるようにしたものです。
- createSession と resumeSession:会話を始める、または続ける
- session.send():メッセージを送る
- session.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系以前のコードを保守している人向けの参照として残してある、と書いています。固定したまま放置せず、移行の期限を決めておくのが安全です。
移行チェックリスト
- [ ] コード内の unstable_v2 で始まる関数を全部検索した
- [ ] SDKSession、SDKSessionOptions の型を使っている箇所を洗い出した
- [ ] 一回きりの質問を query() と for await に置き換えた
- [ ] 複数ターンの会話は、入力用の非同期ジェネレーターに置き換えた
- [ ] 再開は options.resume とセッションIDの保存で書き直した
- [ ] await using と close() に頼っていた後始末を見直した
- [ ] 更新前に、固定したバージョンで動作確認をした
まとめ
- TypeScript版Agent SDKのV2セッションAPIは、0.3.142 で削除された
- 移行先は query()。複数ターンは AsyncIterable、再開は options.resume
- すぐ直せないときは @0.2 で固定できるが、期限つきの時間稼ぎとして使う
- 更新前に unstable_v2 を検索し、置き換えと動作確認を済ませておく
SDKの旧版から新版への書き換え全般は 移行ガイドの記事 にもまとめています。
出典:TypeScript SDK V2 session API (removed)(公式ドキュメント)
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


