メインコンテンツへスキップ
Todo 追跡は、タスクを管理し、ユーザーに進捗を表示するための構造化された方法を提供します。Claude Agent SDK には、複雑なワークフローを整理し、ユーザーにタスク進捗を知らせるのに役立つ組み込み todo 機能が含まれています。
TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降、セッションは TodoWrite の代わりに構造化された Task ツール TaskCreateTaskUpdateTaskGet、および TaskList を使用します。Python SDK は Python パッケージバージョンではなく、起動する Claude Code CLI からこの変更を取得します。スイッチは、その CLI(pip パッケージ内にバンドルされているコピー、または cli_path で指定するコピー)が v2.1.142 以降の場合に適用されます。監視コードの変更方法については、Task ツールへの移行を参照してください。このページの例では、まだ移行していないセッションの TodoWrite を引き続き表示するために CLAUDE_CODE_ENABLE_TASKS=0 を設定しています。

Todo ライフサイクル

Todo は予測可能なライフサイクルに従います:
  1. 作成 - タスクが識別されたときに pending として作成される
  2. アクティベート - 作業が開始されたときに in_progress に変更される
  3. 完了 - タスクが正常に完了したときに完了する
  4. 削除 - グループ内のすべてのタスクが完了したときに削除される

Todo が使用される場合

SDK は以下の場合に自動的に todo を作成します:
  • 複雑なマルチステップタスク - 3 つ以上の異なるアクションが必要な場合
  • ユーザー提供のタスクリスト - 複数のアイテムが言及されている場合
  • 非自明な操作 - 進捗追跡の恩恵を受ける場合
  • 明示的なリクエスト - ユーザーが todo 整理を要求した場合

これらの例を実行する前に、クイックスタートに従って Claude Agent SDK をインストールしてください。 各例はエージェントが完了して最終結果メッセージを生成するまで実行されます。セッションがターン制限に最初に達した場合、その結果メッセージは error_max_turns サブタイプを持ちます。終了を検出するために subtype を確認してください。 これらの例は単一ショットの query() 呼び出しを使用します。error_max_turns 結果を生成した後、query()Reached maximum number of turns を含むエラーを発生させます。各例はそれが発生したときにクリーンに終了するために、ループを try ブロックでラップします。 結果サブタイプについては、結果を処理するを参照してください。

Todo 変更の監視

リアルタイム進捗表示

Task ツールへの移行

Task ツールは、単一の TodoWrite 呼び出しを、各新規アイテムの TaskCreate と各ステータス変更の TaskUpdate に分割し、TaskListTaskGet はモデルが現在のリストを読み戻すために利用可能です。監視コードは引き続きアシスタントストリーム内の tool_use ブロックを検査しますが、すべての呼び出しでリスト全体を置き換える代わりに、タスク ID でキー付けされたマップを保持します。Task ツールは TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降のデフォルトであるため、options.env の変更は不要です。 割り当てられたタスク ID は TaskCreate 入力にはありません。マッチング tool_result{ task: { id, subject } } として返されるため、マップをキー付けするために結果ブロックからそれをキャプチャします。次の例は、Todo 変更の監視ループへの最小限の変更を示しています。ストリーム内の TaskList ツール結果を監視するか、TaskCreate 結果と TaskUpdate 入力をマップに蓄積することで、完全なリストをレンダリングできます。 ストリーミングされた tool_use 入力は、モデルが発行した生の形状です。Claude Code は実行前にいくつかの近いが正確でないキー名を修復し、id または task_idtaskId にマッピングし、active_formactiveForm にマッピングしますが、その修復はストリームに反映されません。以下のサンプルのように、常に正規名が存在すると仮定するのではなく、TaskUpdate 入力フィールドを防御的に読み取ります。