🛞

自律型エージェントの実装 ~ ReAct パターン

に公開

はじめに

エージェントについて理解ができていなかったため、理解を深めるために一から実装してみました。
今回 ReAct パターンを導入して、自律型エージェントを実装しています。

登場する概念

ReAct パターン

ReAct パターンとは推論(Reasoning)と行動(Action)を繰り返すことを指しています。
もう少し細かく見ると、下図のように思考(Thought)、行動(Action)、観察(Observation)というプロセスを繰り返すパターンです。

Function Calling

LLM が使用可能なツールをあらかじめ定義しておき、どのツールを使用するか判断させる手法です。
上図だと ツール仕様の読み込み で使用可能なツールの定義を LLM に提供します。
LLM は Action: ツール選択 で使用するツールを決定します。
アプリケーション側はツールを実行して結果を Observation: 実行結果 として履歴に積んで行きます。

Agent as a Tool

エージェントはツールを保持しますが、エージェント自体もツールとしてより上の階層のエージェントに保持されます。

コードの要点の説明

システムプロンプト

システムプロンプトは LLM に ReAct エージェントとしての振る舞いを指定します。
ReAct エージェントのコアとなります。

SYSTEM_PROMPT = """
あなたは、{agent_role}です。
以下のミッションを遂行するために、ツールを論理的に選択して実行してください。

## ミッション:
{task_description}

## 利用可能なツール:
{tools_spec}

## 出力フォーマット:
回答は必ず以下のJSON形式のみで出力してください。他のテキストは一切含めないでください。

{{
    "thought": "現在の状況分析",
    "action": "ツール名 または null",
    "action_input": {{"引数名": "値"}} または null,
    "answer": "最終回答 または null"
}}

## 動作ルール:
1. 思考: 何が不足しているかを thought に書き出してください。
2. 評価: ツール結果が「正確か」「十分か」を厳格に評価してください。
3. 完了: 準備が整ったら answer を出力し、action は null にしてください。
"""

ツールの管理

レジスタパターンでツールを管理しています。
ツールのレジスタクラスのインスタンスを、ReAct エージェントクラスが受け取ります。

ReAct エージェントクラスはレジスタクラスからツールの定義を取得して LLM のシステムプロンプトに含めます。
また、LLM の回答をもとにツールを取得して実行します。

class ToolRegistry:
    def __init__(self):
        self.tools: dict[str, Tool] = {}

    def get(self, name: str):
        """ツールを取得します。"""
        return self.tools[name]

    def get_tools_spec(self):
        """LLMのプロンプトに渡す形式で、全ツールの仕様を返します。"""
        spec = {}
        for tool in self.tools.values():
            spec.update(tool.to_dict())
        return spec

class ReActAgent:
    def __init__(self, tools: ToolRegistry):
        self.tools = tools

階層型レジストリによる無限ループ回避

サブエージェントには簡単な Web 情報取得ツールを与えています。
メインエージェントにはサブエージェントをツールとして与えています。
メインエージェント -> サブエージェント -> Web 情報取得ツールと一方向の依存関係にすることで、 無限ループを避けています。

# メインエージェントのツールとしてサブエージェントを登録
main_agent_tools.register(
    Tool(
        name=sub_agent.name,
        description="Webから最新の情報を自律的に検索します。",
        func=sub_agent.run_react_loop,
        func_parameters_schema={"query": {"type": "string"}},
    )
)

# メインエージェントを作成
main_agent = ReActAgent(
    main_agent_tools,
    "main_agent",
    "与えられた課題を自律的に解決するエージェント",
)

履歴の蓄積

履歴には最初にシステムプロンプト(ReAct エージェントの仕様)とユーザーのクエリを設定します。そこに LLM の回答とツールの実行結果を積んで行きます。

履歴の積み上げによって発生するトークン量の増大を防ぐため、実行サイクルは最大3回までとしています。

# メッセージの履歴を初期化
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": query},
]

# 履歴の追加
# LLM の回答
messages.append({"role": "assistant", "content": res.model_dump_json()})
# ツールの実行結果
messages.append({"role": "user", "content": f"Observation: {observation}"})  

全体コード

動かし方

環境変数の設定

LLM の呼び出しには LiteLLM を使用しています。
MODEL_NAME に使用するモデル名を設定して、以下を参考に API Key を設定してください。
https://docs.litellm.ai/docs/set_keys

実行コマンド

# 依存パッケージのインストール
uv init
uv add litellm ddgs pydantic trafilatura

