LangChain の「Managed Deep Agents」にツール機能を追加

LangChain の「Managed Deep Agents」に独自ツールを追加して AI エージェントを拡張する方法

LangChain が提供する Managed Deep Agents は、LLM に検索やファイル操作などの標準機能を提供しますが、実際の業務では社内のデータベースや独自の API と連携できるカスタムツールが不可欠です。本記事では、Python を用いて独自のカスタムツールを定義し、Managed Deep Agents に接続して AI エージェントの能力を柔軟に拡張する具体的な手順と、LLM が正しくツールを理解させるための重要な設定について解説します。

標準機能の限界とカスタムツールの必要性

Managed Deep Agents は、モデル側（例：OpenAI）が提供する「組み込みツール」や、ハッチス自体に埋め込まれたファイル操作ツールなどを初期状態で利用できます。これらは Web 検索や基本的なデータ処理には便利ですが、社内の CRM システムへのアクセスや、外部 API を介した特定の実行など、組織固有のタスクには対応できません。

ツールは、エージェントが外部世界と相互作用するための手段です。データベースを検索したり、オンライン情報を取得したり、外部 API 経由でアクションを実行したりする機能こそが、エージェントに「行動能力」を与えます。

このため、開発者が自社のシステムやデータベースと連携できる独自のカスタムツールを定義し、エージェントに接続する必要があります。

カスタムツールの定義方法：デコレータとドキュストリング

Python で Managed Deep Agents にカスタムツールを追加する際、最も重要なのは「関数」を「ツール」として認識させる仕組みです。LangChain のツールデコレータ（@lc_tool など）を関数に付与することで、通常の Python 関数をエージェントが利用可能なツールに変換できます。

ツールとして定義する関数は、以下の要素を含める必要があります。

1. 名前: 関数名そのままがツールの名前にマッピングされます。これは人間だけでなく、LLM がツールを識別するための名称です。
2. パラメータ: LLM がツールを呼び出す際に埋める必要がある引数です。型ヒントや説明を明記することで、LLM が適切な値を推論しやすくなります。
3. ドキュストリング（Docstring）: 関数の冒頭に記述された説明文が、ツールの説明として LLM に渡されます。ここでの記述の質が、エージェントがツールを正しく使いこなせるかどうかを決定づけます。

以下は、顧客情報を取得するカスタムツールの定義例です。

from langchain.tools import tool

@tool
def lookup_customer(customer_id: str) -> str:
    """
    顧客 ID を指定して顧客レコードを検索します。

    Args:
        customer_id (str): 検索対象の顧客 ID

    Returns:
        str: 顧客情報（プラン名やステータスなど）
    """
    # ここに実際のデータベース照会ロジックが入ります
    return f"顧客 {customer_id} はエンタープライズプランです。"

このように、名前、パラメータ、そして何より LLM 向けの説明（ドキュストリング）を明確に記述することが、ツール定義の核心です。

エージェントへの接続と設定ファイルへの登録

カスタムツールの関数を作成したら、次は Managed Deep Agents の設定ファイル（エージェント定義ファイル）に対して、そのツールを読み込み、利用可能にする手順が必要です。TypeScript 版でも同様にファイルとして扱われますが、Python では Python ファイルとして定義し、インポートして登録します。

1. ツール関数を定義したファイル（例：tools/lookup.py）を作成します。
2. エージェントの設定ファイルで、そのツールをインポートします。
3. 設定リストに追加することで、エージェントが実行可能な状態になります。

from tools.lookup import lookup_customer

# エージェントのツールリストに追加
agent_tools = [lookup_customer, ...既存のツール...]

この一連の手順で、新しいツールは即座にエージェントの能力として利用可能になります。複雑な設定や追加のコード不要で、関数を定義してインポートするだけで拡張が可能です。

LLM がドキュストリングを正しく解釈するための「parse_docstring」

カスタムツールの説明（ドキュストリング）が LLM に正しく伝わるかどうかは、設定パラメータ parse_docstring の有無で決まります。このパラメータを有効化すると、関数のドキュストリング内の情報が構造化されて LLM に渡され、ツール呼び出しの精度が大幅に向上します。

トレーシングログを確認すると、LLM が受け取るプロンプト内で parse_docstring=true として処理された結果、パラメータ名や型、説明が明確に記述されていることがわかります。例えば、ドキュストリング内の「顧客 ID を指定して検索」という記述は、LLM にとって「customer_id という文字列型の引数が必要である」という具体的な指示として解釈されます。

parse_docstring を有効化することで、関数の説明が LLM に正しく伝達され、ツール呼び出しの精度が高まります。ドキュストリングの記述が不十分だと、LLM はツールを誤って使用したり、そもそも使用しなかったりします。

つまり、ツールの定義は人間のためのものだけでなく、LLM がその機能を理解し、適切に活用するための重要な情報源なのです。

実行結果とトレーシングによる検証

カスタムツールの設定が完了したら、mda dev コマンドで開発者用スタジオを起動し、実際にエージェントをテストします。チャット画面で「顧客 ID 123 の情報を教えて」と指示すると、エージェントは自動的に lookup_customer ツールを呼び出し、結果を返すことが確認できます。

さらに、トレーシング機能（Trace）を活用することで、LLM がどのような思考プロセスを経てツールを選択し、どのような引数を送信したかを詳細に検証できます。トレースログでは、以下のような情報が可視化されます。

• エージェントが利用可能なツールのリスト（組み込み検索、ファイル操作、カスタム CRM ツールなど）
• LLM が受け取るプロンプト内のツール定義と説明
• 実際の呼び出し引数（例：customer_id: "123"）
• ツールからの戻り値

このように、トレーシングログは開発者がエージェントの動作をデバッグし、ドキュストリングやパラメータ定義が LLM に正しく伝達されているかを検証するための強力なツールです。

まとめ

Managed Deep Agents へのカスタムツール追加は、Python で関数を定義し、デコレータでラップして設定ファイルにインポートするだけのシンプルなプロセスです。しかし、その実効性を高める鍵となるのは、LLM が正しく理解できる「ドキュストリング」の記述と、parse_docstring パラメータの活用にあります。この基本的なワークフローをマスターすることで、開発者は自社のシステムやデータベースに柔軟に対応する汎用 AI エージェントを迅速に構築し、エンタープライズ環境での実務適用範囲を広げることができます。