マルチエージェントAgent SDK の進み具合表示｜Todo を画面に出す
この記事の要点
- Todo の道具を使うと、AI は作業の一覧を書き、1つずつ状態を変えながら進める。その変化は道具の呼び出しとして届く
- 新しいモデルでは既定で使われない。進み具合を画面に出したい時だけ、3つのどれかの方法で有効にする
- 流れてくる入力は AI が書いたままの形。項目の名前が少し違うこともあるので、余裕を持って読み取る
社内向けに AI エージェントの画面を作ると、「いま何をしていて、あと何が残っているのか」 を知りたいという声が必ず出ます。長い作業ほど、途中の様子が見えないと不安になります。
この記事では、公式ドキュメント「Track todos」（2026年11月11日確認）にもとづいて、Claude Agent SDK で AI の作業の一覧（Todo）を受け取り、自分の画面に進み具合を出す方法を整理します。SDK の全体像は Claude Agent SDK とは で解説しています。
結論：Todo は「AI が書く作業の一覧」で、変化は道具の呼び出しとして届く
Todo の道具がある会話では、AI は作業の一覧を書き、1つずつ状態を変えながら進めます。 その変化は、メッセージの流れの中に「道具の呼び出し」として届きます。アプリの側はそれを拾って、記録に残したり、進み具合の表示にしたりします。
ただし、新しいモデルは一覧を書かなくても長い作業を進められる ため、既定ではこの道具が使われません。進み具合を自分の画面に出したい時だけ、有効にします。
既定で使えるモデルと、有効にする方法
公式ドキュメントでは、Todo の道具（TodoWrite と、TaskCreate・TaskGet・TaskUpdate・TaskList の4つ）が既定で使えるのは、Claude Opus 4.7・Claude Sonnet 4.6・Claude Haiku 4.5 と、それより前のモデル とされています。それ以外のモデルでは、次の 3つのどれか で有効にします。
| 方法 | やること |
|---|---|
| 許可の一覧に入れる | allowedTools に、Todo の道具の名前を1つ入れる |
| 道具の一覧に入れる | tools の一覧に入れる（この一覧は使える道具を絞るので、ほかに使う道具も一緒に書く） |
| 環境変数を入れる | env に CLAUDE_CODE_ENABLE_TODO_TOOLS=1 を入れる |
この既定は Claude Code 2.1.268 以降（TypeScript 版 SDK は 0.3.268 以降に同梱）のものです。自分で入れた Claude Code を SDK から使うように指定している時は、その版の既定に従います。
TypeScript 版で env を指定すると、元の環境変数が置き換わります。元の環境変数も残したい時は、元の値を一緒に入れます。 Python 版では、元の環境変数の上に足される形です。
作業の状態は4段階で進む
| 段階 | 状態 | いつ |
|---|---|---|
| 作られた | pending | AI がやることを見つけた時 |
| 始めた | in_progress | その作業に取りかかった時 |
| 終わった | completed | うまく終わった時 |
| 消した | deleted | もう要らなくなった時 |
AI が一覧を作るのは、3つ以上の手順がある作業・利用者が複数のことを頼んだ時・時間がかかる作業・一覧にしてと頼まれた時 です。短い1回で終わる依頼では、一覧を作らないこともあります。
画面に出す時の2つの型
公式ドキュメントでは、使い方に合わせて2つの型が紹介されています。
- 記録を残す型：作られた作業と、状態の変化を1行ずつ書き出す。作業の履歴を残したい時に向く
- 進み具合を表示する型：作業の番号ごとに状態を覚えておき、変化のたびに「完了の数・作業中の数」と、いま進めている作業の説明を出し直す
2つめの型では、作業の番号は、作った時の入力には入っていない 点に注意します。番号は、道具の結果として返ってくる側（tool_use_result）に入ります。結果を待ってから、作業と番号を結びつけます。返事を少しずつ表示する方法は Agent SDK のストリーミング で解説しています。
読み取る時の注意
流れてくる入力は、AI が書いたままの形です。 たとえば作業の番号の項目名が、正しい名前と少し違う形で書かれることがあります。Claude Code は実行する前にこれを直しますが、直した結果は流れてくる内容には反映されません。 読み取る側では、名前が少し違っても拾えるように書いておきます。
また、裏で動かしているコマンドやサブエージェントの知らせは、Todo とは別のメッセージで届きます。Todo の進み具合は、道具の呼び出しの方を見ます。
仕事での使いどころ
- 長い資料づくり：調べる・まとめる・図にする、の進み具合を依頼した人の画面に出す
- 作業の記録：AI がどの順番で何をしたかを、あとから確かめられるように残す
- 止まった場所の把握：回数の上限で止まった時に、どの作業まで終わっていたかを見る
回数の上限で止まった時は、最後のメッセージの種類が error_max_turns になります。止まり方の見分け方を用意しておくと、続きから頼み直しやすくなります。
よくある質問
新しいモデルで Todo を使わないと、作業の質は落ちますか？
落ちるとは書かれていません。 公式ドキュメントでは、新しいモデルは一覧を書かなくても長い作業を進められるため、AI に作業を進めてもらうだけなら、このページの設定は要らないとされています。有効にするのは、アプリの側で一覧を読んで使いたい時だけ です。
費用はどう確かめますか？
使った量と費用は、メッセージの流れから読み取れます。Agent SDK の費用と使用量の記録 で解説しています。
まとめ
- Todo は AI が書く作業の一覧 で、変化は道具の呼び出しとして届く
- 新しいモデルでは既定で使われない。画面に出したい時だけ3つの方法のどれかで有効にする
- 流れてくる入力は書いたままの形。名前の違いに余裕を持って読み取る
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
