Agno 再入門 – 機能 : エージェント・ストレージ, 運用可視性

by

エージェントは、db パラメータで設定されたデータベースに、生成して使用するすべてのデータポイントを永続化できます。セッション、メモリ、ナレッジ、トレース、スケジュール、承認、学習データ、さらには使用状況メトリクスも保存可能です。

Agno 再入門 – 機能 : エージェント・ストレージ, 運用可視性

作成 : クラスキャット・セールスインフォメーション
作成日時 : 06/08/2026
バージョン : v2.6.12

* 本記事は docs.agno.com の以下のページを参考にしています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

Agno 再入門 – 機能 : エージェント・ストレージ

セッション、メモリ、ナレッジ、トレースをあらゆるデータベース・バックエンドに保存できます。

エージェントは、db パラメータで設定されたデータベースに、生成して使用するすべてのデータポイントを永続化できます。セッション、メモリ、ナレッジ、トレース、スケジュール、承認、学習データ、さらには使用状況メトリクスも保存可能です。

プリミティブ (エージェント、チーム、ワークフロー) と AgentOS は db パラメータを受け取ります。JSON ファイル (ローカルまたはクラウド)、組み込みデータベース (SQLite)、リレーショナルデータベース (Postgres、MySQL)、ドキュメントデータベース (MongoDB)、キーバリュー・データベース（Redis、DynamoDB、Firestore) または分散データベース (SingleStore) から選択できます。

from agno.db.postgres import PostgresDb
from agno.os import AgentOS

db = PostgresDb(db_url="postgresql://user:pass@host:5432/agno")

agent_os = AgentOS(agents=[agent], db=db)

db パラメータを設定すると、AgentOS は初回起動時にテーブルとインデックスを作成します。

 

What gets stored (保存されるもの)

  • agno_sessions – (user_id, session_id) ごとの会話履歴

  • agno_memories – エージェントが保持することを決定したユーザーメモリ

  • agno_knowledge – 埋め込み

  • agno_traces, agno_spans – OpenTelemetry トレース

  • agno_approvals – 保留中および解決済みの HITL リクエスト

  • agno_schedules, agno_schedule_runs – Cronジョブ

  • agno_metrics, agno_eval_runs – メトリクスと評価結果

※ バックエンド固有の名称は異なる場合があります。

※ スキーマの変更は一般的に追加的なものです。

 

バックエンドの選択

PostgresDb は殆どのチュートリアルでデフォルトとして使用され、本番環境でも推奨されるデータベースです。PgVector との相性もよく、リレーショナル・データと埋め込みを同じエンジン上で保持できます。

  • (バックエンド – When to use)

  • PostgresDb – 本番環境向け。ベクトル + リレーショナル DB を一つで両立。

  • SqliteDb – ローカル開発、単一ユーザー・デモ、エッジ環境へのデプロイ向け

  • MongoDb – Already on Mongo

  • MySQLDb – Already on MySQL

  • SingleStoreDb – 単一エンジンで「ベクトル + 分析処理」。高スループット用途向け

  • RedisDb -　キャッシュ用途に適し、一時的なセッション管理向け

  • DynamoDb – AWS-ネイティブ、サーバレス

  • FirestoreDb – GCP-ネイティブ、サーバレス

  • GCSJsonDb – 安価なコールドストレージ、クラウドストレージにおける JSON 形式のナレッジ

  • InMemoryDb – テスト、一時的なデモ

Neon や Supabase などの PostgreSQL 互換マネージドサービスは、PostgresDb から直接利用できます。db_url を対象のマネージドインスタンスに向けてください。非同期版（AsyncPostgresDb, AsyncSqliteDb, AsyncMongoDb, AsyncMySQLDb）については Database を参照してください。

 

ベクトルストレージ

ナレッジにはベクトルストレージが必要で、agno はあらゆるベクトルデータベースを標準でサポートしています。

