DeepAgents アーキテクチャ解析：Planning Tools、Sub-agents、File System

あなたの AI エージェントは、複雑なタスクで常にクラッシュしていませんか？

ある技術トピックを調査させると、20ステップ進んだあたりで出力品質が低下し始めます。コードベースをリファクタリングさせると、半日かけて変更したのに元の機能さえ動かなくなります。長いレポートを書かせると、半分あたりで同じ内容を繰り返し始めます。

私は以前、この落とし穴にハマりました。当時、従来のエージェントを使って深い調査を行い、LangGraph のベストプラクティスを調べてほしいと依頼しました。最初は出力が整理されていましたが、30ステップ以上進むと「記憶喪失」に陥りました。以前調べた資料を忘れ、元の分析フレームワークも崩れ、最終的に矛盾だらけのレポートが完成しました。

これらの問題の根本原因はすべて同じです。従来のエージェントは「浅い（Shallow）」のです。単発の反応的実行しかできず、計画能力も、記憶システムも、サブタスクの分割もありません。まるで、5000文字のレポートを書かせるのにアウトラインも与えず、途中で道を外れるのを見ているようなものです。

しかし、Claude Code、Deep Research、Manus といったエージェントは複雑なタスクを完了できます。数千行のコードプロジェクトのリファクタリング、数十ページにわたる深い調査レポートの作成などです。彼らはどんな手法を使っているのでしょうか？

その答えは、Deep Agent アーキテクチャです。LangChain 公式がこのアーキテクチャを DeepAgents パッケージとしてパッケージ化しました。本日は、その4つの柱を解説します：Planning Tools、Sub-agents、File System、System Prompts です。

なぜ Deep Agents が必要なのか？

まず事実から始めましょう。従来のエージェントは、10ステップを超えるタスクで成功率が半分以上低下します。

これはでたらめではありません。Prompting Guide の研究データによると、タスクのステップ数が10を超えると、Shallow Agent の出力品質が明らかに低下し始めます。なぜでしょうか？「脳」がないからです。

従来のエージェントの設計は反応的です。指示を受け取る → ツールを呼び出す → 結果を返す。各ステップは独立しており、長期的な計画も、中間状態の管理もありません。例えるなら、家全体を掃除させるのに掃除の順序も教えず、どの部屋が終わったかも記録させないようなものです。キッチンを半分掃除してから突然リビングに行き、キッチンがまだ終わっていないことを忘れてしまうかもしれません。

3つの典型的なクラッシュシナリオを見てみましょう。

深い調査タスク。エージェントに「LangGraph の本番環境でのベストプラクティス」のような技術トピックを調査させます。検索を開始し、ドキュメントを読み取り、情報を抽出します。20ステップ後には、以前調べた資料はコンテキストウィンドウから押し出され、新しい検索結果が以前の分析フレームワークを上書きしています。最終的に、脈絡のないレポートが出力されます。

コードリファクタリングタスク。エージェントに数千行のコードを持つプロジェクトをリファクタリングさせます。あるモジュールを変更し、別のモジュールも変更しますが、2つのモジュール間には依存関係があります。それを忘れてしまいます。最後には、元々動いていた機能が全て壊れます。

長いコンテンツ生成。エージェントに5000文字の技術記事を書かせます。2000文字あたりで、前に言ったことを繰り返し始めたり、元のトピックから逸脱し始めたりします。

これらの問題の核心はすべて、コンテキストの制御不能です。

Claude Code は数千行のコードプロジェクトのリファクタリングを処理でき、Deep Research は数十ページの構造化レポートを生成でき、Manus は複雑なマルチステップタスクを完了できます。彼らは魔法ではなく、統一された構造を使用しています。それが Deep Agent アーキテクチャです。

Deep Agent とは、エージェントに「脳」を持たせることです。計画を立て、タスクを分割し、記憶を管理し、進捗を確認できます。LangChain はこのアーキテクチャを DeepAgents としてパッケージ化しました。具体的な設計を見ていきましょう。

DeepAgents の4つの柱となるアーキテクチャ

