メインコンテンツへスキップ
V2 セッション API はサポートされなくなりました。TypeScript Agent SDK 0.3.142 では unstable_v2_createSessionunstable_v2_resumeSessionunstable_v2_prompt、および SDKSessionSDKSessionOptions 型が削除されます。移行するには、query() API と、それが受け入れる セッションオプション を使用してください。マルチターン会話の場合は AsyncIterable<SDKUserMessage> を渡すか、保存されたセッションを続行するには options.resume を使用してください。このページは、Agent SDK 0.2.x 以前のコードを保守している場合の参照用に保持されています。
V2 は、非同期ジェネレータと yield 調整の必要性を排除した実験的なセッション API でした。ターン間でジェネレータの状態を管理する代わりに、各ターンは個別の send()/stream() サイクルになります。API サーフェスは 3 つの概念に縮小されました。
  • createSession() / resumeSession():会話を開始または継続する
  • session.send():メッセージを送信する
  • session.stream():レスポンスを取得する

インストール

Agent SDK 0.2.x は V2 インターフェースを含む最後のバージョンです。パッケージバージョンは 0.2.x から直接 0.3.142 にジャンプしたため、上記の削除バージョンと下記のインストールピンは同じ境界を説明しています。最後の V2 互換リリースをインストールするには、メジャーバージョンとマイナーバージョンをピンしてください。
SDK はオプションの依存関係として、プラットフォーム用のネイティブ Claude Code バイナリをバンドルしているため、Claude Code を別途インストールする必要はありません。

クイックスタート

ワンショットプロンプト

セッションを維持する必要がない単純なシングルターンクエリの場合は、unstable_v2_prompt() を使用します。この例は数学の質問を送信し、答えをログに出力します。

基本的なセッション

単一のプロンプトを超えるインタラクションの場合は、セッションを作成します。V2 は送信とストリーミングを個別のステップに分離します。
  • send() はメッセージをディスパッチします
  • stream() はレスポンスをストリーミングします
この明示的な分離により、ターン間にロジックを追加しやすくなります(レスポンスを処理してからフォローアップを送信するなど)。 以下の例はセッションを作成し、「Hello!」を Claude に送信し、テキストレスポンスを出力します。await using(TypeScript 5.2 以降)を使用して、ブロックが終了するときにセッションを自動的に閉じます。session.close() を手動で呼び出すこともできます。

マルチターン会話

セッションは複数の交換全体でコンテキストを保持します。会話を続けるには、同じセッションで send() を再度呼び出します。Claude は前のターンを記憶しています。 この例は数学の質問を尋ねてから、前の答えを参照するフォローアップを尋ねます。

セッションの再開

前のインタラクションからセッション ID がある場合は、後でそれを再開できます。これは長時間実行されるワークフローや、アプリケーションの再起動全体で会話を永続化する必要がある場合に便利です。 この例はセッションを作成し、その ID を保存し、それを閉じてから会話を再開します。

クリーンアップ

セッションは手動で閉じるか、await using(自動リソースクリーンアップ用の TypeScript 5.2 以降の機能)を使用して自動的に閉じることができます。古い TypeScript バージョンを使用している場合や互換性の問題が発生した場合は、代わりに手動クリーンアップを使用してください。 自動クリーンアップ(TypeScript 5.2 以降):
手動クリーンアップ:

API リファレンス

unstable_v2_createSession()

マルチターン会話用の新しいセッションを作成します。

unstable_v2_resumeSession()

ID で既存のセッションを再開します。

unstable_v2_prompt()

シングルターンクエリ用のワンショット便利関数。

SDKSession インターフェース

機能の可用性

V2 セッション API は、すべての V1 機能をサポートしていません。以下は V1 SDK を使用する必要があります。
  • セッションフォーキング(forkSession オプション)
  • 一部の高度なストリーミング入力パターン

関連項目