Updated: 2026年2月16日 14 分で読めます

LangChain DeepAgent実践ガイド: 単発LLMから継続実行エージェントへ

LangChainのDeepAgentを題材に、アーキテクチャ、状態管理、ツール実行、評価設計、運用までを長文で整理した実践ノート。

#langchain #deepagent #agent #llm #python

はじめに

LLMアプリケーションをしばらく作っていると、次の壁に必ず当たります。

  • プロンプト1回で完結するタスクは強いが、複数ステップになると壊れやすい
  • 外部APIやDB、ファイル操作を絡めると、再現性とデバッグ性が一気に落ちる
  • 会話の文脈が長くなるほど、意図しない振る舞いが増える

この壁を越えるための選択肢として、LangChainのエージェント設計は現実的です。 特に「DeepAgent」という考え方は、単発の推論ではなく、状態を保持しながら複数回の思考とツール実行を重ねる実装に向いています。

この記事では、LangChainベースでDeepAgent的なシステムを作るときの実践ポイントを、設計から運用まで一気通貫で整理します。単なる概念紹介ではなく、次の1週間でプロダクションに近づけるための判断材料を置くことが目的です。

DeepAgentをどう定義するか

まず、ここで扱うDeepAgentを明確にします。

DeepAgentとは、以下を満たすエージェント実装です。

  1. 長いタスクを小さなサブタスクに分解できる
  2. サブタスクごとの結果を状態として蓄積できる
  3. 蓄積した状態を使って次のアクションを再計画できる
  4. ツール失敗時に自己修復的なリトライ戦略を持つ
  5. 最終出力だけでなく、意思決定の履歴を観測できる

ポイントは「賢い回答を1回で出す」ことより、壊れにくい実行ループを作ることです。

単発チャットボットの評価軸は回答品質に寄りがちですが、DeepAgentでは次の運用指標が同じくらい重要になります。

  • タスク完了率
  • 平均ステップ数
  • ツール呼び出し成功率
  • リトライ後の回復率
  • タイムアウト率

この指標を計測しないまま改善を続けると、体感品質だけ上がって実運用は不安定なままになります。

なぜLangChainなのか

LangChainは万能ではありませんが、DeepAgent実装に必要な「接着面」が広いのが強みです。

  • モデル抽象化
  • ツール定義
  • プロンプトテンプレート
  • メモリ/状態表現
  • 実行フローの構成（LangGraph含む）
  • コールバック/トレース連携

特に、状態機械の観点でエージェントを組めるのは大きいです。 「思考 → ツール実行 → 状態更新 → 再計画」のループを、曖昧な再帰ではなく明示的なグラフとして実装できます。

また、チーム開発では「誰が見ても同じ実行経路を追える」ことが重要です。暗黙的なプロンプト職人芸ではなく、ノードとエッジで振る舞いを説明できるだけで保守性が上がります。

最小アーキテクチャ

DeepAgentを最初から大きく作る必要はありません。以下の4層で始めるのが安全です。

  1. Planner: ユーザー要求をサブタスクへ分解する
  2. Executor: サブタスクを実行し、必要ならツールを呼ぶ
  3. State Store: 中間成果物と実行ログを保持する
  4. Critic: 進捗と品質を評価し、再計画の有無を決める

この構成は、実装時に次の責務分離を作ります。

  • 「何をするか」と「どうやるか」を分離
  • 失敗の局所化（どこで壊れたかが追える）
  • 将来的な差し替え容易性（モデル/ツール/評価器）

最初のMVPでは、Criticを単純なルールベースにして構いません。 例えば「必須フィールド欠損」「API 429」「出力フォーマット不一致」を検知したら再試行するだけでも、体感の信頼性は大きく上がります。

状態設計: DeepAgentの心臓部

DeepAgentが浅い実装で終わる最大要因は、状態を雑に扱うことです。 次の3種類を分けて保存してください。

  • Task State: タスク分解結果、各ステップの完了フラグ
  • Working Memory: 一時的な推論メモ、観測値、ツール出力サマリ
  • Audit Log: 入出力、ツール呼び出し、エラー、リトライ履歴

この分離がないと、会話履歴が肥大化し、推論コストとノイズが増えます。 「全部を会話コンテキストに積む」設計は短期では楽ですが、長期運用で確実に破綻します。

運用目線では、State Storeに以下のメタ情報を必ず持たせるのが実務的です。

  • run_id（1回の実行を一意に追跡）
  • step_id（どの段階での出来事か）
  • tool_call_id（外部連携単位の識別子）
  • retry_count（何回目の試行か）
  • latency_ms（処理時間）

この情報があるだけで、障害解析とコスト最適化の難易度が大きく下がります。

ツール設計の原則

DeepAgentの品質はモデル性能より、ツール境界の設計で決まる場面が多いです。

原則1: ツールの責務を狭くする

1ツール1責務に寄せます。例えば「顧客検索」「契約取得」「請求更新」を1つの巨大ツールにまとめると、失敗時の切り分けができません。

原則2: 入出力を厳密に型定義する

曖昧な自由入力は事故の原因です。Pydantic等でスキーマを固定し、必須項目不足を早期に弾きます。

原則3: 副作用ツールにガードを入れる

更新系のツール（送信、削除、課金）は、

  • dry-run
  • confirmationトークン
  • idempotency key

を基本セットにします。これだけで「うっかり実行」の被害を大幅に減らせます。

原則4: ツール結果は生データと要約の両方を持つ

モデルに返すのは要約中心でよいですが、監査用に生レスポンスも保存します。障害時に「なぜその判断をしたか」を説明できるようにするためです。

失敗前提の実行ループ

DeepAgentは失敗しないことを目指すのではなく、失敗しても回復できることを目指します。

実装上は、次の分岐を明示してください。

  1. Replan: 計画自体を作り直す
  2. Retry: 同じ計画で再試行する
  3. Fallback: 精度を落としてでも完了優先で進める
  4. Escalate: 人間へハンドオフする

例えば外部APIが一時障害ならRetry、仕様矛盾ならReplan、権限エラーならEscalateが妥当です。 この判断を全部モデル任せにすると、場当たり的になります。最低限のルールをコードで固定してください。

評価設計: まず「壊れ方」を測る

多くのチームは「最終回答の自然さ」だけを見ますが、DeepAgentでは評価軸を増やす必要があります。

  • 成功率: 目標状態に到達した割合
  • 回復率: 失敗後に完了へ戻れた割合
  • 過剰実行率: 不要なツール呼び出し回数
  • 安全性違反率: 禁止操作/漏洩リスクの発生率
  • 一貫性: 同一入力での結果ブレ

おすすめは、オンライン評価の前にオフライン評価セットを作ることです。 「正常系20件」「境界系20件」「障害系20件」から始めるだけでも、改善速度が上がります。

プロンプト戦略

DeepAgentでプロンプトを設計するときは、1枚の巨大システムプロンプトに詰め込まないほうが安定します。

実務では、次のような分割が扱いやすいです。

  • Planner Prompt: 分解戦略と完了条件
  • Executor Prompt: ツール選択基準と出力形式
  • Critic Prompt: 品質判定と次アクション選択

それぞれに「禁止事項」を短く明記し、共通ポリシー（安全・個人情報・権限境界）は別ファイルで注入します。

加えて、プロンプトには次を含めてください。

  • 現在の状態要約
  • 直近の失敗理由
  • 残りステップ
  • 制約（時間、トークン、コスト）

これにより、モデルが毎回ゼロから推論する無駄を減らせます。

運用設計: 本番で困るポイント

DeepAgentはローカルで動いた時点では完成ではありません。 本番運用で必須になるのは、次の3点です。

1. 観測性

  • 実行トレース
  • ツール単位のレイテンシ
  • 失敗理由の分類
  • モデル別コスト

これらをダッシュボード化しないと、改善が勘に戻ります。

2. リリース戦略

  • カナリアリリース
  • モデル切替フラグ
  • 失敗時の即時ロールバック

エージェントは非決定的要素があるため、段階リリースが必須です。

3. セーフティ

  • 権限最小化
  • PIIマスキング
  • 監査ログ保持期間
  • 操作証跡の改ざん耐性

「便利な自動化」は、裏返すと事故の拡大装置になり得ます。 開発速度より先に、境界条件を決めることが重要です。

実装ロードマップ（4週間の現実案）

Week 1: 最小ループ

  • Planner / Executor / State Store を最小実装
  • 読み取り専用ツールのみ接続
  • 成功率と失敗率の計測を開始

Week 2: 回復力

  • Critic導入
  • Retry/Replan/Fallback 分岐実装
  • 障害系テストケース追加

Week 3: 安全性

  • 更新系ツールにガード導入
  • 監査ログの整備
  • Escalate（人間ハンドオフ）実装

Week 4: 運用最適化

  • レイテンシ/コストの最適化
  • モデル切替A/B
  • ダッシュボードの閾値運用

この順序を守る理由は、精度改善より先に「事故らない土台」を作るためです。

よくある失敗パターン

最後に、DeepAgent導入でよく見た失敗をまとめます。

  1. いきなり本番APIで更新系操作を許可する
  2. 状態保存を会話履歴だけに依存する
  3. 失敗時の分岐をモデルに丸投げする
  4. 評価を人間レビューだけで済ませる
  5. 実行コストの監視を後回しにする

どれも短期では速く見えますが、中長期で必ず負債になります。

まとめ

LangChainでDeepAgentを作る本質は、「高度な推論」そのものより、継続実行の設計にあります。

  • 状態をどう表現し
  • 失敗からどう回復し
  • 何を指標に改善し
  • どの境界で人間に戻すか

この4点を明確にできれば、エージェントはデモからプロダクションへ進めます。

逆に言えば、ここを曖昧にしたままモデルだけ入れ替えても、安定性は上がりません。

LangChainはその設計を支える実装基盤として十分有力です。 まずは小さく、観測可能に、そして失敗前提で作る。 それがDeepAgentを現場で機能させる最短ルートです。