DeepAgents の設計哲学は明確です。複雑なタスクを管理可能な単位に分割し、各単位に明確な責任を持たせます。

4つの柱が相互に連携します。Planning Tools は計画と進捗追跡を管理し、Sub-agents は専門的な役割分担とコンテキストの分離を実現し、File System は記憶の保存問題を解決し、System Prompts は行動の境界を定義します。これらはオーケストラのようなものです。指揮者（Planning）、異なる楽器グループ（Sub-agents）、楽譜の保存（File System）、演奏ルール（System Prompts）があります。

Planning Tools：エージェントに「脳」を持たせる

Planning Tools の中心は todo_write です。

その動作原理は興味深いもので、本質的には no-op（空操作）です。実際のタスクは何も実行せず、タスクリストの作成と更新のみを行います。しかし、これらのタスクリストはコンテキストウィンドウを通じてワーキングメモリとして機能し、エージェントは実行プロセス全体で自分の計画と進捗を「見る」ことができます。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

例を見てみましょう。エージェントに技術調査をさせます。まず todo_write を使って計画を作成します。

- [ ] LangGraph 公式ドキュメントを検索
- [ ] LangGraph State Machine 設計を読む
- [ ] ベストプラクティス事例を抽出
- [ ] コア設計パターンをまとめる
- [ ] 構造化レポートを出力

各タスクを完了するたび、エージェントはこのリストを更新し、[ ] を [x] に変更します。これにより、何ステップ実行しても、エージェントはいつでも自分の進捗を確認できます。何が完了し、何がまだ始まっておらず、何が進行中か。

これが核心的な問題を解決します。長期目標の一貫性です。

従来のエージェントは第20ステップまで進むと、第1ステップで決めた目標を忘れている可能性があります。しかし、Deep Agent の todo list は冷蔵庫に貼った付箋のように、いつでも「あなたは一体何をしようとしているのか」を思い出させます。

"Claude Code と Manus の planning tool はどちらもこの原理です。コンテキストウィンドウをワーキングメモリとして使い、エージェントが迷子にならないようにします"

Sub-agents：専門的な役割分担とコンテキストの分離

Sub-agents は Deep Agent の2番目の柱です。

その設計ロジックはこうです。1つのメインオーケストレーター（Orchestrator）が全体の計画とタスク割り当てを担当し、複数の専門化されたサブエージェントが具体的なタスクを実行します。各サブエージェントは独立したコンテキストウィンドウを持ち、実行完了後に最終結果のみをオーケストレーターに返します。

これにより4つの重要な利点がもたらされます。

Context Preservation（コンテキストの保持）。オーケストレーターのコンテキストウィンドウはサブエージェントの中間ステップで汚染されません。従来のエージェントが検索タスクを実行すると、すべての検索結果、ウェブページの内容、抽出プロセスをコンテキストに詰め込みます。しかし、Sub-agent は実行完了後、クリーンな結果のみを返します。「これらの重要な情報を見つけました」。オーケストレーターのコンテキストは整理されたままです。

Specialized Expertise（専門的な専門知識）。各サブエージェントは1つの領域に集中できます。research_subagent は情報の検索と抽出に特化し、writer_subagent はコンテンツの整理に特化し、coder_subagent はコード分析に特化します。専門的な役割分担により、各サブエージェントは自分の領域でより良いパフォーマンスを発揮します。

Reusability（再利用性）。同じサブエージェントを複数のオーケストレーターから呼び出せます。例えば、research_subagent は調査タスク、執筆タスク、分析タスクで使用できます。一度書けば、どこでも使えます。

Fine-Grained Permissions（きめ細かな権限管理）。サブエージェントは異なる権限の境界を持てます。あるサブエージェントはファイルの読み取りのみ、あるサブエージェントはファイルの書き込みもでき、あるサブエージェントはネットワークアクセスもできます。きめ細かな権限制御はセキュリティリスクを低減します。

