deepagents-architecture

Deep Agentsのアーキテクチャ上の判断

Deep Agentsを使用する場面

次のような要件がある場合はDeep Agentsを使用します。

• 長期間にわたるタスク - 数十回のツール呼び出しに及ぶ複雑なワークフロー
• 計画機能 - 実行前のタスク分解
• ファイルシステム操作 - ファイルの読み取り、書き込み、編集
• サブエージェントへの委任 - 個別のコンテキストウィンドウを使った分離されたタスク実行
• 永続メモリ - 会話をまたいだ長期保存
• Human-in-the-loop - 機密性の高い操作に対する承認ゲート
• コンテキスト管理 - 長い会話の自動要約

次のような場合は、代替手段を検討してください。

シナリオ	代替手段	理由
LLMの単一呼び出し	直接API呼び出し	Deep Agentsのオーバーヘッドに見合う効果がありません
シンプルなRAGパイプライン	LangChain LCEL	抽象化がよりシンプルです
カスタムのグラフ制御フロー	LangGraphを直接使用	柔軟性が高まります
ファイル操作が不要	create_react_agent	より軽量です
ステートレスなツール使用	Function calling	ミドルウェアが不要です

バックエンドの選択

バックエンドの比較

バックエンド	永続性	用途	必要なもの
StateBackend	一時的（スレッド単位）	作業ファイル、一時データ	なし（デフォルト）
FilesystemBackend	ディスク	ローカル開発、実ファイル	root_dirパス
StoreBackend	スレッド間	ユーザー設定、ナレッジベース	LangGraphのstore
CompositeBackend	混在	ハイブリッドメモリのパターン	複数のバックエンド

バックエンドの決定フロー

Need real disk access?
├─ Yes → FilesystemBackend(root_dir="/path")
└─ No
   └─ Need persistence across conversations?
      ├─ Yes → Need mixed ephemeral + persistent?
      │  ├─ Yes → CompositeBackend
      │  └─ No → StoreBackend
      └─ No → StateBackend (default)

CompositeBackendによるルーティング

異なるパスを異なるストレージバックエンドにルーティングします。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Working files (ephemeral)
        routes={
            "/memories/": StoreBackend(store=store),    # Persistent
            "/preferences/": StoreBackend(store=store), # Persistent
        },
    ),
)

サブエージェントのアーキテクチャ

サブエージェントを使用する場面

次のような場合はサブエージェントを使用します。

• タスクが複雑で複数のステップがあり、独立して実行できる
• メインスレッドのコンテキストを肥大化させるほど、大量のコンテキストが必要
• 複数の独立したタスクを並列実行できる
• 分離された実行（サンドボックス化）が必要
• 中間ステップではなく最終結果だけが必要

次のような場合はサブエージェントを使用しないでください。

• タスクが単純（ツール呼び出しが少ない）
• 中間推論を確認する必要がある
• 分割してもメリットがなく、遅延だけが増える
• タスクの実行中にメインスレッドの状態に依存する

サブエージェントのパターン

パターン1：並列調査

         ┌─────────────┐
         │  Orchestrator│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Task A│  │Task B│  │Task C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  Synthesize │
      └─────────────┘

適しています：複数のトピックの調査、並列分析、バッチ処理。

パターン2：特化型エージェント

research_agent = {
    "name": "researcher",
    "description": "Deep research on complex topics",
    "system_prompt": "You are an expert researcher...",
    "tools": [web_search, document_reader],
}

coder_agent = {
    "name": "coder",
    "description": "Write and review code",
    "system_prompt": "You are an expert programmer...",
    "tools": [code_executor, linter],
}

agent = create_deep_agent(subagents=[research_agent, coder_agent])

適しています：分野固有の専門知識、タスクの種類ごとに異なるツールセットが必要な場合。

パターン3：コンパイル済みサブエージェント

from deepagents import CompiledSubAgent, create_deep_agent

# Use existing LangGraph graph as subagent
custom_graph = create_react_agent(model=..., tools=...)

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom-workflow",
        description="Runs specialized workflow",
        runnable=custom_graph
    )]
)

適しています：既存のLangGraphグラフの再利用、複雑なカスタムワークフロー。