from agno.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

agent = Agent(
    db=db,
    knowledge=Knowledge(
        vector_db=PgVector(
            table_name="my_kb",
            db_url=DB_URL,
            search_type="hybrid",   # vector + BM25
        ),
    ),
)

その他のオプション : LanceDB, Qdrant, Weaviate, Pinecone, Chroma, MongoDB Atlas, Cosmos, Cassandra, ClickHouse, SurrealDB, Milvus。See Vector Stores.

殆どの本番環境の AgentOS デプロイおいては、同一の Postgres 上の `PgVector + PostgresDb` が最適なデフォルト構成です。データベースは 1 つで、ハイブリッド検索、トランザクション読み取りが可能で、追加のサービス運用は不要です。

 

Agno 再入門 – 機能 : エージェント運用可視性 (オブザーバビリティ)

トレース、実行履歴、監査ログを独自のデータベースに保存できます。Agno でネイティブ対応しています。

AgentOS には、すべての実行をデータベースにルーティングする組み込みのトレースプロバイダを備えています。外部の監視 (observability) SaaS に登録したり、API キーを管理したり、データを外部に送信したりする必要はありません。トレースは、セッションやメモリに使用しているのと同じデータベース内の agno_traces と agno_spans に保存されます。

from agno.os import AgentOS

agent_os = AgentOS(
    agents=[agent],
    db=db,
    tracing=True,
)

実行ごとにトレースツリーが生成されます: LLM 呼び出し、各ツール、フック、取得、そしてチーム委任 (delegation) のスパン。トレース機能は OpenTelemetry に基づいて構築されており、コード変更なしでエージェントを監視 (instrument) できます。

 

Your data never leaves your db

これが AgentOS のトレース機能とホスト型オブザーバビリティ・プラットフォームとの違いです。

AgentOS トレース ホスト型オブザーバビリティ SaaS
トレースの保存場所 あなたのデータベース ベンダー・サーバ
データ送信 (egress) None すべてのプロンプト、ツール呼び出し、応答がユーザネットワークから送信
ベンダー依存 None ダウンした場合や支払いを停止した場合、オブザーバビリティは停止
料金モデル 既存データベース シート (アカウント) or イベント単位の課金
クエリ テーブルへの直接 SQL クエリ ベンダー API と UI のみ

プロンプト、ツール引数、モデル出力には、顧客の個人情報 (PII)、内部データ、独自のロジックが含まれている場合が多いです。AgentOS のトレース機能を使用すれば、これらの情報はネットワーク境界を越えることはありません。データの所有権はユーザにあり、保持期間も管理でき、既に実行しているデータベースツールでクエリを行うことができます。

 

What gets captured

  • (スパン – 属性)

  • 実行 (Run) – agent_id, user_id, session_id, model, latency, status

  • LLM 呼び出し – モデル、プロンプトトークン、補完 (completion) トークン、temperature、ツール呼び出し結果

  • ツール – ツール名、引数、結果、実行時間、例外 (存在する場合)

  • プリ／ポストフック – フック名、実行時間、変更された入力／出力

  • 検索 – クエリ、ベクトルストア、k、返されたドキュメント、スコア

  • チーム – 委任、メンバー名、モード、サブ実行トレース

トレースは OpenTelemetry のセマンティック規約に従うため、直接クエリを実行できます :

-- Top 10 slowest span types by average duration
SELECT
    name,
    AVG(duration_ms) AS avg_ms,
    COUNT(*) AS calls
FROM agno_spans
GROUP BY name
ORDER BY avg_ms DESC
LIMIT 10;

 

In the AgentOS UI

コントロールプレーンにも同じトレースが視覚的に表示されます。実行をクリックすると、完全なツリーが表示されます: LLM ホップ、入力と出力を含むツール呼び出し、フック、サブエージェントのトレース。ユーザー、セッション、または時間範囲でフィルタリングできます。

 

以上