Agno FrameworkとPythonによるステートフルなAIエージェントの構築:メモリ、ストレージ、ナレッジベース活用ガイド

AI tutorial - IT technology blog
AI tutorial - IT technology blog

アプローチ比較:ステートレスLLMとステートフルAgnoエージェント

多くの開発者は、プロンプト文字列をAPIエンドポイントに送信してテキスト出力を受け取ることから生成AIの利用を始めます。プルリクエストの要約のような単発のタスクであれば、そのパターンでも問題ありません。しかし、マルチターンの対話を処理したり、社内運用手順書(ランブック)を参照したり、個別のCLIやWebセッションをまたいで過去の設定や好みを記憶したりする必要が生じた途端、その手法は破綻します。

本番システムでは、通常以下の3つのアーキテクチャパターンのいずれかが採用されます。

  • 自前で状態管理を行う素のLLM API: 会話履歴をインメモリのリストに追加しながら、OpenAIやAnthropicに素のJSONペイロードを送信します。ランタイムを完全に制御できる利点がある一方、コンテキストウィンドウの制限、トークンの切り詰め処理、データベースへの永続化、ベクトル検索などを処理するために、およそ300〜500行の定型コード(ボイラープレート)を書く必要があります。
  • 重量級のオーケストレーションフレームワーク: モノリシックなグラフ指向ライブラリは巨大なエコシステムを提供します。しかし、クラス階層が深くチェーンのラッパーが多用されているため、コードが脆くなりがちです。本番環境でリクエストがハングアップした場合、内部コールバックの6層もの階層をトレースしてデバッグするのは骨の折れる作業となります。
  • 軽量なエージェントアーキテクチャ(Agno Framework): Phidataの後継であるAgnoは、標準的なPythonプリミティブをベースに設計されています。不要なミドルウェアや過剰な抽象化層を排除し、LLM、永続ストレージ、メモリ、ベクトルナレッジを単一のまとまりのあるオブジェクトに集約しています。

単発のプロンプトラッパーから信頼性の高いエンタープライズツールへとステップアップするには、こうした状態境界(ステートバウンダリ)の管理を習得することが不可欠です。

ステートフルエージェントにAgno Frameworkを採用するメリットとデメリット

導入前にエージェントフレームワークを適切に評価しておくことで、本番稼働から半年後に発生するような苦痛を伴う再設計を防ぐことができます。実際のエンジニアリング環境におけるAgnoの評価は以下のとおりです。

メリット

  • 明確な状態の分離: Agnoは生の会話ログ(ストレージ)、要約されたユーザー属性(メモリ)、インデックス化された参照資料(ナレッジベース)を明確に区別します。ユーザー名を記憶するためだけに、会話ログを無理やりベクトルコレクションに詰め込むようなハックは不要です。
  • 最小限のオーバーヘッドと高速な実行: 軽量なPydanticスキーマと標準的なPython呼び出しを採用しているため、フレームワークのディスパッチオーバーヘッドは1実行あたり5ms未満に抑えられます。対照的に、重量級のグラフエンジンでは、モデルの呼び出しが始まる前にミドルウェアの処理だけで50ms〜120msのレイテンシが発生することがあります。
  • ネイティブなデータベースアダプター: SQLite、PostgreSQL(pgvector対応)、LanceDB、Qdrant向けのプロダクション対応ドライバーが標準で用意されています。ノートPC上のローカルファイルでプロトタイプを作成し、接続URIを1行変更するだけで、ステージング環境のAurora Postgresクラスタへ切り替えることが可能です。
  • シンプルなデバッグ: 実行トレースが直線的です。エージェントへのクエリが失敗した場合でも、スタックトレースはフレームワーク内部のランタイムループではなく、失敗した関数やデータベース呼び出しを直接指し示します。

トレードオフ

  • 発展途上のエコシステム: 2024年後半にPhidataからリブランディングされた後、コアAPIは安定しました。ただし、2024年初頭のコミュニティチュートリアルには、非推奨となったクラス名や古いインポートパスが記載されていることがよくあります。
  • 統合カタログの規模: LangChainが700以上のコミュニティコネクタを揃えているのに対し、Agnoは主要なプロトコルに絞っています。特殊なエンタープライズSaaS APIを連携させる場合、通常は15行程度のシンプルなカスタムPythonツールを自作する必要があります。

本番を見据えたローカル開発の推奨環境構築

Python 3.10、3.11、または3.12を使用してサンドボックス環境を構築します。ローカルの状態管理には、セッションの永続化にSQLite、ベクトル埋め込み(Embedding)の管理にLanceDBを採用します。どちらもプロセス内に組み込まれて動作し、直接ディスクに永続化されるため、開発中にDockerデーモンやスタンドアロンのデータベースサービスを用意する必要はありません。

ワークスペースと仮想環境を初期化します:

mkdir agno-stateful-agent
cd agno-stateful-agent
python3 -m venv .venv
source .venv/bin/activate

バージョンを固定して依存関係をインストールします:

pip install agno==1.1.3 openai lancedb tantivy pypdf sqlalchemy

OpenAIの認証情報を設定します:

export OPENAI_API_KEY="sk-proj-your-actual-api-key-here"

実装ガイド:メモリ、ストレージ、ナレッジベースを備えたAgnoエージェントのステップ別構築

ここでは、プロセスの再起動をまたいで会話履歴を保持し、開発者の好みを追跡しながら、ローカルの技術運用手順書に基づいて回答を生成する運用アシスタントを構築します。