ミドルウェアのアーキテクチャ

組み込みミドルウェアスタック

Deep Agentsは次の順序でミドルウェアを適用します。

1. TodoListMiddleware - write_todos/read_todosによるタスク計画
2. FilesystemMiddleware - ファイル操作：ls、read_file、write_file、edit_file、glob、grep、execute
3. SubAgentMiddleware - taskツールによる委任
4. SummarizationMiddleware - コンテキストが約85%または170kトークンに達した時点で自動要約
5. AnthropicPromptCachingMiddleware - システムプロンプトをキャッシュ（Anthropicのみ）
6. PatchToolCallsMiddleware - 中断によって残された未完了のツール呼び出しを修正
7. HumanInTheLoopMiddleware - 承認のため一時停止（interrupt_onが設定されている場合）

カスタムミドルウェアの配置

from langchain.agents.middleware import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    tools = [my_custom_tool]

    def transform_request(self, request):
        # Modify system prompt, inject context
        return request

    def transform_response(self, response):
        # Post-process, log, filter
        return response

# Custom middleware added AFTER built-in stack
agent = create_deep_agent(middleware=[MyMiddleware()])

ミドルウェアとツールのどちらを選ぶか

要件	ミドルウェアを使用	ツールを使用
システムプロンプトの内容を挿入する	✅	❌
ツールを動的に追加する	✅	❌
リクエスト／レスポンスを変換する	✅	❌
単独で利用できる機能	❌	✅
ユーザーが呼び出せるアクション	❌	✅

サブエージェントのミドルウェア継承

デフォルトでは、サブエージェントは独自のミドルウェアスタックを受け取ります。

• TodoListMiddleware
• FilesystemMiddleware（バックエンドを共有）
• SummarizationMiddleware
• AnthropicPromptCachingMiddleware
• PatchToolCallsMiddleware

SubAgentMiddlewareのdefault_middleware=[]または、サブエージェントごとのmiddlewareキーで上書きします。

ゲート：実装前のアーキテクチャ上の決定

順番どおりに完了してください。明記された成果物が設計ノート、ADR のひな形、またはチケットに存在する場合にのみ、そのステップは合格です。内部的な意図だけでは不十分です。

1. 適合性 - Deep Agents と代替案を確認します（上の表を参照）。

   • 合格条件：「Deep Agents が必要な場合」の箇条書きのいずれか、または「代替案を検討」の行と選択した代替案のいずれかを明示した、簡潔な文書による根拠があること。

2. バックエンド - バックエンドの判断ツリーに基づき、具体的な選択肢を決定します。

   • 合格条件：「バックエンドの比較」表にあるバックエンド名が記載されていること。FilesystemBackend または CompositeBackend を使用する場合は、root_dir とルートプレフィックスを記載していること（パスのプレースホルダーでも可）。

3. サブエージェント - 委譲する範囲を決定します。

   • 合格条件：「サブエージェントなし」とその理由を説明する一文、または「サブエージェントを使用する場合」の理由のうち少なくとも 1 つに対応する、名前付きのリストがあること。並列処理の計画では、出力を何が統合するかを明記すること。

4. Human-in-the-loop - 承認の仕組みを決定します。

   • 合格条件：interrupt_on を使用するツール／操作の明示的なリスト、または「HITL なし」と、リスクを受け入れる旨の一文があること。

5. ミドルウェア - カスタムか組み込みかのみを決定します。

   • 合格条件：「カスタムミドルウェア：なし」、または各カスタム要素の名前、組み込みスタックの後に配置すること、プロンプトインジェクション、ツール、またはリクエスト／レスポンスの変換との関連が明記されていること。

6. コンテキスト - 長いスレッドと大きな入力への対応を決定します。

   • **合格条件：**デフォルトの要約動作（コンテキスト約 85%／約 170k トークン）に関する計画、または代替の上限が記載されていること。大きなファイルは、参照／チャンク化、または同等の方法で処理することを文書に明記すること。

7. チェックポイント - 再開と耐久性への対応を決定します。

   • **合格条件：**グラフのチェックポイント／チェックポインター方式が明記されていること、または「なし」とその理由を説明する一文（例：一時的なデモのみ）があること。