deepagentsとは｜LangChain公式教材で作る計画・ファイル・サブエージェント

「エージェントを作る」と言ったとき、モデルにツールを渡してループを回すところまでは誰でもすぐ書ける。詰まるのはその先——長い作業で計画を見失う、文脈があふれる、サブタスクの調査ログで本体の会話が埋まる。deepagents は、この3点への対処を最初から載せた LangChain 公式のエージェント基盤だ。そして langchain-ai/deep-agents-from-scratch は、その中身を LangGraph だけで組み直して学ぶ公式教材にあたる。

エージェント基盤の選択肢を横並びで見たい場合は、AIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証に9種のフレームワークをまとめてある。本記事はそのうち LangChain 公式の系譜を1本だけ深掘りする位置づけになる。

deepagentsとは——LangGraph の上に載る「バッテリー同梱」の層

deepagents は LangGraph を土台に、汎用エージェントに必要な部品をあらかじめ組み込んだ Python パッケージだ。公式ドキュメントは LangGraph 本体との住み分けを「まず速く動かしたいなら Deep Agents、制御を自分で書きたいなら LangGraph 本体」と案内している。

パッケージ本体のリポジトリ langchain-ai/deepagents は GitHub star 28,757、fork 4,037、MIT ライセンス（2026-08-31 時点、GitHub API 実測）。PyPI のリリース数は 123 に達しており、最新版 0.7.11 は 2026-08-28 公開だ。1年足らずで 123 リリースというペースは、後述する「教材と最新版のずれ」の直接の原因でもある。

deepagents が最初から積んでいるのは、大づかみに次の4つになる。

教材リポジトリの README は、この設計が Manus や Claude Code といった実運用エージェントの「文脈エンジニアリング」パターンの共通項を抽出したものだ、と説明している。実際 Manus のブログを引いて「平均的なタスクで約50回のツール呼び出しを使う」と書いており、長時間タスクを前提にした設計であることが出発点になっている。

公式教材 deep-agents-from-scratch の中身

langchain-ai/deep-agents-from-scratch は star 817・fork 324・MIT。言語の内訳は Jupyter Notebook で、リポジトリのファイル数はわずか35本しかない。中身は次の5ノートブックが本体だ。

src/deep_agents_from_scratch/ 配下には todo_tools.py・file_tools.py・task_tool.py・prompts.py が置かれていて、ノートブックはこれらを import しながら組み上げていく。prompts.py が 9,489 バイトあるのが象徴的で、「バッテリー同梱」の実体の少なくない部分がプロンプト文そのものだと分かる。

ノートブックの順番はそのまま deepagents の設計の順番でもある。0_create_agent でツール付きのループを作り、1_todo で計画を、2_files で文脈退避を、3_subagents で委譲を足し、4_full_agent で全部を1本にまとめる。途中で「なぜこの部品が要るのか」が体感できるように、先に不便を味わわせてから解決策を足す構成になっているので、飛ばし読みには向かない。1_todo が537 KBと5本で最大なのは、TODO の書き出しと読み返し（recitation）の効き方を実行例で見せるためにセル出力が多く残っているからだ。

つまりこの教材は、deepagents パッケージの使い方を教える本ではない。パッケージが隠している中身を、LangGraph の素の API で書き直すための教材だ。だから「deepagents を業務で使いたい」人と「deepagents の中身を理解したい」人とで、読むべきものが分かれる。

deepagents のインストールと最小の使い方

教材の README は uv sync を案内しているが、パッケージ単体を触るだけなら venv と pip で足りる。本記事の実測はすべてこの手順で行った。

python3 -m venv /tmp/da_venv
/tmp/da_venv/bin/pip install deepagents
/tmp/da_venv/bin/python -c "import importlib.metadata as md; print(md.version('deepagents'), md.version('langchain'))"
# => 0.7.11 1.3.18

エージェント自体は1行で作れる。グラフの構築時点ではモデルAPIを呼ばないので、APIキーがダミーでもツール構成の確認まではできる（実行にはもちろん本物のキーが要る）。

from deepagents import create_deep_agent

agent = create_deep_agent(model="claude-sonnet-4-5")
print(sorted(agent.nodes["tools"].tools_by_name))
# => ['delete', 'edit_file', 'execute', 'glob', 'grep', 'ls', 'read_file', 'task', 'write_file']

ここで1つ注意がある。0.7.11 の create_deep_agent の docstring は既定ツールを8本（ファイル操作6本＋execute＋task）としか列挙しておらず、実際にグラフへ載る delete が抜けている。上の実行結果が9本を返すのが実体で、ドキュメント側が追いついていない。