"Orchestrator-Sub-agent アーキテクチャが推奨されます。Task Decomposition Pattern とも呼ばれます。複雑なタスクをサブタスクに分解し、各サブタスクを専門の処理ユニットに渡します"

具体的にどう実装するのでしょうか？DeepAgents はシンプルな API を提供しています。

from deepagents import create_deep_agent, create_subagent

# サブエージェントを定義
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="情報の検索と抽出を専門に担当"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="コンテンツの整理と出力を専門に担当"
)

# メインエージェントを作成
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

オーケストレーターがサブエージェントを呼び出す際、DeepAgents は自動的にコンテキストの切り替えと結果の受け渡しを処理します。

File System：コンテキストウィンドウの制限を突破

これは Deep Agent が記憶問題を解決する核心的なソリューションです。

コンテキストウィンドウにはサイズ制限があります。Claude は約200Kトークン、GPT-4 は約128Kトークンです。短いタスクでは十分です。しかし、長いタスクでは、例えば数千行のコードを処理したり、数十篇のドキュメントを読んだりする場合、このスペースはすぐにいっぱいになります。

File System Backend の解決アプローチは賢いものです。直接読み込みの代わりにファイル参照を使用します。

エージェントはすべてのコンテンツをコンテキストウィンドウに詰め込むのではなく、中間結果をファイルシステムに保存します。あるファイルが必要になった時、read_file ツールで必要に応じて読み取ります。研究をする時に、すべての参考文献を頭の中に入れるのではなく、ドキュメントに整理し、必要な時に開いて確認するようなものです。

DeepAgents は3種類の Backend をサポートしています。

StateBackend。メモリ保存、テスト環境と短期タスクに適しています。エージェントの状態と中間結果はメモリに保存され、セッション終了後に消えます。高速ですが永続的ではありません。

FilesystemBackend。ローカルファイルシステム保存、本番環境と永続化が必要なシナリオに適しています。エージェントの中間結果はローカルファイルに書き込まれ、次回実行時も読み取れます。永続的ですがローカルストレージに依存します。

StoreBackend。クラウドストレージ、エンタープライズレベルのデプロイと監査追跡が必要なシナリオに適しています。エージェントの状態はクラウドデータベースに保存され、バージョン管理と監査ログをサポートします。信頼性が高いですが設定が複雑です。

どの Backend を選ぶかは、あなたのシナリオによります。迅速なテストなら StateBackend を、本番デプロイなら FilesystemBackend を、エンタープライズアプリケーションで監査が必要なら StoreBackend を使用します。

FlowHunt の Context Management Strategy 比較表は、この3つのモードを明確に説明しています。

DeepAgents はデフォルトで Hybrid モードを使用します。重要な情報はコンテキストに保持し、大量のデータはファイルシステムに保存します。

System Prompts：過小評価されている重要要素

System Prompts は4つの柱の中で最も見過ごされがちなものです。

多くの人は System Prompt を単なる短い指示だと思っています。「あなたは役立つアシスタントです」のようなものです。しかし、Deep Agent の System Prompts は実際には数百から数千行のエンジニアリングドキュメントです。

Claude Code の System Prompt は数百行あり、完全なツール呼び出し仕様、ファイル操作フロー、コードスタイルの制約を定義しています。Deep Research の System Prompt は数千行あり、調査方法論、情報抽出仕様、出力フォーマットテンプレートが含まれています。

なぜこれほど詳細な System Prompt が必要なのでしょうか？

エージェントは長いタスクで様々なエッジケースに遭遇するからです。短い指示ではすべてのシナリオをカバーできません。詳細な System Prompt の役割は以下の通りです。

行動の境界を定義。どのような場合に todo_write を呼び出し、どのような場合に sub-agent に委任し、どのような場合に直接結果を返すか。これらのルールは十分に詳細に書かれて初めて、エージェントは正しい判断を下せます。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

ツール呼び出しを規範化。各ツールの使い方、パラメータフォーマット、戻り値の処理方法。例えば、read_file ツールのパラメータはファイルパスかファイル ID か、戻り値は元の内容か要約か。

