ディープエージェントとmilvusを使った生産準備の整ったAIエージェントの構築方法

より多くのチームがAIエージェントを構築しており、彼らに割り当てるタスクはより複雑になっている。実世界のワークフローの多くは、複数のステップと多くのツールコールを伴う長時間ジョブを含んでいる。このようなタスクが増えるにつれて、トークンのコスト上昇とモデルのコンテキストウィンドウの限界という2つの問題がすぐに現れます。エージェントはまた、過去の研究結果やユーザーの好み、以前の会話など、セッションをまたいで情報を記憶する必要があることも多い。

LangChainがリリースしたDeep Agentsのようなフレームワークは、これらのワークフローを整理するのに役立つ。タスクプランニング、ファイルアクセス、サブエージェントの委譲をサポートし、構造化されたエージェントの実行方法を提供する。これにより、長いマルチステップのタスクをより確実に処理できるエージェントの構築が容易になる。

しかし、ワークフローだけでは十分ではありません。エージェントは、以前のセッションから有用な情報を取り出すことができるように、長期記憶も必要とする。そこで、オープンソースのベクトルデータベースであるMilvusの出番となる。Milvusは、会話、ドキュメント、ツールの結果を埋め込んで保存することで、エージェントが過去の知識を検索して呼び出すことを可能にします。

この記事では、Deep Agentsの仕組みを説明し、Milvusと組み合わせて、構造化されたワークフローと長期記憶を持つAIエージェントを構築する方法を紹介する。

Deep Agentsとは？

Deep AgentsはLangChainチームによって構築されたオープンソースのエージェントフレームワークです。このフレームワークは、エージェントが長期にわたるマルチステップタスクをより確実に処理できるように設計されています。3つの主要な機能に焦点を当てています：

1.タスクプランニング

Deep Agents にはwrite_todos やread_todos のようなビルトインツールが含まれています。エージェントは、複雑なタスクを明確な ToDo リストに分割し、各項目をステップごとに処理し、完了したタスクに印を付けます。

2.ファイルシステムへのアクセス

ls 、read_file 、write_file のようなツールを提供し、エージェントはファイルの表示、読み込み、書き込みができる。ツールが大きな出力を生成する場合、その結果はモデルのコンテキスト・ウィンドウに留まるのではなく、自動的にファイルに保存されます。これは、コンテキスト・ウィンドウがいっぱいになるのを防ぐのに役立ちます。

3.サブエージェントの委任

task ツールを使って、メインエージェントはサブタスクを専門のサブエージェントに委譲することができます。各サブエージェントは、独自のコンテキストウィンドウとツールを持ち、作業の整理整頓に役立ちます。

技術的には、create_deep_agent で作成されたエージェントは、コンパイルされたLangGraph StateGraph です。(LangGraphはLangChainチームによって開発されたワークフローライブラリであり、StateGraphはその中核となる状態構造である)。このため、ディープエージェントは、ストリーミング出力、チェックポイント、ヒューマン・イン・ザ・ループ・インタラクションといったLangGraphの機能を直接使用することができます。

では、ディープエージェントが実際に役立つのはなぜでしょうか？

長時間実行されるエージェントタスクは、しばしばコンテキストの制限、高いトークンコスト、信頼性の低い実行といった問題に直面します。Deep Agentsは、エージェントのワークフローをより構造化し、管理しやすくすることで、これらの問題の解決を支援します。不要なコンテキストの増加を抑えることで、トークンの使用量を減らし、長時間実行するタスクのコスト効率を維持します。

また、複雑な複数ステップのタスクを整理しやすくします。サブタスクは互いに干渉することなく独立して実行できるため、信頼性が向上する。同時に、システムは柔軟であり、開発者はエージェントが単純な実験から本番アプリケーションに成長するのに合わせてカスタマイズし、拡張することができます。

ディープエージェントにおけるカスタマイズ

一般的なフレームワークでは、あらゆる業界やビジネスのニーズをカバーすることはできません。Deep Agentsは柔軟に設計されているため、開発者は独自のユースケースに合わせて調整できます。

カスタマイズにより、次のことが可能になります：

• 独自の社内ツールとAPIを接続する

• ドメイン固有のワークフローを定義する

• エージェントがビジネスルールに従うことを確認する

• セッション間の記憶とナレッジ共有をサポートする