ステップ1:ディレクトリ構造とサンプルデータの準備

ドキュメントファイル用とSQLiteデータベースファイル用の専用ディレクトリを作成します:

mkdir -p data/docs data/storage

運用セキュリティポリシーを data/docs/company_policy.txt に書き込みます:

ネットワークセキュリティガイドライン:
- エンジニアは90日ごとにVPNクレデンシャルをローテーションする必要があります。
- 本番環境へのデプロイには、シニアエンジニア2名以上による相互承認が必要です。
- データベースのバックアップは毎日02:00 UTCに実行され、マルチリージョンのコールドストレージに365日間アーカイブされます。
- ap-southeast-1リージョンでのKubernetesクラスタのアップグレードには、48時間前のメンテナンス凍結通知が必要です。

ステップ2:ナレッジベースとベクトルデータベースの設定

agent.py という名前のファイルを作成します。Agnoのコアモジュールをインポートし、テキストファイルをインデックス化するために、ハイブリッド検索(密ベクトル検索とTantivyによるキーワードBM25ランキングの組み合わせ)を指定してLanceDBを設定します。

from pathlib import Path
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.storage.agent.sqlite import SqliteAgentStorage
from agno.knowledge.text import TextKnowledgeBase
from agno.vectordb.lancedb import LanceDb, SearchType

# ローカルディスク上に永続ベクトルデータベースを設定
vector_db = LanceDb(
    table_name="knowledge_store",
    uri="data/storage/lancedb",
    search_type=SearchType.hybrid,
)

# ドキュメントフォルダを指定してナレッジベースを初期化
knowledge_base = TextKnowledgeBase(
    path=Path("data/docs"),
    vector_db=vector_db,
)

# 初回実行時にドキュメントをベクトル化。再起動時は既存のインデックスを再利用
knowledge_base.load(recreate=False)

ステップ3:永続ストレージの接続とエージェントの初期化

次に、SQLiteストレージを設定します。read_chat_history=True を設定することで、Agnoは進行中のセッションにおいてSQLiteに問い合わせを行い、過去の対話内容をプロンプトコンテキストに自動でフィードバックします。

# SQLiteに永続セッションテーブルを設定
storage = SqliteAgentStorage(
    table_name="agent_sessions",
    db_file="data/storage/sessions.db",
)

# 各種ステートエンジンを接続してエージェントを構築
assistant = Agent(
    name="DevOps Assistant",
    model=OpenAIChat(id="gpt-4o-mini"),
    knowledge=knowledge_base,
    storage=storage,
    search_knowledge=True,
    read_chat_history=True,
    show_tool_calls=True,
    markdown=True,
    instructions=[
        "運用ルールについては、必ず社内ナレッジベースを最優先で確認してください。",
        "ユーザーから提供された個人情報、インフラの環境設定、サービス名を記憶してください。",
        "技術的な回答は簡潔かつ的確にし、無駄な前置きや相づちは省いてください。",
    ],
)

ステップ4:セッション永続性を備えた対話セッションの実行

状態がプロセスのライフサイクルを超えて維持されることを確認するため、明示的な session_id と user_id を紐づけたCLIループで実行ロジックをラップします。このコードを agent.py に追記します:

def run_chat_session(session_id: str, user_id: str):
    print(f"\n--- アクティブセッション: {session_id} | ユーザー: {user_id} ---")
    print("スクリプトを終了するには 'exit' または 'quit' と入力してください。\n")
    
    while True:
        try:
            user_prompt = input("あなた: ").strip()
            if user_prompt.lower() in ["exit", "quit"]:
                print("セッションを終了しています...")
                break
            if not user_prompt:
                continue
                
            print("\nアシスタント: ", end="")
            assistant.print_response(
                user_prompt,
                session_id=session_id,
                user_id=user_id,
                stream=True,
            )
            print()  # ストリーミング完了後に改行を追加
        except KeyboardInterrupt:
            print("\nセッションが中断されました。")
            break

if __name__ == "__main__":
    # スクリプト再起動後も永続性をテストできるように固定識別子を使用
    SESSION_ID = "infra-ops-room-42"
    USER_ID = "engineer-alex"
    run_chat_session(SESSION_ID, USER_ID)

ステップ5:メモリと情報検索機能の検証

ターミナルから対話ループを起動します:

python agent.py

以下の3つのテストプロンプトを順に実行し、アーキテクチャの各レイヤーを検証します:

  1. ナレッジベースの検索: 「本番データベースのバックアップポリシーはどうなっていますか?」 と質問します。エージェントはLanceDBを検索してポリシー文書を見つけ出し、毎日02:00 UTCのスケジュールと365日間のコールドストレージ保管ルールを回答します。
  2. セッションコンテキスト: 自身の担当範囲を伝えます:「ap-southeast-1のプライマリKubernetesクラスタを管理しています。」。アシスタントは担当リージョンを認識し、そのやり取りをSQLiteに保存します。
  3. プロセスの永続性: exit と入力してPythonプロセスを完全に終了します。その後 python agent.py で再起動し、「私が管理しているクラウドアカウントのリージョンとワークロードは何ですか?」 と質問します。

SQLiteデータベースがセッション infra-ops-room-42 の過去のやり取りを保持しているため、エージェントは以前のメッセージを即座に取得します。特別なプロンプトエンジニアリングの小細工を施すことなく、あなたが ap-southeast-1 でKubernetesを管理していることを正確に把握して回答します。

Share: