プロンプト活用

【LLM全般】ローカルLLMでAgent機能を実装する方法：ReAct/Tool Useの実践ガイドとよくあるエラー解決

· 15分で読めます · 7 閲覧

問題の概要：ローカルLLMでAgent機能を実装する際の課題

近年、ChatGPTやClaudeのような大規模言語モデル（LLM）の「Agent機能」、すなわち外部ツールを利用して自律的にタスクを実行する能力に注目が集まっています。しかし、OpenAI APIなどのクラウドサービスを利用せず、ローカル環境で動作するLLM（Llama 3, Gemma, Mixtralなど）で同様のAgent機能を実装しようとすると、開発者はいくつかの壁に直面します。

具体的なエラーや課題としては、以下のようなものが頻繁に報告されています。

  • フォーマットエラー: LLMの出力が期待したJSONや特定の構造（例: Thought:, Action:, Action Input:）に従わない。
  • ツール選択の誤り: 利用可能なツールのリストがあるにもかかわらず、存在しないツール名を出力したり、タスクに不適切なツールを選択したりする。
  • 無限ループ: ThoughtとObservationのサイクルが終了条件に達せず、同じ処理を繰り返し続ける。
  • コンテキスト長超過: 会話履歴、ツールの説明、思考過程がモデルのコンテキストウィンドウを超え、処理が失敗する。
# 典型的なエラーメッセージ例
Error: LLM output parsing failed. Expected format 'Action: ...nAction Input: ...' but got 'I think I should search for the weather.'
JSONDecodeError: Expecting value: line 1 column 1 (char 0)
Warning: Context length exceeded. Truncating conversation history.

原因の解説：なぜローカルLLMでのAgent実装は難しいのか

これらの問題の根本原因は、主に以下の3点に集約されます。

1. 指示追従（Instruction Following）能力の差

GPT-4やClaude-3のような最先端のクラウドモデルは、複雑な出力フォーマットを厳密に守るように微調整（Fine-tuning）されています。一方、多くのローカルLLMは、汎用的なテキスト生成に優れていても、特定の構造化フォーマットを遵守する「指示追従」能力が相対的に低い場合があります。これがフォーマットエラーの主要因です。

2. プロンプトエンジニアリングの難易度

ReAct（Reasoning + Acting）やTool Useを実現するには、モデルに「思考」「行動」「観察」のサイクルを理解させる詳細なプロンプト設計が必要です。ツールの説明、出力形式の例（Few-shot Example）、タスクの制約を全てプロンプト内に収め、かつモデルの能力範囲内で理解させるのは高度な技術を要します。

3. コンテキスト長と計算リソースの制約

Agentの実行では、思考過程の蓄積によりコンテキストが膨張します。7Bや13Bパラメータの軽量ローカルモデルでは、コンテキスト長（通常2K〜8Kトークン）がすぐに不足したり、長いコンテキストの処理中に計算リソース（VRAM）が枯渇したりするリスクがあります。

解決方法：ステップバイステップ実装ガイド

ここでは、PythonとLangChainライブラリを用いて、ローカルLLMでシンプルなAgentを構築する方法を説明します。LangChainは、Agent構築の複雑さを抽象化する強力なフレームワークです。

ステップ1: 環境構築とモデルの準備

まず、必要なライブラリをインストールし、ローカルLLMを読み込みます。ここでは、Ollamaを使ってLlama 3 8Bモデルを利用する例を示します。

# 必要なライブラリのインストール
pip install langchain langchain-community langchainhub chromadb beautifulsoup4
pip install ollama  # Ollamaのインストールとモデルダウンロードは別途必要

# ターミナルでOllamaモデルをプル（初回のみ）
# ollama pull llama3:8b

ステップ2: ツールの定義

Agentが使用できるツールを関数として定義し、LangChainのツールオブジェクトにラップします。

from langchain.agents import tool
from datetime import datetime

# シンプルなツールの例1: 現在時刻を返す
@tool
def get_current_time(query: str) -> str:
    """現在の日時を返します。引数は無視されます。"""
    return f"現在の日時は: {datetime.now().strftime('%Y年%m月%d日 %H:%M:%S')}"

# シンプルなツールの例2: 数値の計算を行う（簡易版）
@tool
def calculate(expression: str) -> str:
    """数式（例: '3 + 5' や '10 / 2'）を計算して結果を返します。"""
    try:
        # 注意: セキュリティ上、evalの使用は実際のプロダクトでは避け、安全なパーサーを使用すべきです。
        result = eval(expression)
        return f"計算結果: {expression} = {result}"
    except Exception as e:
        return f"計算エラー: {e}"

ステップ3: プロンプトテンプレートとLLMのセットアップ

ReAct形式の思考を促すプロンプトテンプレートを準備し、ローカルLLM（Ollama経由）と連携させます。

from langchain.agents import create_react_agent, AgentExecutor
from langchain.prompts import PromptTemplate
from langchain_community.llms import Ollama

# ローカルLLMの読み込み (Ollamaを使用)
llm = Ollama(model="llama3:8b", temperature=0)  # temperatureを低く設定し、出力を安定させる

# ReAct形式のプロンプトテンプレート（シンプル版）
# LangChain Hubからデフォルトのものを使用することも可能
react_prompt = PromptTemplate.from_template(
    """以下の質問に答えてください。以下のツールが利用可能です:

{tools}

質問: {input}
思考: 質問に答えるために、段階的に考えましょう。利用可能なツールがあれば、正確に使用してください。
{agent_scratchpad}"""
)

ステップ4: Agentの作成と実行

ツール、LLM、プロンプトを組み合わせてAgentを構築し、実行するエグゼキューターを作成します。

# ツールをリスト化
tools = [get_current_time, calculate]

# ReAct Agentの作成
agent = create_react_agent(llm, tools, react_prompt)

# Agentエグゼキューターの作成（最大ループ数を制限して無限ループを防止）
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=5, handle_parsing_errors=True)

# Agentの実行例
try:
    result = agent_executor.invoke({"input": "今何時ですか？それから、123に456を足した値も教えてください。"})
    print("n最終結果:", result["output"])
except Exception as e:
    print(f"エラーが発生しました: {e}")

上記コードを実行すると、verbose=Trueにより、Agentの思考過程（Thought, Action, Observation）がコンソールに詳細に出力され、デバッグに役立ちます。

コード例・コマンド例：よくあるエラーとその対策

エラー1: 出力パースエラーの詳細対応

handle_parsing_errors=Trueを設定してもエラーが解消しない場合、より頑健なパーサーを用意したり、プロンプトを強化したりする必要があります。

# カスタム出力パーサーの例（簡易版）
from langchain.schema import AgentAction, AgentFinish
import re

def custom_react_output_parser(text: str):
    """ReAct形式の出力をパースするカスタム関数。"""
    action_match = re.search(r"Action:s*(.+?)n", text)
    action_input_match = re.search(r"Action Input:s*(.+?)(?:n|$)", text)
    finish_match = re.search(r"Final Answer:s*(.+?)(?:n|$)", text, re.DOTALL)

    if finish_match:
        return AgentFinish(return_values={"output": finish_match.group(1).strip()}, log=text)
    elif action_match and action_input_match:
        action = action_match.group(1).strip()
        action_input = action_input_match.group(1).strip().strip('"'')
        return AgentAction(tool=action, tool_input=action_input, log=text)
    else:
        # パース失敗時は、エラーではなく「最終答え」として扱い、処理を終了させる一例
        return AgentFinish(return_values={"output": f"モデルの出力を解析できませんでした。生の出力: {text[:200]}"}, log=text)

# AgentExecutor作成時にカスタムパーサーを渡す（高度な設定が必要）

エラー2: ツール選択ミスを減らすプロンプト改良

ツールの説明（docstring）を非常に明確にし、Few-shot Exampleをプロンプトに含めます。

# 改良版プロンプトテンプレートの一部
enhanced_prompt = """
あなたは優秀なアシスタントです。以下のツールのみを使用できます。ツールはJSON形式で指定されています。

ツール一覧:
{tools}

出力形式は以下に厳密に従ってください:
Thought: ここに質問に対する思考を段階的に書く
Action: 使用するツール名（上記リストから正確に選択）
Action Input: ツールへの入力（適切な形式で）
Observation: ツールの実行結果（この行はあなたは書かず、システムが挿入します）
... (この思考-行動-観察のサイクルを繰り返す)
Final Answer: 質問に対する最終的な答え

例:
質問: 東京の現在の天気は？
Thought: ユーザーは東京の現在の天気を知りたい。天気を取得するツールは「get_weather」だ。
Action: get_weather
Action Input: {{"location": "Tokyo"}}

では、始めます。
質問: {input}
{agent_scratchpad}
"""

まとめ・補足情報

ローカルLLMでAgent機能を実装するには、モデルの能力限界を理解した上で、プロンプト設計、ツール定義、エラーハンドリングの3つを慎重に行うことが成功のカギです。LangChainのようなフレームワークを利用すれば、これらの複雑さの多くを抽象化できますが、依然としてモデル自体の指示追従能力に大きく依存します。

実践的なアドバイス:

  • モデル選定: Agentタスクには、命令理解に特化してチューニングされたモデル（例: Llama 3 Instruct, Mistral Instruct, Command R）を選択しましょう。
  • 段階的開発: いきなり複雑なAgentを作るのではなく、1つのツールから始め、確実に動作してから機能を追加しましょう。
  • フォールバック戦略: パースエラー時や不適切な出力時には、ユーザーに明確なエラーメッセージを表示したり、シンプルなチャットモードにフォールバックしたりするロジックを組み込みましょう。
  • コンテキスト管理: 会話履歴が長くなりすぎないよう、重要な部分だけを要約して保持するメモリ機能（ConversationSummaryBufferMemoryなど）の利用を検討しましょう。

ローカル環境でのAgent開発は、データプライバシー、コスト削減、カスタマイズ性の点で大きなメリットがあります。本ガイドを参考に、試行錯誤を重ねながら、ご自身のユースケースに合った実用的なAgentの構築に挑戦してみてください。

この記事は役に立ちましたか？