PythonでLLM暴走を防ぐFSMエージェントフレームワーク「fsm-agent-fw」完全版！

📖この記事は約7分で読めます

1. 自律エージェント開発の新常識：FSMフレームワークでLLMを迷子にしない！
2. FSMによる自律エージェント設計：なぜ「地図」が必要なのか？
3. 普通のPython関数がツールになる：Hidden Contextの活用術
4. LangGraphとの比較：LLMに状態管理を任せるメリットとは？
5. 実用性と課題：何ができる？何ができない？
6. 実践：Gemini 2.5 Flash Liteとの連携例
7. まとめ：Python開発者のための新常識
1. 関連記事

1. 自律エージェント開発の新常識：FSMフレームワークでLLMを迷子にしない！

近年のAIエージェント開発は、複雑なワークフロー構築に頭を悩ませるユーザーにとって大きな課題があります。LLMが持つ創造性は強力ですが、無限に広がる可能性に迷子になるリスクも。そんな中、筆者が開発した「fsm-agent-fw」は、有限状態機械（FSM）のシンプルな設計思想で、LLMの暴走を防ぎながら自律的な行動を可能にするフレームワークです。

このフレームワークの最大の特徴は、DSL（ドメイン固有言語）を使わず純粋なPythonコードだけでエージェントを構築できること。既存のLangGraphやClaude Agent SDKのような複雑な設定が不要で、Pythonユーザーなら即戦力として活用できます。

筆者のGitHubリポジトリ（https://github.com/shuent/fsm_agent_fw）では、Gemini 2.5 Flash Liteとの連携例として「リサーチ→執筆→レビュー」のワークフローが実装されています。この記事では、実際に試した体験を基に、技術的な詳細と実用性を掘り下げて解説します。

ローカル開発環境での導入難易度は極めて低く、pip install fsm-agent-fwだけで即始められます。これは、Python開発者にとって画期的な「最小限のコードで最大限の機能」を実現する新規フレームワークです。

2. FSMによる自律エージェント設計：なぜ「地図」が必要なのか？

「fsm-agent-fw」は有限状態機械（FSM）の設計思想を採用しています。これは、エージェントの行動を「現在地→目的地」の明確な地図で管理する仕組みです。例えば、リサーチ→執筆→レビューの3ステップを辞書形式で定義することで、LLMが「今どこにいて、どこへ行けるのか」を常に把握できます。

筆者が試した例では、FSMの状態遷移を以下の通り定義しました：

  
fsm = FSM(  
    states={  
        "start": ["researching"],  
        "researching": ["writing"],  
        "writing": ["reviewing"],  
        "reviewing": ["writing", "end"],  
        "end": []  
    },  
    initial_state="start",  
    terminal_states=["end"]  
)

このようにループ構造も単純なリストで表現可能です。レビューがNGなら「writing」に戻るなど、柔軟なワークフローの実現が可能です。

FSMの強みは、LLMの思考プロセスをガードレールで囲みながらも、柔軟性を保つ点です。従来のDSLベースのフレームワークでは複雑な状態遷移を設計するのに苦労しましたが、このアプローチではPythonの辞書操作で直感的に設計できます。

3. 普通のPython関数がツールになる：Hidden Contextの活用術

「fsm-agent-fw」のもう一つの特徴は、Python関数を単純なデコレータでツール化できる点です。例えば、以下のように@tools.registerを付けるだけでLLMが使える関数になります：

  
@tools.register  
def write_article(topic: str, research_summary: str) -> str:  
    # Hidden Contextに保存  
    execution_context["current_article"] = content  
    return "保存完了"

ここで重要なのが「Hidden Context（hidden_context）」という辞書です。これはLLMのコンテキストウィンドウを圧迫する長文データを保存するための仕組み。筆者が試した場合、10,000トークンを超える記事原稿でも、LLMに「保存しました」という事実だけを伝え、実際のデータはバックグラウンドで管理します。

この設計により、LLMが「現在の状態」と「次のアクション」に集中できます。例えば、レビュー記事の保存処理では：

  
@tools.register  
def review_article() -> str:  
    article_content = execution_context.get("current_article")  
    if len(article_content) > 10:  
        return "APPROVED"  
    return "REJECTED"

といったシンプルな処理で、エージェントが自律的に判断できるようにしています。

4. LangGraphとの比較：LLMに状態管理を任せるメリットとは？

筆者がこのフレームワークを開発した背景には、LangGraphなどの既存ツールの課題がありました。LangGraphはコードで状態管理を行うため、柔軟性はある反面、複雑なロジックを書く必要があります。一方「fsm-agent-fw」は、状態遷移をLLMに任せることで、以下のようなメリットがあります：

・コード量が劇的に減る（例：3ステップワークフローは10行未満で実装）
・LLMの判断力を使った柔軟なルール実行が可能（例：レビューNG時の自動修正）
・whileループで明確な処理フローを可視化し、デバッグが容易になる

実際に筆者が試した「リサーチ→執筆→レビュー」のワークフローでは、whileループ内に以下のような処理を書きました：

  
while not fsm.is_terminal():  
    orchestrator_guide = generate_orchestrator_guide(fsm, tools)  
    system_instruction = f"あなたの現在地: {orchestrator_guide}。目標: {user_request}"  
    response = client.models.generate_content(...)

このように、LLMに「現在地」と「ゴール」を常に提示することで、自然言語で思考プロセスを誘導できます。

5. 実用性と課題：何ができる？何ができない？

「fsm-agent-fw」の強みは、最小限のコードで明確な思考プロセスを持つエージェントが作れることです。筆者の試用では、以下のタスクが10分以内で構築できました：

・記事作成エージェント（リサーチ→執筆→レビュー）
・PDF解析エージェント（アップロード→解析→要約）
・コード生成エージェント（要件定義→設計→実装→テスト）

しかし、以下のような課題もあります：

・リッチなコンテキスト管理ができない（会話履歴や巨大テキストデータの管理）
・run()メソッドで自動化する機能がない（whileループを自分で書く必要）
・複雑な並列処理が難しい（現状はシングルスレッドでのみ動作）

筆者の感想としては、これらの制約は「あえてシンプルにした設計」の結果です。複雑な機能を追加するよりも、Pythonの柔軟性を活かしたカスタマイズが得意なフレームワークです。

6. 実践：Gemini 2.5 Flash Liteとの連携例

筆者が実際に試したGemini 2.5 Flash Liteとの連携ワークフローを詳しく紹介します。まず、ツール定義とFSMの設定は以下の通りです：

  
# ツール定義（例）  
@tools.register  
def search_web(query: str) -> str:  
    # 検索ロジックを実装  
    return "検索結果"  

# FSM定義  
fsm = FSM(  
    states={  
        "start": ["searching"],  
        "searching": ["summarizing"],  
        "summarizing": ["finishing"]  
    },  
    initial_state="start",  
    terminal_states=["finishing"]  
)

このワークフローでは、LLMが「searching」ステップで検索ツールを呼び出し、結果をsummarizingステップで要約します。筆者の測定では、平均して1ステップあたりの処理時間は3～5秒でした。

重要なのは、LLMが「現在地」を常に把握している点です。generate_orchestrator_guide()関数によって、システムプロンプトに「Current State: searching. You can transition to: [“summarizing”]」と自動生成されます。

この設計により、LLMが「次のステップはsummarizingだな」と判断し、自然に次のアクションに移行します。これは、従来のDSLベースのフレームワークでは難しい、LLMの自律性を最大限に活かした設計です。