便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

電池込みのAIエージェントハーネス「Deep Agents」— LangGraph上で動くオープンソース実行基盤

タグ Deep AgentsLangGraphAIエージェントオープンソースLangChainマルチエージェントLangSmithPythoncolumnコラムlinuxLinuxwindowsWindowsGitHublangchain-aideepagents
📦 GitHubで見る

電池込みのAIエージェントハーネス「Deep Agents」— LangGraph上で動くオープンソース実行基盤

ひとことでいうと

Deep Agents は、AIエージェント（自律的にタスクをこなすプログラム）を動かすための「実行基盤」です。ファイルの読み書き・シェル操作・サブエージェントへの委譲・永続メモリなど、複数ステップの作業を自律的にこなすために必要な機能がすべてひとまとめになっています。OpenAI・Anthropic・Google といった有名なAIサービスから、自分のパソコン上で動かすローカルモデルまで、幅広い組み合わせで使えます。ひとことで言えば「エージェントを作るための、すぐ使える土台」です。開発者からプロダクション運用チームまで、AIエージェントをゼロから組み立てる手間を大幅に省いてくれます。

こんな人におすすめ

1. リサーチやドキュメント作成を自動化したい開発者 Web検索・ファイル書き込み・要約といった複数の作業を組み合わせた「長期タスク」を、数行のコードで構築できます。調査・執筆・校正をそれぞれ別のサブエージェントに分担させるような並列処理も、ハーネスの仕組みを使えば自然に実現できます。

2. モデルを頻繁に切り替えるAIエンジニア モデルの指定は model="openai:gpt-5.5" のような文字列ひとつで完結します。Anthropic・Google・Fireworks・Baseten・ローカルのOllamaなど、任意のLangChainチャットモデルへの差し替えが可能です。プロンプトやツールのロジックをほぼ変えずにモデルを比較できるので、実験サイクルが格段に速くなります。

3. AIエージェントを本番環境にデプロイしたいチーム LangGraph（後述）のストリーミング・永続化・チェックポイント機能がそのまま使えるため、障害からの復旧・途中再開・状態管理を別途実装する必要がありません。LangSmith（トレース・モニタリングツール）との統合も標準で備わっており、本番運用に必要な監視まわりも整っています。

インストール・使い方

Step 1: パッケージをインストールする

ターミナル（文字で命令を送る画面）を開いて、次のコマンドをコピー＆ペーストして実行します。

推奨: uv（高速Pythonパッケージ管理ツール）を使う場合

uv add deepagents

uv はインストールが速く、依存関係の管理も自動で行ってくれます。

従来の pip を使う場合

pip install deepagents

どちらの方法でも、deepagents ライブラリが手元の環境に追加されます。動作確認済みのPythonバージョンは 3.12 です。Python 3.10 以上の環境を推奨します。事前に python --version コマンドでバージョンを確認しておくと安心です。

Step 2: 基本的なエージェントを起動する

インストールが終わったら、次のコードを .py ファイルに保存して実行します。create_deep_agent という関数ひとつで、計画立案・ファイル操作・コンテキスト管理を備えたエージェントが起動します。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",        # 使いたいモデルをここで指定
    tools=[my_custom_tool],         # 自作ツールを渡せる（不要なら [] でよい）
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})

model にはLangChain形式の識別子（たとえば "anthropic:claude-opus-4-6" など）を渡します。tools に独自の関数を渡すだけでカスタムエージェントの完成です。invoke を呼ぶと、エージェントが自律的にステップを実行して結果を返してきます。

Step 3: サブエージェントを接続する（応用）

LangGraph の CompiledStateGraph（グラフとして組まれた処理フロー）をサブエージェントとして渡すことができます。既存のLangGraphコードをそのまま組み込めるので、過去の資産を壊さずに移行・統合できます。複雑なワークフローを「メインエージェント→サブエージェントへ委譲」という形で整理できるのが大きなメリットです。

動かしてみた

実行環境では Python 3.12.13 が正常に認識され、パッケージのインストールも問題なく完了しました。

=== python ===
Python 3.12.13

リポジトリの構造も確認できました。libs/（ライブラリ本体）、examples/（サンプルコード集）、.mcp.json（MCPサーバーの設定ファイル）、AGENTS.md（エージェント定義）が含まれています。action.yml が存在することから、GitHub Actions（自動テスト・デプロイの仕組み）との統合も公式にサポートされています。.pre-commit-config.yaml も同梱されており、コードの品質管理が整備されたリポジトリであることが確認できました。パッケージは PyPI（Pythonのパッケージ公開サービス）に deepagents という名前で公開されており、MITライセンスのもとで誰でも自由に利用・改変できます。

ブラウザで試す

ブラウザ上のデモでは、create_deep_agent に渡す設定パラメータ（モデル名・システムプロンプト・ツール一覧）を入力フォームで組み合わせると、そのまま実行できるPythonスターターコードが生成されます。実際のLLM呼び出しにはローカルのAPIキーが必要ですが、コード生成の部分はブラウザ上だけで試せます。どんな設定が必要かを手を動かしながら確認するのに便利です。

はじめの一歩：すぐ試すためのコツ