出力フォーマットを設定。異なるタスクタイプには異なる出力フォーマット要件があります。調査レポートは Markdown 構造、コードリファクタリングは diff フォーマット、コンテンツ生成は特定のテンプレートを使用します。

DeepAgents の Middleware Architecture は System Prompts を自動的に注入します。数千行を手動で書く必要はありません。フレームワークが設定に基づいて自動生成します。しかし、System Prompts の役割を理解することは重要です。それはエージェントの行動の「憲法」です。

4つの柱の解説は以上です。次は実践的なコードを見ていきましょう。

DeepAgents 実践コード解析

完全なコード例を見て、技術調査エージェントを実装します。

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. ツールを定義
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="インターネットを検索して情報を取得"
)

# 2. サブエージェントを定義
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="あなたは情報検索の専門家です。\
                   あなたのタスクは重要な情報を検索し抽出することです。\
                   構造化された調査結果のみを返し、中間ステップは含めないでください。",
    description="情報検索を担当するサブエージェント"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],  # writer は外部ツールを必要としない
    system_prompt="あなたはコンテンツ整理の専門家です。\
                   あなたのタスクは調査結果を整理し、構造化レポートを出力することです。\
                   Markdown フォーマットを使用し、明確な章構造を含めてください。",
    description="コンテンツ出力を担当するサブエージェント"
)

# 3. Deep Agent を作成
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"  # ファイルシステムストレージを使用
)

# 4. タスクを実行
result = agent.invoke(
    "LangGraph のベストプラクティスを調査し、\
     構造化された調査レポートを出力してください"
)

実行フローはこのようになります。

ステップ1：Plan。エージェントは todo_write を呼び出して計画リストを作成します。

todo_write([
    "LangGraph 公式ドキュメントを検索",
    "コアアーキテクチャ設計を読む",
    "ベストプラクティス事例を抽出",
    "設計パターンをまとめる",
    "構造化レポートを出力"
])

ステップ2：Delegate。エージェントは research_subagent を呼び出して検索タスクを実行します。

call_subagent("research", "LangGraph ベストプラクティス関連ドキュメントを検索")

research_subagent は internet_search ツールを呼び出し、検索結果を取得し、重要な情報を抽出し、クリーンな構造化結果をオーケストレーターに返します。オーケストレーターのコンテキストウィンドウには「ここで5つの重要なベストプラクティスが見つかりました」のような要約のみが届きます。すべての検索結果の元の内容ではありません。

ステップ3：Update。エージェントは todo list を更新し、完了状態をマークします。

todo_write([
    "[x] LangGraph 公式ドキュメントを検索",
    "[x] コアアーキテクチャ設計を読む",
    "[ ] ベストプラクティス事例を抽出",
    ...
])

ステップ4：継続実行。エージェントは writer_subagent を呼び出してコンテンツを整理し、write_file で最終レポートを出力します。

call_subagent("writer", "調査結果を整理し、レポートを出力")
write_file("langgraph_best_practices.md", report_content)

実行ログはこのようになります。

[Step 1] todo_write: 5つのタスク項目を作成
[Step 2] call_subagent(research): 情報検索を開始
[Step 3] internet_search: "LangGraph best practices" を検索
[Step 4] read_url: 3つの公式ドキュメントを読む
[Step 5] subagent_complete: research が構造化結果を返す
[Step 6] todo_write: 進捗を更新、2項目完了
[Step 7] call_subagent(writer): コンテンツ整理を開始
[Step 8] subagent_complete: writer が Markdown レポートを返す
[Step 9] write_file: レポートをファイルに出力
[Step 10] todo_write: すべてのタスク完了

全プロセスを通じて、オーケストレーターのコンテキストウィンドウは常にクリーンな状態を維持します。タスクリスト、サブエージェントが返す要約結果のみで、中間ステップのノイズはありません。

これが Deep Agent の威力です。構造化されたプロセス、コンテキスト管理、専門的な役割分担です。

他のエージェントフレームワークとの比較