create_deep_agent() が返すのは LangGraph の CompiledStateGraph なので、以降は LangGraph のやり方でそのまま扱える。0.7.11 のシグネチャは引数22個まで増えており、subagents でサブエージェント定義を渡す、permissions でファイル操作の許可範囲を絞る、skills で Agent Skills を読み込ませる、といった調整が入口の1関数に集約されている。

deepagents 実測①：教材の 0.2.7 と最新 0.7.11 で既定ツールが入れ替わっている

教材リポジトリには Nov_2025_pkgs という素朴な名前のファイルがあり、中身は検証時点の依存バージョン一覧だった。uv.lock の固定値とも一致する。

そこで両版を別の venv に入れ、create_deep_agent(model="claude-sonnet-4-5") の既定ツールを機械的に取り出して比べた。結果が下の表で、ツール数は9本のまま同じなのに、中身が1本入れ替わっている。

write_todos は教材の第2章（1_todo.ipynb）が丸ごと扱っているテーマそのものだ。それが最新版の既定から外れている。0.2.7 の graph.py には「このエージェントは既定で todo を書くツール（write_todos）を持つ」という記述がソースコードのコメントに残っているが、0.7.11 の create_deep_agent の docstring は既定ツールを「ファイル操作6本・execute・task」とだけ列挙していて、TODO に触れていない。

消えたわけではなく、提供元が移った。0.7.11 のパッケージ内を検索すると write_todos は2か所にしか出てこない。ひとつは NVIDIA Nemotron 向けのハーネスプロファイル、もうひとつは OpenAI Codex 向けのプロファイルで、後者には「Codex のシステムプロンプトが write_todos による TODO 消し込みに言及するため TodoListMiddleware（write_todos ツール）を含める」というコメントが書かれている。ツールの実体は deepagents ではなく langchain 本体の langchain/agents/middleware/todo.py に移っている。

したがって最新版で教材どおりの TODO を使いたいなら、middleware を明示的に渡すことになる。これも実測で確認した。

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(model="claude-sonnet-4-5", middleware=[TodoListMiddleware()])
print(len(agent.nodes["tools"].tools_by_name))   # => 10（write_todos が戻る）

なお pip install "deepagents==0.2.7" としても、同時に入る langchain は 1.3.18 のままだった。deepagents だけを固定しても Nov 2025 のスタックは再現しないので、教材を厳密になぞるなら uv sync で lock ごと解決するほうが確実だ。

deepagents 実測②：既定ツールの常駐コストは何トークンか

エージェントに何を積むかは、そのまま毎ターンの入力トークンに乗る。既定ツールの定義（convert_to_openai_tool で OpenAI 形式へ変換し、json.dumps で1本の文字列にしたもの）を測ったのが下の表だ。トークナイザによって数字が変わるので、両方を併記する。

読み取れることが3つある。

1. 最新版のほうが4割軽い。 ツール数は同じ9本なのに 4,722 → 2,821 トークン（cl100k_base 基準で −40.3%）まで減った。ツール説明文そのものが書き直されて短くなっている
2. write_todos 1本の値段は約980トークン。 0.7.11 に TodoListMiddleware を足すと 2,821 → 3,801 に増える。ツール1本としてはかなり重く、既定から外れた理由の説明にはなっている
3. TODO を戻してもなお 0.2.7 より軽い。 3,801 対 4,722 で約2割減。単に機能が減っただけではない

なお deepagents を実タスクで走らせたときの1タスクあたり実行コストは、TrueForgeとは｜LLMを動かすOSSエージェントハーネスの導入手順・サンドボックス・コスト実測で扱った公式ベンチマークに数字が出ている（Opus 構成で $21.2／タスク）。本記事の値はそれ以前の、毎ターン必ず乗る固定費にあたる。

計測条件は macOS（Darwin 23.5.0・arm64）、Python 3.14、tiktoken の cl100k_base と Anthropic の count_tokens API（モデル claude-sonnet-5）。cl100k_base は OpenAI のトークナイザなので Claude の実トークン数ではなく近似値である点に注意してほしい。実際、この3構成では count_tokens 側が 1.47〜1.49 倍という安定した比率になった。

既定9ツールの内訳——重いのは grep と read_file

合計 2,821 トークンの内訳を1本ずつ数えると、偏りがはっきり出る。

上位3本（grep・read_file・glob）だけで 1,434 トークン、全体の 50.8% を占める。いずれも引数の意味を誤解されると事故る検索・読み取り系で、説明文が長いのは理にかなっている。実際 grep の説明は「パターンは正規表現ではなくリテラルとして一致する。正規表現のメタ文字はただの文字であって演算子ではない」と、真っ先に誤解の芽を潰しにいく書き方になっていた。個別9本の合計は 2,820 トークンで、まとめて JSON 配列にしたときの 2,821 との差1トークンが配列の構造ぶんにあたる。