Deep Agentをカスタマイズする主な方法は次のとおりです：

システムプロンプトのカスタマイズ

ミドルウェアが提供するデフォルトの指示に、独自のシステムプロンプトを追加できます。これは、ドメイン・ルールおよびワークフローを定義するのに便利です。

優れたカスタムプロンプトには、以下が含まれます：

• ドメイン・ワークフロー・ルール

例「データ分析タスクでは、モデルを構築する前に必ず探索的分析を実行する。

• 具体例

例"類似文献の検索依頼を1つのTodo項目にまとめる"

• 停止ルール

具体例"100以上のツールコールが使用されたら停止する"

• ツール調整ガイダンス

例"grep 、コードの場所を見つけ、read_file 、詳細を見る。"

ミドルウェアがすでに処理している命令の繰り返しは避け、デフォルトの動作と矛盾するルールの追加は避ける。

ツール

組み込みのツールセットに独自のツールを追加することができます。ツールは通常の Python 関数として定義され、その docstrings に何を行うかが記述されています。

from deepagents import create_deep_agent
def internet_search(query: str) -> str:
    """Run a web search"""
    return tavily_client.search(query)
agent = create_deep_agent(tools=[internet_search])

Deep Agents は、langchain-mcp-adapters を介してモデル・コンテキスト・プロトコル (MCP) 標準に従うツールもサポートしています。

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent
async def main():
    mcp_client = MultiServerMCPClient(...)
    mcp_tools = await mcp_client.get_tools()
    agent = create_deep_agent(tools=mcp_tools)
    async for chunk in agent.astream({"messages": [{"role": "user", "content": "..."}]}):
        chunk["messages"][-1].pretty_print()

ミドルウェア

以下のカスタム・ミドルウェアを記述できます：

• ツールの追加または変更

• プロンプトの調整

• エージェントの実行のさまざまな段階にフックする

from langchain_core.tools import tool
from deepagents import create_deep_agent
from deepagents.middleware import AgentMiddleware
@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."
class WeatherMiddleware(AgentMiddleware):
    tools = [get_weather]
agent = create_deep_agent(middleware=[WeatherMiddleware()])

Deep Agents には、計画、サブエージェント管理、および実行制御のための組み込みミドルウェアも含まれています。

ミドルウェア	機能
TodoList ミドルウェア	タスクリストを管理するための write_todos と read_todos ツールを提供します。
ファイルシステムミドルウェア	ファイル操作ツールを提供し、大きなツール出力を自動保存する。
サブエージェントミドルウェア	サブエージェントに作業を委任するタスクツールを提供
要約ミドルウェア	コンテキストが170kトークンを超えると自動的に要約する
AnthropicPromptCachingミドルウェア	Anthropicモデルのプロンプトキャッシングを有効にする
PatchToolCallsミドルウェア	中断による不完全なツールコールを修正
HumanInTheLoopミドルウェア	人間の承認が必要なツールの設定

サブエージェント

メインエージェントは、task ツールを使用してサブエージェントにサブタスクを委任することができます。各サブエージェントは、独自のコンテキストウィンドウで実行され、独自のツールとシステムプロンプトを持ちます。

from deepagents import create_deep_agent
research_subagent = {
    "name": "research-agent",
    "description": "Used to research in-depth questions",
    "prompt": "You are an expert researcher",
    "tools": [internet_search],
    "model": "openai:gpt-4o",  # Optional, defaults to main agent model
}
agent = create_deep_agent(subagents=[research_subagent])

高度な使用例では、サブエージェントとして事前に構築されたLangGraphワークフローを渡すこともできます。

from deepagents import CompiledSubAgent, create_deep_agent
custom_graph = create_agent(model=..., tools=..., prompt=...)
agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="data-analyzer",
        description="Specialized agent for data analysis",
        runnable=custom_graph
    )]
)

interrupt_on (人間の承認コントロール）

interrupt_on パラメータを使って、人間の承認を必要とする特定のツールを指定することができます。エージェントがこれらのツールを呼び出すと、人がレビューして承認するまで実行は一時停止します。

from langchain_core.tools import tool
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
@tool
def delete_file(path: str) -> str:
    """Delete a file from the filesystem."""
    return f"Deleted {path}"
agent = create_deep_agent(
    tools=[delete_file],
    interrupt_on={
        "delete_file": {
            "allowed_decisions": ["approve", "edit", "reject"]
        }
    },
    checkpointer=MemorySaver()
)

バックエンドのカスタマイズ（ストレージ）

ファイルの処理方法を制御するために、異なるストレージバックエンドを選択できます。現在のオプションは以下の通りです：

• StateBackend（一時ストレージ）

• FilesystemBackend(ローカルディスクストレージ)

StoreBackend(persistent storage)、CompositeBackend(hybrid routing)。
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/path/to/project")
)

バックエンドを変更することで、システム全体の設計を変更することなく、ファイルストレージの動作を調整できます。

なぜAIエージェントにMilvusのDeep Agentを使うのか？

実際のアプリケーションでは、エージェントはしばしばセッションをまたいで持続するメモリを必要とします。例えば、ユーザの好みを記憶したり、時間をかけてドメイン知識を蓄積したり、行動を調整するためにフィードバックを記録したり、長期的な調査タスクを追跡したりする必要があるかもしれません。

デフォルトでは、Deep Agents はStateBackend を使用し、単一のセッション中のみデータを保存します。セッションが終了すると、すべてクリアされます。つまり、長期的なクロス・セッション・メモリをサポートすることはできません。

永続的な記憶を可能にするために、Milvus を StoreBackend と共にベクトル・データベースとして使用する。その仕組みは以下の通り：重要な会話内容やツールの結果はエンベッディング（意味を表す数値ベクトル）に変換され、Milvus に保存される。新しいタスクが始まると、エージェントは関連する過去の記憶を取り出すために意味検索を行う。これによりエージェントは以前のセッションの関連情報を「記憶」することができる。

Milvusは、計算機とストレージを分離したアーキテクチャのため、このユースケースに適しています。Milvusは以下をサポートしている：

• 数百億ベクトルへの水平スケーリング

• 高同期クエリ

• リアルタイムのデータ更新

• 大規模システム向けのプロダクション対応デプロイメント

技術的には、Deep AgentsはCompositeBackend 、異なるストレージバックエンドに異なるパスをルーティングします：

パス	バックエンド	目的
/ワークスペース/, /temp/	状態バックエンド	セッション終了後に消去される一時的なデータ
/メモリー/、/ナレッジ	StoreBackend + milvus	セッションをまたいで検索可能な永続データ

このセットアップでは、開発者は長期的なデータを/memories/ のようなパスに保存するだけでよい。システムは自動的にクロス・セッション・メモリを処理する。詳細な設定手順は以下のセクションで説明する。

ハンズオンMilvusとDeep Agentsを使用した長期メモリ付きAIエージェントの構築

この例では、Milvusを使用してDeepAgentsベースのエージェントに永続的なメモリを与える方法を示します。

ステップ1: 依存関係のインストール

pip install deepagents tavily-python langchain-milvus

ステップ2: メモリバックエンドのセットアップ

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langchain_milvus.storage import MilvusStore
# from langgraph.store.memory import InMemoryStore # for testing only
# Configure Milvus storage
milvus_store = MilvusStore(
    collection_name="agent_memories",
    embedding_service=... # embedding is required here, or use MilvusStore default configuration
)
backend = CompositeBackend(
    default=StateBackend(),
    routes={"/memories/": StoreBackend(store=InMemoryStore())} 
)

ステップ 3: エージェントの作成

from tavily import TavilyClient
import os
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(query: str, max_results: int = 5) -> str:
    """Perform an internet search"""
    results = tavily_client.search(query, max_results=max_results)
    return "\n".join([f"{r['title']}: {r['content']}" for r in results["results"]])
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="You are a research expert. Write important findings to the /memories/ directory for cross-session reuse.",
    backend=backend
)
# Run the agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "Research the technical features of the Milvus vector database"}]
})

キーポイント

• 永続パス

/memories/ の下に保存されたファイルは永続的に保存され、異なるセッションでもアクセスできます。

• 本番用セットアップ

この例では、テスト用にInMemoryStore() を使用しています。本番環境では、スケーラブルなセマンティック検索を可能にするために、Milvusアダプターに置き換えてください。

• 自動メモリ

エージェントは、調査結果と重要なアウトプットを自動的に/memories/ フォルダに保存します。後のタスクでは、関連する過去の情報を検索して取り出すことができます。