# 環境変数の設定(例)
export MODEL_NAME=gpt-4o
export OPENAI_API_KEY=***

# ReAct エージェントの起動
uv run react_agent.py ${質問}

コードの全容

コードを見る
import json
import os
import re
import sys
import textwrap
from typing import Callable

import litellm
from ddgs import DDGS
from pydantic import BaseModel, Field
from trafilatura import extract, fetch_url


class Tool(BaseModel):
    """ツールの基底クラス"""

    name: str
    description: str
    func: Callable  # 実行される関数の本体
    func_parameters_schema: dict | None = None  # 関数のパラメータのスキーマ

    def to_dict(self) -> dict:
        """LLMのプロンプトに渡す形式に変換します。"""
        return {
            self.name: {
                "description": self.description,
                "parameters": self.func_parameters_schema or {},
            }
        }


class ToolRegistry:
    """ツールのレジストリクラス"""

    def __init__(self):
        self.tools: dict[str, Tool] = {}

    def register(self, tool: Tool):
        """ツールを登録します。"""
        self.tools[tool.name] = tool

    def unregister(self, name: str):
        """ツールを削除します。"""
        del self.tools[name]

    def get(self, name: str):
        """ツールを取得します。"""
        return self.tools[name]

    def get_tools_spec(self):
        """LLMのプロンプトに渡す形式で、全ツールの仕様を返します。"""
        spec = {}
        for tool in self.tools.values():
            spec.update(tool.to_dict())
        return spec


class ReActFormat(BaseModel):
    """ReActの出力形式"""

    thought: str
    action: str | None = Field(default=None)
    action_input: dict | None = Field(default=None)
    answer: str | None = Field(default=None)


class ReActAgent:
    """
    ReActAgent エージェントクラス。

    Args:
        tools: 利用可能なツール
        name: エージェントの名前
        role: エージェントの役割
        model_name: 使用するモデルの名前

    Returns:
        str: 最終回答
    """

    SYSTEM_PROMPT = """
    あなたは、{agent_role}です。
    以下のミッションを遂行するために、ツールを論理的に選択して実行してください。

    ## ミッション:
    {task_description}

    ## 利用可能なツール:
    {tools_spec}

    ## 出力フォーマット:
    回答は必ず以下のJSON形式のみで出力してください。他のテキストは一切含めないでください。

    {{
        "thought": "現在の状況分析",
        "action": "ツール名 または null",
        "action_input": {{"引数名": "値"}} または null,
        "answer": "最終回答 または null"
    }}

    ## 動作ルール:
    1. 思考: 何が不足しているかを thought に書き出してください。
    2. 評価: ツール結果が「正確か」「十分か」を厳格に評価してください。
    3. 完了: 準備が整ったら answer を出力し、action は null にしてください。
    """

    def __init__(
        self,
        tools: ToolRegistry,
        name: str,
        role: str,
    ):
        self.tools = tools
        self.name = name
        self.role = role

    def call_llm(self, messages: list[dict]) -> ReActFormat:
        """
        litellmを使用してモデルを呼び出します。
        環境変数 MODEL_NAME で指定されたモデルを使用します。
        """
        model_name = os.getenv("MODEL_NAME")
        res = litellm.completion(
            model=model_name, messages=messages, response_format={"type": "json_object"}
        )

        content = res.choices[0].message.content
        return ReActFormat.model_validate_json(content)

    def run_react_loop(self, query: str) -> str:
        """ReActパターンに従って、ユーザーの質問に対して回答を生成します。"""

        # ツール仕様を取得
        # 例: {"web_search": {"description": "Webから情報を検索します。", "parameters": {"query": {"type": "string"}}}}
        tools_spec = self.tools.get_tools_spec()

        # システムプロンプトを作成
        system_prompt = textwrap.dedent(self.SYSTEM_PROMPT).format(
            agent_role=self.role,
            task_description=query,
            tools_spec=json.dumps(tools_spec, ensure_ascii=False, indent=2),
        )

        # メッセージの履歴を初期化
        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": query},
        ]

        # 最大3回のターンを繰り返す
        # トークン使用量がきになるので短めに設定
        for i in range(3):
            print(f"\n=== [{self.name}] ===")

            res = self.call_llm(messages)
            print(f"Thought: {res.thought}")

            if res.answer:
                print(f"Final Answer: {res.answer}")
                return res.answer

            # レジストリから動的にツールを取得して実行
            if res.action in self.tools.tools:
                tool = self.tools.get(res.action)
                observation = tool.func(**res.action_input)
            else:
                observation = f"エラー: 未定義のツール '{res.action}' です。"

            # 履歴の追加
            messages.append({"role": "assistant", "content": res.model_dump_json()})
            messages.append({"role": "user", "content": f"Observation: {observation}"})

        return "制限回数内に回答を得ることができませんでした。"


