AgentLedger

AgentLedger — エージェントごとの支出管理

x402／MPP／API キーを介した AI エージェントの支出を追跡し、予算上限を設定して、 異常な支出を検知し、監査証跡を保持します。「エージェント支出の Datadog」―― エージェント開発者から寄せられた、検証済みコミュニティ要望の第 1 位です。

🎯 無料プラン：ワークスペースあたり 3 エージェント、カード不要、ログイン不要です。 POST /start でワークスペースが作成され、キーが一度だけ表示されます。

AgentLedger に接続する

接続時に認証ハンドシェイクは不要です。初めて書き込みを行う前に workspace_key が必要です。次のいずれかの方法で取得できます。

• ウォレットを持つ自律型エージェント： X-PAYMENT ヘッダーを付けて POST /v1/billing/x402 を実行します。 支払いを行うウォレットがワークスペースの ID になります。 メールアドレスもログインも不要で、人間が介在する必要もありません。
• 人間： /start を開きます。 登録、ログイン、カードは不要です。workspace_key はその場で一度だけ表示され、 ページにはそのワークスペースのアップグレードリンクも表示されます。

キーによって新しい agent_ids を登録できます。登録するたびに、そのエージェント専用の agent_secret が生成されます。このシークレットが以降のすべての書き込みの認証に使われます。 そのエージェントでは、workspace_key は二度と必要ありません。

Claude Code：

claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/

Codex：

codex mcp add agent-ledger --url https://aiagentscity.com/mcp/

Cursor — mcp.json にマージします：

{
  "mcpServers": {
    "agent-ledger": {
      "url": "https://aiagentscity.com/mcp/"
    }
  }
}

その他の MCP クライアント： ストリーム可能な HTTP リモートの https://aiagentscity.com/mcp/ を指定します。ヘッダーは不要で、 接続時の認証ハンドシェイクも必要ありません。

接続後に試せるプロンプト：

• 「Claude Code の支出を追跡して」
• 「いずれかのエージェントが 1 日あたり 50 ドルを超えたら通知して」
• 「週次の損益レポート」

試してみる — キーを取得して、追跡を開始する

# Track a spend — the FIRST call for a new agent_id CLAIMS it, so it needs
# your workspace_key, and it returns that agent's agent_secret.
# Save the secret: every later write (track/budget) to this agent_id uses it
# instead, and needs no workspace_key.
curl -X POST https://aiagentscity.com/v1/track \
  -H "Content-Type: application/json" \
  -H "AL-API-Version: 2026-09-01" \
  -d '{"agent_id":"YOUR_AGENT_ID","rail":"x402","amount_cents":100,"service":"search_query","workspace_key":"YOUR_WORKSPACE_KEY"}'

# Set a monthly budget cap — pass the agent_secret from above
curl -X POST https://aiagentscity.com/v1/budget \
  -H "Content-Type: application/json" \
  -H "AL-API-Version: 2026-09-01" \
  -d '{"agent_id":"YOUR_AGENT_ID","monthly_cents":5000,"agent_secret":"YOUR_SAVED_SECRET"}'

# Spend report + anomalies — requires the agent_secret from above
curl https://aiagentscity.com/v1/report/YOUR_AGENT_ID \
  -H "X-Agent-Secret: YOUR_SAVED_SECRET"

まず内容を確認したい場合は？ すべてのエージェントに、人が読めるページがあります（シークレットをヘッダーとして送信します。JSON の取得に curl は不要です）。 https://aiagentscity.com/v1/report/YOUR_AGENT_ID/html

/v1/report、/v1/tokens、/v1/alerts には、X-Agent-Secret: <agent's secret> または X-Workspace-Key: <the workspace's key> のいずれかが必要です。 認証情報がない場合や誤っている場合は 401 が返されます。認証はヘッダーのみです。Cookie や セッションによる方法はなく、REST と MCP のどちらにも未認証で読み取る手段はありません。 これにより、第三者が他のユーザーの agent_id を読み取ったり上書きしたりできないようにしています。

これは、以前の AgentLedger の「リンクを共有すれば誰でも読める」という動作からの意図的な変更です。 顧客間の確実な分離を実現するために、その動作を変更しました。

2 行で、従量制・上限付きエージェントに

pip install "aiagentscity-ledger[wrapper]"      # client only: the wrapper + the CLI
agent-ledger init --agent YOUR_AGENT_ID       # mints a workspace, claims the agent, writes .env

from openai import OpenAI
import agentledger

client = agentledger.wrap(OpenAI(api_key=OPENAI_KEY),
                          agent_id="YOUR_AGENT_ID", agent_secret="<from .env>")

統合はこれだけです。wrap() はクライアントのベース URL をプロキシに切り替え、 2 つの ID ヘッダーを追加します。SDK にパッチを適用したりサブクラス化したりしないため、 ストリーミング、ツール呼び出し、再試行はこれまでどおり動作します。Anthropic のクライアントも同様に動作します。 プロバイダーキーはそのまま転送され、保存されることはありません。

Python SDK を使用していない場合は、X-AL-Agent と X-AL-Secret を付けて、 OpenAI または Anthropic 互換のクライアントを <base>/proxy/openai/v1/ （または /proxy/anthropic）に指定してください。

インストール（MCP クライアント）

{
  "mcpServers": {
    "agent-ledger": {
      "url": "https://aiagentscity.com/mcp/"
    }
  }
}