DeepAgents は唯一の選択肢ではありません。市場には LangGraph、AutoGen、CrewAI、SmolAgents などのフレームワークがあります。それぞれ重点が異なり、適用シナリオも異なります。

比較表で明確にしましょう。

いくつかの重要な違いを見てみましょう。

DeepAgents vs LangGraph。DeepAgents は LangGraph の上位レイヤーのカプセル化で、Deep Agent パターンに特化しています。Planning Tools、File System Backend、Sub-agent Management という汎用機能をカプセル化しているため、自分で構築する必要がありません。LangGraph はより低レベルで、ステートマシンとワークフローオーケストレーション機能を提供し、各ノードとエッジを自由に定義できますが、Memory と Planning は自分で実装する必要があります。

簡単に言うと、Deep Agent を迅速に構築したいなら DeepAgents を、低レベルのカスタマイズをしたいなら LangGraph を使いましょう。

DeepAgents vs AutoGen。AutoGen は Microsoft のフレームワークで、マルチエージェント対話とパイプラインオーケストレーションをサポートしています。その特徴は、エージェント同士が対話し、議論や交渉などの複雑なインタラクションパターンを形成できることです。DeepAgents はタスクの分解と実行に重点を置き、AutoGen はエージェント間のコラボレーションとコミュニケーションに重点を置いています。

簡単に言うと、エージェントチームのコラボレーションや議論・交渉をしたいなら AutoGen を、タスクの分解や専門的な役割分担をしたいなら DeepAgents を使いましょう。

DeepAgents vs CrewAI。CrewAI は「ロールプレイング」を強調しています。各エージェントは異なる役割（リサーチャー、エディター、プログラマー）を持ち、協力してタスクを完了します。DeepAgents の Sub-agent モードと似ていますが、CrewAI はキャラクターの設定とインタラクションをより強調し、DeepAgents はタスクの分解と分離をより強調しています。

簡単に言うと、チームコラボレーションやロールプレイングをシミュレートしたいなら CrewAI を、技術的なタスク分解をしたいなら DeepAgents を使いましょう。

DeepAgents vs SmolAgents。SmolAgents は Hugging Face が提供する軽量フレームワークで、コードファーストが特徴です。エージェントはツールを呼び出すのではなく、Python コードを直接書いてタスクを実行します。迅速なプロトタイピングには適していますが、複雑な長期タスクには適していません。

簡単に言うと、シンプルなエージェントを素早く試したいなら SmolAgents を、複雑な長期タスクをしたいなら DeepAgents を使いましょう。

"フレームワークの選択はシナリオ次第です。DeepAgents は複雑な推論タスクに適し、LangGraph は本番レベルのシステムに適し、AutoGen と CrewAI はマルチエージェントコラボレーションに適し、SmolAgents はアイデアを迅速に検証するのに適しています。万能なフレームワークはなく、適したフレームワークのみがあります"

本番デプロイとベストプラクティス

DeepAgents を本番環境で使用する際、いくつかの重要なポイントに注意が必要です。

Backend 選択戦略

3種類の Backend の選択ロジック：

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

StateBackend：テスト環境、短期タスク。利点は高速です。すべてのデータがメモリにあり、読み書きに IO 遅延がありません。欠点は永続的ではないことです。エージェント再起動後、状態はすべて失われます。ユニットテスト、迅速な検証、短期タスクに適しています。

FilesystemBackend：本番環境、永続化ニーズ。利点は信頼性です。データはファイルシステムに書き込まれ、再起動後も読み取れます。欠点は IO コストです。ファイルの読み書きはメモリより遅いです。本番デプロイ、長期タスク、永続化が必要な場合に適しています。

StoreBackend：エンタープライズレベル、監査追跡が必要。利点は制御可能性です。データはクラウドデータベースに保存され、バージョン管理と監査ログをサポートします。欠点は複雑さです。データベース接続、権限管理の設定が必要です。エンタープライズアプリケーション、コンプライアンス要件、監査ニーズに適しています。

設定例：

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",  # 保存パス
        max_file_size=10 * 1024 * 1024,  # 単一ファイル最大10MB
        cleanup_after_days=30  # 30日後に古いファイルをクリーンアップ
    )
)

