AIチュートリアル

miniEvoAgentでツール呼び出しと自己進化型LLMエージェントを構築する

このチュートリアルでは、単一アクションのLLMエージェントの構築、Pythonツールの実行、QA予測の評価、フィードバックに基づくプロンプトの進化に対応した、読みやすいフレームワークminiEvoAgentを紹介します。evo_reproパッケージをインストールし、OpenAI互換モデルを設定して、基本エージェントとツール対応エージェントを実行します。さらに、進化のトレースを確認し、リモートモデル呼び出しなしでフレームワークをテストします。

2026年8月29日約14分で読了

miniEvoAgentとは？

miniEvoAgentは、LLMベースのエージェントがどのように構築・改善されるかを学ぶための、コンパクトなPythonフレームワークです。EvoAgentXに着想を得ており、エージェントの実行、ツール呼び出し、評価、プロンプトの書き換え、自己進化という中核概念を維持しながら、大規模なエージェントフレームワークの複雑さを取り除いています。

パッケージ名は現在evo_reproです。意図的に小さく設計されているため、それぞれの仕組みを読みやすく、テストしやすく、拡張しやすくなっています。ワークフローグラフ、メモリ、ビジュアルエディター、ベンチマークアダプター、大規模なツールエコシステムを提供するのではなく、透明性の高い単一アクションエージェントとプロンプト進化ループに焦点を当てています。

フレームワークの仕組み

miniEvoAgentアプリケーションは、いくつかの役割に特化したコンポーネントから構成されます。

PromptTemplate：タスクの入力をプロンプトテンプレートに挿入します。
Action：LLMを呼び出し、必要に応じて複数ラウンドのツール実行を行い、最終レスポンスを解析します。
Agent：アクションをラップし、構造化されたメッセージを返します。
Evaluator関数：完全一致、トークンレベルのF1、正解率を使用してQA予測を評価します。
PromptRewriter：オプティマイザーLLMを使用し、具体的なフィードバック例に基づいて改訂版プロンプトを提案します。
PromptSelector：同じ開発セットで親プロンプトと候補を比較し、より高い性能のものを保持します。
evolve：学習実行、フィードバック生成、書き換え、評価、選択を繰り返します。

主な機能

最小限で検査しやすい単一アクションエージェントの抽象化。
環境変数またはローカルの.envファイルで設定できる、OpenAI互換のLLMアダプター。
複数ラウンドのツール実行に対応した、OpenAI形式の関数ツール。
オプティマイザーLLMによる、フィードバック駆動型のプロンプト書き換え。
候補によってスコアが改善した場合のみ採用する、開発セットでの選択。
学習実行、書き換えの入力、開発スコア、選択結果を含む進化トレース。
リモートAPIを呼び出さずにフレームワークの動作をテストできる、決定論的なフェイクLLM。

miniEvoAgentのインストール

要件

Python 3.10以降を使用してください。以下のPowerShellコマンドは、リポジトリへの移動、仮想環境の作成と有効化、pipの更新、編集可能モードでのパッケージインストールを行います。

cd D:\Projects\RSIProject\student-project\Evo-repro
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

編集可能モードでインストールすると、ソースを学習・変更している間も、ローカルパッケージの変更をすぐにPython環境で利用できます。

OpenAI互換LLMの設定

デフォルトのOpenAILLMアダプターは、環境変数またはローカルの.envファイルから設定を読み込みます。PowerShellでAPIキーとモデルを設定するには、次のようにします。

$env:OPENAI_API_KEY="your_api_key"
$env:OPENAI_MODEL="gpt-4o-mini"

別のOpenAI互換サービスを使用する場合は、エンドポイントを設定します。

$env:OPENAI_BASE_URL="https://your-compatible-endpoint/v1"

または、.env.exampleを.envにコピーし、同じ設定値を追加してください。

基本的な質問応答エージェントの構築

基本的なエージェントには、LLM、プロンプトテンプレート、出力パーサー、アクションが必要です。エージェントはこれらの部品を、シンプルな実行インターフェースを通じて利用できるようにします。

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser

llm = OpenAILLM()

action = Action(
    name="answer_question",
    prompt_template=PromptTemplate(
        template="Answer the following question:\n\n{question}"
    ),
    llm=llm,
    output_parser=TextOutputParser(),
)

agent = Agent(
    name="qa_agent",
    description="Answers a single user question.",
    action=action,
)

message = agent.execute({
    "question": "What is Retrieval-Augmented Generation?"
})
print(message.content)

agent.executeに渡すquestionキーは、テンプレート内の{question}プレースホルダーに対応します。アクションはプロンプトを生成し、設定されたLLMに送信し、返されたテキストを解析して、その結果を構造化されたメッセージにまとめます。

付属の例を実行することもできます。

python examples\simple_agent.py

呼び出し可能なPythonツールの追加

miniEvoAgentのツールは、Python関数を薄くラップしたものです。各ツールは、モデルが関数呼び出しに利用できるJSONスキーマを提供し、構造化されたToolResultを返します。

パッケージにはget_word_length_toolが含まれており、tools引数を通じてアクションに追加できます。

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
from evo_repro import get_word_length_tool

agent = Agent(
    name="tool_agent",
    description="Answers a question and can use tools.",
    action=Action(
        name="answer_with_tools",
        prompt_template=PromptTemplate(
            template=(
                "Answer the following question. "
                "Use tools when useful:\n\n{question}"
            )
        ),
        llm=OpenAILLM(),
        output_parser=TextOutputParser(),
        tools=[get_word_length_tool],
    ),
)