if __name__ == "__main__":
    sub_agent_tools = ToolRegistry()

    # サブエージェントのツール用の関数を作成
    def web_search(query, max_results=3, max_chars=2000):
        """DuckDuckGo で検索し、URL のコンテンツを取得します。"""
        print(f"  [Executing web_search] query: {query}")
        search_results = list(DDGS().text(query, max_results=max_results))
        results = []
        for item in search_results:
            url = item.get("href") or item.get("url")
            content = fetch_url(url)
            if content:
                text = re.sub(r"\s+", " ", extract(content) or "").strip()
                text = text[:max_chars]
                results.append({"url": url, "text": text})
        return json.dumps(results, ensure_ascii=False)

    # サブエージェントのツールを登録
    sub_agent_tools.register(
        Tool(
            name="web_search",
            description="Webから情報を検索します。",
            func=web_search,
            func_parameters_schema={"query": {"type": "string"}},
        )
    )

    # サブエージェントを作成
    sub_agent = ReActAgent(
        sub_agent_tools,
        "web_search_agent",
        "Webから最新の情報を検索する自律型エージェント",
    )

    main_agent_tools = ToolRegistry()

    # メインエージェントのツールとしてサブエージェントを登録
    main_agent_tools.register(
        Tool(
            name=sub_agent.name,
            description="Webから最新の情報を自律的に検索します。",
            func=sub_agent.run_react_loop,
            func_parameters_schema={"query": {"type": "string"}},
        )
    )

    # メインエージェントを作成
    main_agent = ReActAgent(
        main_agent_tools,
        "main_agent",
        "与えられた課題を自律的に解決するエージェント",
    )

    result = main_agent.run_react_loop(sys.argv[1])

    print(f"\n=== [最終回答] ===")
    print(f"{result}")

実行結果

メインエージェントがサブエージェントを呼び出し、
サブエージェントが情報収集して、最終回答を導き出しています。

uv run python react_agent.py "HHKBでMacの場合にFnキーをCtrlにするスイッチ設定は?"

=== [main_agent] ===
Thought: HHKBのスイッチ設定についての具体的な知識は持っていないが、外部からの情報が必要。

=== [web_search_agent] ===
Thought: HHKBでFnキーをCtrlに変更する方法を知る必要がある。
  [Executing web_search] query: HHKB Mac Fn key switch to Ctrl setting
Impersonate 'edge_127' does not exist, using 'random'

=== [web_search_agent] ===
Thought: HHKBでFnキーをCtrlに変更するためには、HHKBのキーマップツールを使用することで設定が可能である。このツールを用いることでキーのカスタマイズが行える。
Final Answer: HHKBでFnキーをCtrlに変更するには、HHKBのキーマップツールをダウンロードし、キーマップをカスタマイズすることで実現できます。このツールを使用することで、左右どちらかのFnキーをCtrlキーに割り当てられます。また、必要に応じてDIPスイッチの設定変更も行えます。

=== [main_agent] ===
Thought: HHKBでFnキーをCtrlに変更する方法が判明した。キーマップツールを使用して設定を変更する。
Final Answer: HHKBでMacの場合にFnキーをCtrlに設定するには、HHKBのキーマップツールをダウンロードし、そのツールを使ってキーマップをカスタマイズしてFnキーをCtrlキーに割り当てます。また、必要に応じてDIPスイッチの設定変更も可能です。

=== [最終回答] ===
HHKBでMacの場合にFnキーをCtrlに設定するには、HHKBのキーマップツールをダウンロードし、そのツールを使ってキーマップをカスタマイズしてFnキーをCtrlキーに割り当てます。また、必要に応じてDIPスイッチの設定変更も可能です。

おわりに

実務でエージェントを構築する場合、LangGraph や LlamaIndex を使うのが一般的かと思います。そのため、ReAct エージェントを一から自作する機会は少ないかもしれません。

しかし、今回あえてフルスクラッチで実装してみることで、「自律性」の正体が、プロンプト設計と状態管理(メッセージ履歴)の積み重ねであることを理解できました。

Aprender Tech Blog

Discussion