サブエージェントの粒度設計

過度に分割しないでください。

ある調査タスクを10個のサブエージェントに分割した人がいました。search_google、search_bing、read_wikipedia、read_github、extract_summary、extract_quotes、format_markdown、check_citations… 結果、オーケストレーターがサブエージェントを呼び出す時間が実際のタスク実行時間より長くなりました。

合理的な設計は3〜5個のコアサブエージェントです：

• research：すべての情報検索と抽出を担当
• analysis：データ処理と論理推論を担当
• writer：コンテンツの整理と出力を担当
• reviewer：品質チェックと検証を担当（オプション）

各サブエージェントには明確な責任境界があります。research サブエージェントはコンテンツの整理をすべきではなく、writer サブエージェントは情報検索をすべきではありません。責任が明確で、呼び出しがクリアです。

パフォーマンス最適化

2つの重要なポイント：

ファイルの必要時読み込み。中間結果をすべて一度に read_file しないでください。エージェントは実行プロセス中、現在のタスクのニーズに応じて関連ファイルを読み取ります。DeepAgents のファイル参照メカニズムはこのために設計されています。ファイルパスはコンテキストに保存され、内容は必要な時にのみロードされます。

Context Summarization の適切な使用。長期タスクの実行中、コンテキストウィンドウには多くのコンテンツが蓄積される可能性があります。DeepAgents は中間ステップの自動要約をサポートしています。冗長な実行記録を簡潔な状態記述に圧縮します。これはコンテキストスペースを節約しますが、要約の正確性に注意が必要です。重要な情報を失ってはいけません。

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,  # 50Kトークンで要約をトリガー
        "preserve_last_n_steps": 5  # 直近5ステップの詳細記録を保持
    }
)

エラー処理と検証

Deep Agent の実行プロセスは長く、エラーの確率も高いです。エラー処理メカニズムが必要です：

LLM-as-a-Judge。別の LLM を使ってエージェントの出力品質をチェックします。例えば、reviewer_subagent が writer_subagent の出力したレポートに論理的な穴や情報の欠落がないかをチェックします。

人間の介入ポイント。重要な決定ポイントで人間の確認を設定します。例えば、エージェントが調査を完了した後、方向が正しいかをユーザーの確認を待ってから継続実行します。

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,  # 自動検証を有効化
        "human_checkpoint": "before_output"  # 出力前に人間の確認
    }
)

まとめ

DeepAgents の4つの柱を振り返りましょう：

Planning Tools はエージェントに計画能力を持たせ、todo_write はコンテキストウィンドウをワーキングメモリとして使い、長期目標の一貫性を維持します。

Sub-agents は専門的な役割分担とコンテキストの分離を実現し、オーケストレーターのコンテキストはクリーンなままで、サブエージェントの中間ステップはメインプロセスを汚染しません。

File System はコンテキストウィンドウの制限を解決し、直接読み込みの代わりにファイル参照を使用し、必要時読み込みでスペースを節約します。

System Prompts はエージェントの行動の境界を定義し、数百から数千行のエンジニアリングドキュメントが様々なエッジケースをカバーします。

この4つの柱が連携して、エージェントを「反応的実行」から「構造化推論」へと進化させます。Claude Code、Deep Research、Manus の成功は、このアーキテクチャの有効性を証明しています。

次のステップのアクションプラン：

• DeepAgents を使って最初の長期タスクエージェントを構築してみてください。公式 GitHub リポジトリに完全なサンプルコードがあります：langchain-ai/deepagents。
• LangChain 公式ドキュメントで詳しく学んでください。DeepAgents のドキュメントは docs.langchain.com/oss/python/deepagents にあります。
• AI 開発実践シリーズに注目してください。LangGraph ステートマシン設計、エージェントメモリシステムの最適化など、今後さらにエージェントアーキテクチャの深い分析を提供します。

10 min read · 公開日: 2026年4月26日 · 更新日: 2026年4月29日

Easton

AI・インテリジェンス