組み込みツールの概要

Deep Agents には、ミドルウェアを通じて提供されるいくつかの組み込みツールがあります。これらは主に 3 つのグループに分類されます：

タスク管理 (TodoListMiddleware)

• write_todos

構造化されたTodoリストを作成します。各タスクには、説明、優先度、および依存関係を含めることができます。

• read_todos

完了したタスクと保留中のタスクを含む、現在のTodoリストを表示します。

ファイルシステムツール (FilesystemMiddleware)

• ls

ディレクトリ内のファイルを一覧表示します。絶対パス（/ で始まる）を使用する必要があります。

• read_file

ファイルの内容を読み取ります。大容量ファイル用にoffset とlimit をサポート。

• write_file

ファイルの作成または上書き。

• edit_file

ファイル内の特定のテキストを置換します。

• glob

すべての Python ファイルを検索する**/*.py のように、パターンを使用してファイルを検索します。

• grep

ファイル内のテキストを検索します。

• execute

サンドボックス環境でシェルコマンドを実行します。バックエンドがSandboxBackendProtocol をサポートしている必要があります。

サブエージェント委任 (SubAgentMiddleware)

• task

サブタスクを特定のサブエージェントに送る。サブエージェント名とタスクの説明を指定する。

ツール出力の処理方法

ツールが大きな結果を生成した場合、Deep Agents はそれを自動的にファイルに保存します。

例えば、internet_search が 100KB のコンテンツを返す場合、システムはそれを/tool_results/internet_search_1.txt のように保存します。エージェントは、コンテキスト内のファイル・パスのみを保持します。これにより、トークンの使用量が減り、コンテキスト・ウィンドウが小さくなります。

DeepAgent とエージェント・ビルダーの比較：それぞれを使用する必要があるのはどのような場合ですか?

この記事はDeepAgentsに焦点を当てているので、LangChainエコシステムのもう一つのエージェント構築オプションである Agent Builderとの比較も理解しておくと便利です。

LangChainはAIエージェントを構築するためのいくつかの方法を提供しており、最適な選択は通常、あなたがシステムをどの程度コントロールしたいかによって決まります。

DeepAgentsは、長時間のマルチステップタスクを処理する自律型エージェントを構築するために設計されています。開発者は、エージェントがどのようにタスクを計画し、ツールを使用し、メモリを管理するかを完全に制御することができます。LangGraph上に構築されているため、コンポーネントをカスタマイズし、Pythonツールを統合し、ストレージバックエンドを変更することができます。このため、DeepAgentsは、信頼性と柔軟性が重要な複雑なワークフローや生産システムに適しています。

対照的に、Agent Builderは使いやすさに重点を置いています。技術的な詳細はほとんど隠されているため、エージェントを記述し、ツールを追加し、迅速に実行できます。メモリ、ツールの使用、人間の承認ステップは自動的に処理されます。このため、Agent Builderは、迅速なプロトタイプ、内部ツール、または初期の実験に便利です。

Agent BuilderとDeepAgentsは別個のシステムではなく、同じスタックの一部です。Agent Builderは、DeepAgentsの上に構築されています。多くのチームは、まずAgent Builderでアイデアをテストし、さらに制御が必要になったらDeepAgentsに切り替えます。DeepAgentsで作成したワークフローは、Agent Builderのテンプレートに変換できるため、他のチームが簡単に再利用できます。

結論

Deep Agents は、タスク計画、ファイルストレージ、およびサブエージェントの委任という 3 つの主要なアイデアを使用することで、複雑なエージェントのワークフローを管理しやすくします。これらのメカニズムは、面倒なマルチステッププロセスを構造化されたワークフローに変えます。Milvusと組み合わせてベクトル検索を行うことで、エージェントはセッションをまたいで長期記憶を保持することができます。

開発者にとっては、トークンのコストが下がり、シンプルなデモから本番環境までスケールできる、より信頼性の高いシステムができることを意味します。

構造化されたワークフローと実際の長期記憶を必要とするAIエージェントを構築している場合、ぜひご連絡ください。

ディープエージェントやMilvusを永続メモリバックエンドとして使用することについてご質問がありますか？Slackチャンネルにご参加いただくか、Milvusオフィスアワーの20分セッションをご予約ください。