ツール：ledger_track、ledger_set_budget、ledger_check_spend、ledger_report、ledger_alerts、 ledger_price、ledger_proxy_attach、ledger_api_docs、ledger_examples、 ledger_request_approval、ledger_approvals、ledger_approval_decide、 ledger_start、ledger_rotate_secret、ledger_revoke_secret。

エージェント向け API リファレンス：llms.txt 実行可能なコードレシピ：recipes.md

機能

• 複数の決済レールに中立 — x402、MPP、API キー、手動入力に対応し、特定の決済レールに縛られません
• トークン数からコストを自動計算 — トークン数とモデルを送信すると、金額を自動計算します； 価格が設定されていないモデルは、無料として黙って記録するのではなく拒否されます
• 予算の適用 — 上限の80%で警告し、それを超える台帳への書き込みを拒否します
• あらゆるプロバイダーに対応、コード変更不要の設定 — providers.json にプロキシが転送できるベンダーを記載します （OpenAI、Anthropic、DeepSeek、Moonshotを例として同梱）；追加するには設定を編集します
• プロキシによる適用（実際に機能します） — プロバイダーの base_url を /proxy/{provider} に設定すると、 上限を超える呼び出しはプロバイダーへの接続前に拒否されるため、費用は発生しません。パススルー方式です。プロバイダーキーは転送されますが、保存されません
• 異常検知 — エージェントごとの支出急増アラート
• 確実に届くアラート — 予算警告（80%）、実際の予算超過によるブロック、異常を、お客様が所有する http(s) webhook にプッシュします；失敗を含め、配信の試行はすべて記録されます
• 監査証跡 — すべての記録を決済レール、サービス、タイムスタンプとともに永続化します
• 共有可能なレポートリンク — POST /v1/report/{agent_id}/share で、有効期限付きの読み取り専用URLを発行します。ヘッダーや認証情報なしで通常のブラウザーから開けます；一度の呼び出しですべてを無効化できます
• 認証情報の復旧 — agent_secret を紛失しても agent_id が使えなくなることはありません。workspace_key で交換用のシークレットを発行（POST /v1/agents/{agent_id}/rotate-secret）するか、支出履歴を維持したまま取り消せます
• ワークスペースごとの分離 — エージェント、上限、サブスクリプションはワークスペースごとに管理され、顧客間で共有されることはありません
• 無料プラン：ワークスペースあたり3エージェント — 有料で利用できるのはエージェントレールのみです： POST /v1/billing/x402 で、$0.10 USDC の再更新可能な24時間Proパス（ウォレットのワークスペースでエージェント数が無制限）を購入できます。人間向けのチェックアウトも月額プランもありません。 サービスの請求額は X402_MINT_PRICE（環境変数、デフォルトは $0.10）で、現在の金額は /.well-known/x402 に公開されています — 古くなりがちなこの記述を信頼するのではなく、そちらで確認してください。

アーキテクチャ

• コアエンジン（ledger_engine.py）：エージェントごとの JSONL 台帳、予算状態、アラートログ、エージェントごとのシークレット（ensure_agent_secret — 新しい claim には workspace_key が必要です。以降の書き込みごとに、そのエージェント専用の agent_secret を発行します）
• ID 管理（identity.py）：呼び出し元を解決する唯一の場所です。ヘッダーで渡される agent_secret または workspace_key を使用します。各ゲート（claim、読み取り、請求）は独自のチェックを実装せず、この処理を呼び出します。
• ワークスペース（workspace_engine.py）：顧客ごとの ID とプラン状態です。ウォレットアドレス（x402、人間を介しません）をキーにするか、通常の POST /start ワークスペースではキーを使用しません。
• REST API（api_server.py、FastAPI）：アプリの作成、メタエンドポイント、人間向けの開始／購入ページ、ルーターの組み込みを担当します。エンドポイントは routes_agents.py と routes_billing.py にあります。ホスト型の streamable-http MCP は /mcp/ で提供します。
  • /v1/agents（テナントをまたぐ完全な一覧）はオーナー専用で、X-Al-Admin ヘッダーが必要です。
  • 読み取り（/v1/report、/v1/tokens、/v1/alerts）には X-Agent-Secret または X-Workspace-Key が必要です。MCP の読み取りツールも同じ 2 つの認証情報をパラメーターとして受け取るため、どちらのインターフェースにも認証なしで読み取れる経路はありません。
  • 認証情報のライフサイクル：POST /v1/agents/{agent_id}/rotate-secret と /revoke-secret は workspace_key のみで実行できます。エージェント自身の agent_secret では、意図的にローテーションできないようにしています。ローテーション可能だと、エージェントの認証情報が漏えいした場合に、本来の所有者が永久に締め出される可能性があるためです。失効時は保存済みのシークレットを削除せず上書きするため、agent_id の claim 状態は維持され、別のワークスペースに取得されることはありません。
• 入力検証：agent_id は [A-Za-z0-9._-]{1,64} に制限されます（パストラバーサル対策）。rail は mpp/x402/api_key/manual の許可リストに限定され、amount と予算の上限は [0、$100k] の範囲です。
• Stripe webhook は fail-closed です。HMAC 署名が STRIPE_WEBHOOK_SECRET_AL に照らして検証されない限り、イベントは拒否されます。人間向けのチェックアウトエンドポイントは廃止されています（410）。webhook は、削除時点ですでに進行中だったサブスクリプションを完了できるよう、引き続き接続されています。検証済みの pro チェックアウトでは、client_reference_id を使ってそのワークスペースを有料プランに設定します。

お問い合わせ

[email protected]