task ツールが渡しているもの

サブエージェント委譲の入口である task は 392 トークンで、説明文は「複雑な多段タスクを隔離されたコンテキストウィンドウで処理する使い捨てのサブエージェントを起動する」と始まり、続けて利用可能なエージェント種別とそれぞれが使えるツールを列挙する形になっていた。既定では general-purpose の1種類だけが載る。create_deep_agent(subagents=[...]) でサブエージェントを追加すると、この列挙が増えて task の説明文も伸びる——サブエージェントを増やすほど毎ターンの固定費が上がる構造なので、数を増やすときはここも合わせて測るとよい。

LangGraph 直書き・Claude Agent SDK との比較

「deepagents を使うべきか」は、どこまで自分で設計したいかで決まる。

LangGraph そのものの書き方はLangGraph入門｜とは？状態遷移でマルチエージェントを作る基本とLangChainとの違い・比較にまとめてある。deepagents は LangGraph の上に載っているので、この3つは排他ではない。create_deep_agent() で始めて、要らない middleware を外し、必要な middleware を足していけば、そのまま LangGraph 直書きの領域へ地続きに移れる。教材が LangGraph の素の API で書かれているのは、この地続きを体で覚えるためだと考えると腑に落ちる。

Anthropic の Claude Agent SDK と比べる場合は、モデルを固定するかどうかが最初の分岐点になる。deepagents は model="openai:gpt-5.5" のようなプロバイダ指定文字列を受け取り、init_chat_model が対応する範囲のモデルへ差し替えられる。エージェントの設計そのものより、どのモデルに乗せ替える可能性があるかで選ぶほうが失敗しにくい。本番運用まで見据えた設計原則は12-Factor Agents完全解説：本番投入できるLLMエージェント設計12原則を一次ソースで読むが詳しい。

使う前に押さえておきたい注意点

・execute はバックエンド次第で動かない。 0.7.11 の docstring は、execute（シェル実行）が SandboxBackendProtocol を実装したバックエンドでのみ動作し、そうでないバックエンドではエラーメッセージを返すと明記している。既定構成でシェルが使える前提でプロンプトを書くと噛み合わない
・model=None は非推奨になった。 0.5.3 以降、モデル未指定で既定モデルに頼る書き方は deprecated で、deepagents==1.0.0 で削除予定と docstring に書かれている。サンプルコードをそのまま持ってくるときは引数を明示する
・リリース頻度が高い。 PyPI で 123 リリース、最新は本記事執筆の3日前だ。バージョンを固定せずに pip install deepagents と書いた手順書は、数週間で挙動が変わりうる
・教材の最終更新は 2026-08-11。 パッケージ側は本記事執筆当日もコミットがある。教材が追いつく前提で読むと事故るので、ノートブックの記述と手元の版が食い違ったら、まず python ck_vers.py（教材同梱のバージョン確認スクリプト）で足元を確かめるとよい

まとめ

deepagents は「計画・ファイル退避・サブエージェント委譲・作り込んだプロンプト」を1関数にまとめた LangChain 公式の基盤で、deep-agents-from-scratch はその中身を LangGraph で組み直して学ぶ公式教材だ。実測して分かった一番大きな注意点は、教材が固定する 0.2.7 と、今 pip で入る 0.7.11 とで既定ツールが入れ替わっていることだった。教材の第2章の主役 write_todos は最新版の既定にはなく、langchain 側の TodoListMiddleware を渡して復活させる形になっている。

常駐コストの実測（0.7.11 既定で cl100k_base 2,821 トークン／count_tokens 4,137 トークン）も含めて、「何が積まれていて、それがいくらか」を把握したうえで使うと、後からの設計変更が楽になる。

参照ソース

・langchain-ai/deep-agents-from-scratch — 公式教材リポジトリ。star・ノートブック構成・Nov_2025_pkgs の内容はここから実測（2026-08-31 参照）
・langchain-ai/deepagents — パッケージ本体のリポジトリ。star 28,757・MIT（2026-08-31 参照）
・Deep Agents overview — LangChain 公式ドキュメント — LangGraph 本体との住み分けの記述（2026-08-31 参照）
・deepagents — PyPI — リリース履歴。0.2.7 は 2025-11-14、0.7.11 は 2026-08-28 公開（2026-08-31 参照）
・deep-agents-from-scratch / uv.lock — 教材が固定している依存バージョンの一次ソース（2026-08-31 参照）
・langchain/agents/middleware/todo.py — write_todos の現在の提供元（2026-08-31 参照）