AIエージェント（LLMを使って自律的にタスクを繰り返し実行するプログラム）を夜間バッチのように動かす運用が増えています。しかし一晩で数十ドル分のAPI料金が同じ失敗テストにハマったまま消費される、といった事故は珍しくありません。本記事はこの問題に対する一つの解決アプローチであるAgentic Ledgerを、アーキテクチャ選定と非機能要件の観点から読み解きます。
対象読者は、LLMエージェントやマルチエージェント構成（複数のAIエージェントが連携してタスクを分担する構成）を本番または検証環境で動かしているエンジニアです。コスト超過やループ暴走をどう検知し、どう防ぐかの設計判断に迷っている方の参考になれば幸いです。
何が問題で、なぜ設計論として扱う価値があるか
AIエージェントは人手を介さず、LLM呼び出しをループさせ、ツールを使い、サブエージェントを生成しながら動きます。
この「見えないところで実行される」性質が、非機能要件としての観測性（オブザーバビリティ、システムの内部状態を外部から把握できる性質）を難しくしています。
既存の多くの観測ツールは、SDK（開発者がコードに組み込むライブラリ）を使ったインストルメンテーション（計測コードの埋め込み）を要求し、特定のフレームワークに紐づいています。つまり、フレームワークを切り替えるたびに計測方法も作り直す必要が出てきます。これはベンダーロックインに近い技術的負債を生みやすい構造です。
Agentic Ledgerはこの前提を覆し、「コードを一切変更せず、すべてのトラフィックを観測する」という方針を取っています。設計としての要点は、SDK型ではなくプロキシ型の観測基盤を選んだことにあります。
技術的な仕組みを段階的に見る
Agentic Ledgerの正体は、エージェントとLLMプロバイダーの間に挟まる透過型プロキシ（通信内容を中継しつつ、送受信データを記録する仲介サーバー）です。
エージェント側の設定でbase_urlをこのプロキシに向けるだけで、リクエストとレスポンスがすべて記録されます。エージェント自身は、プロキシの存在に気づきません。
pip install -U agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com
python -m agenticledger.proxyこの仕組みが成立するのは、どのフレームワークもプロバイダーも、最終的にはHTTP通信という共通層を経由するためです。SDKに依存する観測ツールは各フレームワークの内部APIに合わせて実装を変える必要がありますが、HTTPレイヤーで観測すれば実装を共通化できます。これはAPI連携における「最小共通分母」を狙った設計判断といえます。
記録されたデータはSQLite（軽量なファイル型データベース）またはPostgreSQLに保存され、ダッシュボードとAPIから確認できます。プロンプトの内容も含めてローカルに残る「ローカルファースト」の設計です。ライセンスはMITで、外部にデータを送信しない前提が明記されています。
コスト計算は呼び出しごと、セッションごと、エージェントごと、日次で集計され、プロンプトキャッシュの読み書きもプロバイダーごとの課金方式に合わせて計算されます。キャッシュ課金はコーディング系エージェントの実費用の大半を占める部分であり、多くの観測ツールがここを見落としている点として明記されています。
もう一つの特徴が「ループ検知」です。生のトラフィックからReAct型のスレッド（推論と行動を繰り返すパターン）を再構築し、同じツールを同じ引数で繰り返し呼ぶような無駄なループを検出します。ブロックモードでは、暴走したループにHTTP 429（リクエスト過多エラー）を返し、サーキットブレーカー（過負荷時に処理を遮断する仕組み）として機能します。
予算管理の機能では、セッション単位・エージェント単位・日次でUSDの上限を設定し、プロバイダーに到達する前のリクエスト経路上で強制できます。さらにMCPサーバー（Model Context Protocol、AIエージェントと外部ツールを接続する標準規格）を備え、エージェント自身が「このセッションは予算超過か」を問い合わせられる構造も持っています。
関連技術との比較で見えるトレードオフ
OpenTelemetry（分散システムの計測データを標準化する規格）のGenAI拡張スパンにも対応しており、既にOTel計装済みのフレームワークからはそのまま取り込めます。
ここで整理すべきは、プロキシ型とSDK計装型のトレードオフです。SDK型は呼び出しの意味的な文脈（どのチェーンのどのステップか）を正確に取れる一方、フレームワークごとの実装保守コストがかかります。
プロキシ型はHTTPというコードを見ずに動くため導入コストが低い代わりに、意味的な文脈をヒューリスティック（経験的な推定ロジック）で再構築する必要があります。ループ検知が「推測」である以上、誤検知や見逃しのリスクは設計上避けられません。
可用性の観点では、プロキシ自体が単一障害点になる点も見逃せません。プロキシが落ちればエージェントのLLM呼び出しも止まるため、本番投入時はプロキシの死活監視や冗長化構成を別途検討する必要があります。
| 観点 | SDK計装型 | プロキシ型(Agentic Ledger) |
|---|---|---|
| 導入コスト | フレームワークごとに実装 | base_url変更のみ |
| 文脈の精度 | 高い(意味情報を直接取得) | 推定に依存 |
| 単一障害点リスク | 低い(アプリ内蔵) | プロキシ層が新たな障害点 |
| データの所在 | ツール依存 | ローカル/自前DBに固定可能 |
今日確認できること
導入を検討する場合、まずバージョンと成熟度の確認が欠かせません。公開時点でv0.4.0のソロプロジェクトであり、テストは100件以上・3系統のPython CI・SBOM付きの署名済みマルチアーキイメージが整備されている一方、大規模運用実績はまだ蓄積段階です。
本番投入前に確認すべき項目は次の通りです。
- 対応バージョンとリリースノート（GitHubのリリースページでv0.4.0以降の変更内容を確認する）
- 自分たちのプロバイダー(OpenAI, Anthropic, OpenRouterなど)がプロキシ経由で正しく課金と一致するか、実際に数回呼び出して手元の請求と突き合わせる
- ブロックモードを有効にした場合、正常なリトライ処理まで誤って遮断しないか、ステップ予算の閾値を自分たちのエージェント設計に合わせて調整する
- プロキシの可用性をどう担保するか(ヘルスチェック、フェイルオープンの是非)を運用チームで決めておく
Dockerで試す場合は次のコマンドで起動できます。
docker run -p 8000:8000 \
-e AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com \
-v $(pwd)/data:/data \
ghcr.io/shekharbhardwaj/agentic-ledger:latestClaude Codeのようなコーディングエージェントであれば、環境変数一つで組み込めます。
export ANTHROPIC_BASE_URL=http://localhost:8000
claudeまとめ
Agentic Ledgerは、AIエージェントのコスト暴走とループ検知という非機能要件に、SDK計装ではなくHTTPプロキシという層で答えた設計です。
導入コストの低さと単一障害点リスクは表裏一体であり、本番導入前にはプロキシの可用性設計を別途詰める必要があります。
手を動かすなら、まず開発環境でDocker起動し、手元のプロバイダー請求とダッシュボードの数値が一致するかを確認するところから始めるとよさそうです。
数値のズレがあればそれ自体が設計上の要注意ポイントになるはずです。