初めて動かすときは、次のチェックリストを上から順番に確認していくとスムーズです。

  • Pythonのバージョン確認: python --version を実行して 3.10 以上であることを確かめる。3.9 以下の場合はアップグレードが必要です。
  • APIキーの設定: 使用するモデルプロバイダーの環境変数（例: OPENAI_API_KEY）をターミナルに設定しておく。.env ファイルに書いておくと毎回設定しなくて済みます。
  • 最小スクリプトから始める: tools=[]（空のリスト）・シンプルなシステムプロンプトで動作を確認してから、カスタムツールを追加していくのがおすすめです。
  • LangSmith連携は後回しでよい: 最初は LANGSMITH_API_KEY なしでも動きます。トレース（実行ログの可視化）が必要になったタイミングで LANGSMITH_API_KEY と LANGSMITH_TRACING=true を追加すれば、自動的にログが収集されます。
  • examples/ フォルダを参考にする: リポジトリ内のサンプルコードは、実際の使い方を最短で把握するのに役立ちます。まず動くサンプルをコピーして、少しずつ自分の用途に書き換えるのが近道です。
  • Human-in-the-loopは段階的に導入する: 最初は自動実行だけで試して、「このツール呼び出しは人間が確認したい」という箇所が出てきたタイミングで承認ステップを追加するとよいです。

活用例

  • コードレビューの自動化: ファイルシステムツールでリポジトリを読み込み、コードの問題点をレポートとして書き出します。Human-in-the-loopを使えば「この変更を適用してよいか」という確認ステップを挟むことも可能です。
  • 調査レポートの自動生成: MCPを経由してWeb検索ツールを接続し、特定テーマの情報収集→要約→Markdown出力を自律実行します。分野別の調査をサブエージェントに並列委譲することで処理を高速化できます。
  • 長時間バッチ処理のオーケストレーション: LangGraphのチェックポイント機能を活用し、途中でプロセスが終了しても前回の状態から再開できるパイプラインを構築できます。データ変換・ファイル生成・外部API呼び出しを組み合わせた複雑なワークフローに適しています。
  • ローカルLLMでのプライベート処理: OllamaやvLLMと組み合わせることで、外部サービスにデータを送らずに社内文書の分析・要約・検索が行えます。モデルを変更してもツールやプロンプトの再実装が不要なため、コストと手間を抑えられます。
  • マルチエージェント型ワークフローの実験: メインエージェントが全体を統括し、専門化されたサブエージェントが各タスクを担当する「階層型エージェント」の構成を、既存のLangGraphコードを活かしながら試せます。
  • AIエージェントの評価・改善サイクル: LangSmithのトレース機能と組み合わせることで、エージェントの各ステップの挙動を記録・可視化し、プロンプトやツールの改善を継続的に行えます。

用語とポイント解説

エージェントハーネス AIエージェントが動くための実行基盤全体を指します。かんたんに言うと「エージェントが自律的に動き続けるための骨組み」です。ループ処理・ツール管理・状態管理をひとまとめにしたフレームワークで、開発者がゼロから組み立てる手間を省いてくれます。Deep Agents はこのハーネスにあたります。

LangGraph LangChainが提供するグラフ実行ランタイム（処理フローをグラフ構造で動かす仕組み）です。かんたんに言うと「ノード（処理の単位）とエッジ（つながり）で処理の流れを定義できるエンジン」です。ストリーミング（逐次出力）・永続化・チェックポイントといった本番運用に必要な機能が標準で備わっています。Deep Agents はLangGraphの上に構築されています。

サブエージェント メインエージェントからタスクを委譲される子エージェントのことです。かんたんに言うと「親エージェントに指示された仕事を、独自のコンテキストで担当するエージェント」です。独立したコンテキストウィンドウ（会話の記憶容量）を持つため、長大なタスクを分割して並列処理するのに適しています。

Human-in-the-loop（ヒューマン・イン・ザ・ループ） ツールを呼び出す前に人間の承認ステップを挟むフローのことです。かんたんに言うと「AIが行動する前に人間が『OK』か『やめておく』を判断できる仕組み」です。完全自動化と人間の監視を両立させたい場面で特に効果を発揮します。誤操作のリスクが高いファイル削除や外部API呼び出しに適用するのが定番の使い方です。

MCP（Model Context Protocol） LLMとツール群を標準化されたインターフェースで接続するプロトコル（通信の規約）です。かんたんに言うと「AIとさまざまなツールをつなぐ共通の規格」です。.mcp.json という設定ファイルで接続するツールを管理します。Web検索・データベース・社内システムなど多様なツールをLLMに簡単につなげられます。

LangSmith LangChainが提供するLLMアプリケーション向けのトレース・評価・モニタリングプラットフォームです。かんたんに言うと「エージェントの動きを記録・可視化して改善に役立てるサービス」です。LANGSMITH_API_KEY と LANGSMITH_TRACING=true を設定するだけで、エージェントの各ステップの入出力が自動的に記録されます。

batteries-included（バッテリーズ・インクルーデッド） 「電池込み」という意味の慣用表現です。かんたんに言うと「すぐに動かせる状態で全部そろっている」ということを指します。Pythonの設計思想としても知られており、必要な機能を追加インストールなしで使えることをほめる言い方として使われます。Deep Agents はまさにこの設計方針を採用しています。

チェックポイント 処理の途中経過をセーブしておく仕組みのことです。かんたんに言うと「ゲームのセーブデータのように、途中の状態を記録しておく機能」です。長時間かかる処理が途中で止まっても、チェックポイントから再開できるため、全部やり直す必要がなくなります。LangGraphが提供するこの機能がそのまま Deep Agents でも利用できます。

コンテキストウィンドウ LLMが一度に扱える会話や情報の量の上限のことです。かんたんに言うと「AIの短期記憶の容量」です。長い会話や大量のファイルを扱う場合は、この上限に達しないようにコンテキストを管理する工夫が必要になります。Deep Agents はコンテキスト管理の機能も標準で備えています。

ぜひコードレビューの自動化や調査レポートの生成、ローカルLLMを使ったプライベートな社内文書処理などに活用してみてはいかがでしょうか。