message = agent.execute({
    "question": 'How many characters are in "retrieval"?'
})

print(message.content)
print(message.metadata["tool_results"])

LLMがサポート対象の関数を要求すると、そのアクションが実行され、ツールの結果が会話に返されます。アクションは、モデルの最終出力を解析する前に、この処理を複数ラウンド実行できます。ツール実行の記録は、message.metadata["tool_results"]から利用できます。

同梱のツール例を次のコマンドで実行します。

python examples\tool_agent.py

プロンプトの自己進化を理解する

自己進化システムは、制御されたフィードバックと評価のサイクルを通じてプロンプトを改善します。

現在のプロンプトをトレーニング例に対して実行します。
予測結果、期待ラベル、評価指標をフィードバック例に変換します。
オプティマイザーLLMを基盤とするPromptRewriterに、候補プロンプトを1つ生成させます。
同じ開発セットで親プロンプトと候補プロンプトの両方を評価します。
PromptSelectorを使って、より良いプロンプトを保持します。
設定された世代数に達するまで、この処理を繰り返します。

1世代だけ実行したい場合はevolve_once(...)を使用します。戻り値はEvolutionRoundTraceです。複数世代を実行して、最終プロンプトと完全な履歴の両方を受け取るにはevolve(...)を使用します。

リモートモデルなしで進化を監査する

このリポジトリには、偽のLLM動作を使用する決定論的な監査例が含まれています。

python examples\evolution_audit.py

出力には、各世代の親プロンプト、トレーニング記録、書き換え入力、候補プロンプト、開発セットでの比較、採用または却下の判断が表示されます。これにより、プロンプト改善を隠れた処理として扱わず、最適化プロセスを検査できます。

QA予測を評価する

組み込みの評価器は、意図的にシンプルなQA指標を3つ提供します。

完全一致：評価器の比較動作に基づき、予測が期待される回答と完全に一致するかを確認します。
トークン単位のF1：予測と期待される回答の間のトークンの重複度を測定します。
正解率：正しい予測の割合を報告します。

これらの指標は、進化ループの検証と実演を目的としています。プロジェクトの説明では、後から特定のベンチマークやタスクに適した評価器に置き換えられるとされています。

テストスイートを実行する

リポジトリのルートからすべてのテストを実行します。

python -m pytest

重点テストスイートでは、エージェント、ツール、進化の動作をカバーしています。可能な場合は偽のLLM実装を使用するため、APIキーやリモートモデルの呼び出しなしで、フレームワークの大部分のロジックを検証できます。

高度なヒント

実環境での実験前に決定論的なテストを使う

プロンプトの選択、ツール処理、進化ロジックを変更する場合は、偽のLLMの例とテストから始めてください。決定論的な出力により失敗を再現しやすくなり、フレームワークの不具合と実際のモデル応答の変動を切り分けられます。

各世代のトレースを確認する

進化の実行を最終プロンプトだけで評価しないでください。記録されたトレーニング実行、書き換え担当に提供されたフィードバック、候補プロンプト、開発スコア、選択判断を確認します。これらの記録から、候補が採用または却下された理由が分かります。

トレーニングと開発の役割を分ける

進化プロセスでは、トレーニング例から書き換え用のフィードバックを作成し、一方で同じ開発セット上で親プロンプトと候補プロンプトを比較します。選択がフレームワークの意図したプロセスに従うよう、実験を準備する際にもこの区分を維持してください。

構造化されたツール結果を確認する

ツール対応エージェントでは、最終テキストだけでなくmessage.metadata["tool_results"]も確認してください。これにより、モデルがツールを選択したか、実行が成功したか、どのような構造化結果が返されたかを検証できます。

必要に応じて互換性のあるカスタムエンドポイントを使う

OPENAI_BASE_URL設定により、OpenAILLMがOpenAI互換エンドポイントを対象にできるようになります。APIキーと選択したモデルが、エンドポイントの要件に合っていることを確認してください。

プロジェクトの現在の範囲を理解する

miniEvoAgentは、EvoAgentXより意図的に範囲を絞っています。現在、ワークフローグラフ、マルチエージェントオーケストレーション、メモリ、Human-in-the-Loop機能、ベンチマーク統合、ビジュアル編集、幅広いツールキットには対応していません。ロードマップには、より高度なワークフロー構成、プロバイダーアダプターの拡充、ベンチマークローダー、再利用可能なツールキット、JSON永続化、追加ドキュメントが含まれていますが、これらは現在の機能ではなく、計画中のものです。

再配布前にライセンスを確認する

現在、プロジェクトにはライセンスファイルが含まれていません。コードを公開または再配布する前に、適切なライセンスを追加してください。

まとめ

miniEvoAgentは、LLMエージェントエンジニアリングへの小規模でテスト可能な入り口を提供します。evo_reproパッケージを使うと、プロンプト駆動型エージェントの構築、OpenAI形式の関数ツールの追加、QAパフォーマンスの測定、失敗に基づくプロンプトの書き換え、開発セットの評価による改善の保持が可能です。コンパクトなアーキテクチャと決定論的な例を備えているため、エージェントの実行とプロンプトの進化が内部でどのように機能するかを学ぶのに特に役立ちます。