AgentLedger

AgentLedger — 按 Agent 管理支出

跟踪 AI Agent 通过 x402/MPP/API 密钥通道产生的支出，设置预算上限，发现 异常支出并保留审计记录。「Agent 支出的 Datadog」—— Agent 构建者最希望拥有的功能，经社区验证排名第 1。

🎯 免费套餐：每个工作区可用 3 个 Agent，无需银行卡，无需登录。 POST /start 会创建工作区，并仅显示一次密钥。

连接 AgentLedger

连接时无需身份验证握手。首次写入前，你需要一个 workspace_key，可通过以下两种方式获取：

• 拥有钱包的自主 Agent： 使用 X-PAYMENT 标头调用 POST /v1/billing/x402。付款钱包将成为工作区身份—— 无需电子邮箱，无需登录，也无需人工介入。
• 人工用户： 打开 /start——无需 注册、无需登录、无需银行卡。workspace_key 会在该页面上显示一次，页面还会提供该工作区的升级链接。

该密钥用于认领新的 agent_id。每次认领都会为对应 Agent 创建专属的 agent_secret，后续每次写入都通过它进行身份验证——该 Agent 此后不再需要 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 支出”
• “任何 Agent 每日支出超过 $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"

只想查看内容？ 每个 Agent 都有一个便于阅读的页面（将密钥作为标头发送；获取 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 早期「分享链接，任何人都能读取」的行为—— 这样做是为了确保不同客户之间真正隔离。

两行代码，让 Agent 支出可计量且受预算限制

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 重定向到代理， 并添加两个身份标头——它不会修补或继承 SDK，因此流式传输、工具 调用和重试的行为与之前完全一致。Anthropic 客户端的用法也完全相同。你的 服务提供商密钥会原样转发，且绝不会被存储。

如果不使用 Python SDK？将任何兼容 OpenAI 或 Anthropic 的客户端指向 <base>/proxy/openai/v1/（或 /proxy/anthropic），并提供 X-AL-Agent 和 X-AL-Secret。

安装（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。

面向 Agent 的 API 参考：llms.txt 可运行的代码示例：recipes.md

功能

• 多支付通道中立 — 支持 x402、MPP、API 密钥和手动录入；不受限于单一支付通道
• Token→费用自动定价 — 发送 Token 和模型名称，即可自动计算费用；未定价的模型会被拒绝，而不会被悄悄记为免费
• 预算执行 — 达到上限的 80% 时发出警告，并拒绝会导致超出上限的账本写入
• 支持任意提供商，无需修改代码 — providers.json 列出代理可转发到的服务商（OpenAI、Anthropic、DeepSeek 和 Moonshot 提供了示例配置）；添加服务商只需修改配置
• 代理执行（真正生效） — 将服务商的 base_url 指向 /proxy/{provider}，任何会导致超出上限的调用都会在联系服务商之前被拒绝，因此不会产生费用。请求透传：转发你的服务商密钥，但不会存储
• 异常检测 — 按 Agent 监测支出激增并发出提醒
• 确保送达的提醒 — 将预算警告（80%）、实际预算拦截和异常情况推送到你拥有的 http(s) webhook；每次投递尝试都会记录回执，包括失败情况
• 审计追踪 — 每条记录都会持久化保存，并包含支付通道、服务和时间戳
• 可分享的报告链接 — POST /v1/report/{agent_id}/share 会生成只读的限时 URL，可在普通浏览器中打开（无需请求头或凭据）；一次调用即可撤销所有链接
• 凭据恢复 — agent_secret 丢失不会导致 agent_id 无法使用：可通过 workspace_key 生成替代密钥（POST /v1/agents/{agent_id}/rotate-secret），或撤销该密钥并保留支出历史记录
• 按工作区隔离 — 你的 Agent、上限和订阅均独立；不同客户之间不会共享任何内容
• 免费套餐：每个工作区 3 个 Agent — 唯一的付费方式是 Agent 支付通道：POST /v1/billing/x402 可支付 $0.10 USDC，购买可续期的 24 小时 Pro 通行证（该钱包所属工作区内的 Agent 数量不限）。没有人工结账或月度套餐。服务收费金额由 X402_MINT_PRICE（环境变量，默认值为 $0.10）决定，实时价格发布于 /.well-known/x402 — 请以该处信息为准，不要依赖此行，因为此处的文案可能过时。

架构

• 核心引擎（ledger_engine.py）：按 Agent 划分的 JSONL 账本、预算状态、警报日志，以及每个 Agent 的密钥（ensure_agent_secret — 新声明需要 workspace_key，之后每次写入都会为该 Agent 生成自己的 agent_secret）
• 身份（identity.py）：解析调用方的唯一入口 — agent_secret 或 workspace_key，两者均通过请求头传递。所有门禁（声明、读取、计费）都会调用此处，而非各自实现检查逻辑。
• 工作区（workspace_engine.py）：按客户划分的身份与套餐状态，通过钱包地址标识（x402，无需人工参与），或不使用任何标识（普通 POST /start 工作区）
• REST API（api_server.py，FastAPI）：应用创建、元数据端点、人类使用的开始/购买页面和路由器引入；端点位于 routes_agents.py 和 routes_billing.py。在 /mcp/ 提供托管的 streamable-http MCP
  • /v1/agents（完整的跨租户列表）仅限所有者访问，需要 X-Al-Admin 请求头
  • 读取（/v1/report、/v1/tokens、/v1/alerts）需要 X-Agent-Secret 或 X-Workspace-Key；MCP 读取工具也将这两种凭据作为参数，因此两种入口都不存在未经身份验证的读取路径
  • 凭据生命周期：POST /v1/agents/{agent_id}/rotate-secret 和 /revoke-secret 仅接受 workspace_key。Agent 自身的 agent_secret 不能用于轮换密钥 — 若允许如此，泄露的 Agent 凭据就会永久阻止其真正所有者访问。撤销操作会覆盖已存储的密钥，而非将其删除，因此该 agent_id 仍处于已声明状态，无法被其他工作区占用
• 输入验证：agent_id 限定为 [A-Za-z0-9._-]{1,64}（可防止路径遍历），rail 仅允许 mpp/x402/api_key/manual，amount 和 budget 上限均限制在 [0, $100k]
• Stripe webhook 采用失败即关闭策略：除非 HMAC 签名通过 STRIPE_WEBHOOK_SECRET_AL 验证，否则拒绝事件。面向用户的结账端点已停用（410）— webhook 仍保持接线，仅为让其移除时仍在进行的订阅能够完成；经过验证的 pro 结账会通过其 client_reference_id 将该工作区标记为付费层级。

联系方式

[email protected]