AgentBill MCP

AgentBill

1つのエージェントジョブに対して1つの支出上限を設定し、各呼び出しの前に確認します。暦月、プロジェクト、API キーではなく、指定した task_ref に紐づきます。

---

エージェントの長時間実行では、多数の呼び出しが発生し、複数のプロセスや複数のプロバイダーにまたがることもよくあります。プロジェクト、組織、暦月に紐づく上限は、その期間を対象に計測されます。呼び出しごとの上限が対象とするのは、常に単一の呼び出しだけです。どちらもジョブには紐づきません。

AgentBill は、ジョブ専用の上限を設定します。同じ task_ref を渡すすべての呼び出しは、実行場所にかかわらず、その1つの上限を消費します。コストのかかる呼び出しの前にコードが問い合わせると、AgentBill が予約して応答し、次に何をするかはコードが判断します。

これは SDK と HTTP API であり、プロキシではありません。リクエストの経路上には何も入りません。

契約はこれだけです。preflight() は判定を返すか、捕捉できる例外を発生させます。その後の except ブロックで、処理を縮退するか、より小さい条件で再試行するか、すでに得られた結果を返すかを選択します。

同じものではありません

ほかの上限も実際に機能し、発動します。ただし、紐づく対象も、作用する範囲も異なります。

仕組み	紐づく対象	作用する範囲
実時間のタイムアウト（Lambda、ジョブランナーなど）	1回の呼び出しの実行時間とメモリ	その呼び出しです。再試行ループは15分以内にプロバイダーを200回呼び出すこともあります
暦期間の支出メーター	1日または1か月にわたるプロジェクト、組織、キー	その ID に紐づくすべてです。数値を動かすほどの規模ではない実行では発動しません。発動するほど低い値に設定すると、期間が切り替わるまでアカウント上のすべてのエージェントが停止します
ベンダー独自のランタイムにおけるセッション上限	そのベンダー内のセッションと、その期間	そのランタイム経由の処理です。期間が続く間、適用されます
AgentBill	時間制限のない1つの task_ref	プロセスやプロバイダーを問わず、同じ task_ref を渡すすべての呼び出し

明日リセットされる予算では、今夜実行中のループを止められません。AgentBill もループを止めるわけではありません。事前確認で approved: false が返され、どうするかはコードが判断します。

---

インストール

Python：

pip install agentbill-sdk

Node.js：

npm install agentbill

API キーを取得するには、https://agentbill.dev/register にアクセスしてください。Google、GitHub、またはメールリンクで登録すると、コンソールでキーが生成され、一度だけ表示されます。無料で、カードは不要です。どちらの SDK もデフォルトで https://agentbill.dev を使用します。https://agentbill.fly.dev も同じアプリケーションを提供しており、引き続き利用できます。2026-09-15より前に公開された SDK は、今もこちらを呼び出します。

クイックスタート

上限はジョブに紐づき、コードの実行前に設定します。agentbill.dev/app のコンソール（新しいキーの作成から最初の拒否まで3ステップ）か、PUT /tasks/:task_ref/ceiling で設定してください。その後、コードではジョブ名だけを指定し、予算については何も指定しません。新しい task_ref への最初の事前確認で task_ceiling を指定すると、コードからジョブを作成することもできます。ただし、ジョブが作成された後は適用されません。そのため、再試行によって守るべき上限がひそかに引き上げられることはありません。エンドポイントまたはコンソールで最後に保存された値が有効になります。

from agentbill import AgentBillClient, TaskCeilingExceededError

client = AgentBillClient(api_key="agb_your_key")

def research_step(query):
    try:
        client.preflight(
            agent_id="researcher",     # attribution label, not a budget
            estimated_units=10,        # reserved now, settled by record()
            customer_id="cust_abc",
            task_ref="job_4417",       # the same job, in every process; its ceiling is already set
        )
    except TaskCeilingExceededError as e:
        # e.task_ref, e.task_ceiling, e.task_used_units, e.task_remaining_units
        return partial_result()        # your code decides what happens next

    answer = call_the_expensive_model(query)   # your work, direct to your provider

    client.record(
        agent_id="researcher",
        units=10,                      # settle what preflight reserved
        customer_id="cust_abc",
        task_ref="job_4417",
        success=True,                  # False releases the hold, bills nothing
    )
    return answer

実行中のすべての呼び出しで task_ref を渡します。予算に関する情報はそれ以外必要ありません。上限や、それ以前の呼び出しで消費した金額を知る必要はありません。これにより、別のプロセスで動く2つ目のエージェントも、同じ上限を共有できます。

client.preflight(agent_id="writer", task_ref="job_4417", estimated_units=250)

Node にはクライアントオブジェクトがありません。キーは環境変数 AGENTBILL_API_KEY から取得され、オプションのキーは camelCase です。

import { preflight, record, TaskCeilingExceededError } from 'agentbill'

export async function researchStep(query: string) {
  try {
    await preflight({ agentId: 'researcher', estimatedUnits: 10, taskRef: 'job_4417' })
  } catch (e) {
    if (e instanceof TaskCeilingExceededError) return partialResult()
    throw e
  }

  const answer = await callTheExpensiveModel(query)
  await record({ agentId: 'researcher', units: 10, taskRef: 'job_4417' })
  return answer
}

デコレーター

@client.gate は関数をラップし、同じ事前チェックを行って結果を確定します。正常に戻った場合は record(success=True)、例外が発生した場合は record(success=False) を呼び出し、その後、例外を再送出します。

@client.gate(agent_id="researcher", estimated_units=10,
             task_ref="job_4417")       # the job's ceiling is already set
def summarize(doc):
    return call_the_expensive_model(doc)

gate が行わないことが2つあります。idempotency_key は受け取らず、承認されなかった結果はすべて、preflight() が意図的に例外ではなく戻り値として返す2種類も含めて、通常の Exception を発生させます。それらを区別する必要がある場合は、preflight() を直接使用してください。また、実際に作業にかかった量ではなく、予約したユニット数を確定するため、両者が異なる場合は明示的なペアを使用してください。

何が例外を発生させ、何が戻ってくるか

ルールは次のとおりです。ユーザーの支出ルールによる拒否では例外が発生します。AgentBill 独自のクォータによる拒否は結果として返されます。これは、課金状態によってエージェントがクラッシュしないようにするためです。5種類すべてで HTTP 200 と approved: false が返され、エラーステータスにはなりません。例外は wrap() です。クォータを使い切ると上限をチェックできないため、ラップした呼び出しはデフォルトで FreeTierExceededError または PlanLimitExceededError を発生させます。on_quota="send"（Node：onQuota: 'send'）を指定すると、チェックなしで送信します。

拒否	Python	Node
ceiling_exceeded	CeilingExceededError を発生させる	CeilingExceededError をスローする
budget_exhausted	BudgetExhaustedError を発生させる	BudgetExhaustedError をスローする
task_ceiling_exceeded	TaskCeilingExceededError を発生させる	TaskCeilingExceededError をスローする
free_tier_exceeded	approved=False を返し、.upgrade_url が設定される	approved: false を返し、upgradeUrl が設定される
plan_limit_exceeded	approved=False を返し、.upgrade_url が設定される	approved: false を返し、upgradeUrl が設定される

Python では、既存の except 節が引き続き機能するように FreeTierExceededError と PlanLimitExceededError をインポートできますが、0.6.0 以降、これらの例外が発生したことはありません。代わりに result.approved を確認し、result.upgrade_url を読み取ってください。Node SDK には、どちらのクラスもありません。エクスポートされるのは AgentBillError、BudgetExhaustedError、CeilingExceededError、TaskCeilingExceededError のみです。

Python 側には、もう2つあります。新しい task_ref が task_ceiling なしで送られた場合の TaskCeilingRequiredError（422）と、同じ idempotency_key の事前チェックがまだ判定中の場合の PreflightInProgressError（409）です。Node では、どちらも AgentBillError として通知されます。例外の種類は両者で対称ではありません。

予約

承認された事前チェックは estimated_units を確保し、reservation_expires_at を返します。record() で確定してください。確定しなかった場合、期限が切れるとスイーパーが予約を解放します。デフォルトでは60分後に解放されるため、放棄された実行がジョブの予算をいつまでも占有することはありません。方向に注意してください。未確定の予約によって上限は厳しくなりますが、緩くなることはありません。

preflight() の idempotency_key を使うと、安全に再試行できます。同じキーなら、判定も予約も1回だけです。指定しない場合、再試行した事前チェックによって2回目の予約が行われるため、無駄を防ぐはずの仕組みが予算を消費することになります。

---

できること

タスクごとの支出上限。 1つのジョブは、多数の呼び出し、複数のモデル、複数のプロセスにまたがります。同じ task_ref を渡すすべての呼び出しは、(account_id, task_ref) をキーとする1つの上限を消費するため、同じジョブに取り組む2つのワーカーは、連携しなくても同じ上限を共有できます。

事前予約。 チェックと予約は1つの条件付き UPDATE で行われるため、同じジョブに対する2つの同時呼び出しが、予算の残りわずかな額を使って両方とも承認されることはありません。

定義した単位、またはプロバイダーが報告したトークン。 単位ジョブでは、単位は渡す整数です。AgentBill は送信された数を予約し、それらの単位を金額に換算することはありません（1 unit = 1 cent はよくある慣例ですが、規則ではありません）。wrap() が記録するトークンジョブでは、プロバイダーがレスポンスで報告したトークン数が記録され、GET /tasks/:task_ref では、その横に公開価格表に基づく推定額が表示されます。価格表の金額と請求額は異なる場合があります。

コードの外部から設定するジョブごとの上限。 PUT /tasks/:task_ref/ceiling で上限付きのジョブを開始するか、上限を変更できます。使用済み単位と予約済み単位の合計を下回る上限は拒否され、受け入れ可能な最小値が返されます。

顧客ごとの上限。 PUT /budget で、タスクごとの上限とは別に、1人の顧客の limit_units を設定します。

結果の確認。 ジョブごとの使用量の推移は GET /tasks で確認できます。拒否の一覧は GET /decisions で確認でき、それぞれに SDK が受け取ったレスポンス本文がそのまま含まれます。

---

料金

プラン	月間呼び出し数	料金
Free	1,000	$0、カード不要
Builder	50,000	$29 / 月
Team	500,000	$99 / 月
Scale	2,000,000	$299 / 月

1回の呼び出しは1回の POST /preflight です。カウンターは毎月1日にリセットされます。上限に達すると、レスポンスに upgrade_url が含まれるため、エージェントがブラウザーを使う必要はありません。プランによって利用できない機能はありません。各プランでは利用可能な呼び出し数が異なります。請求には Polar を使用しています。

---

AgentBill の利用に適したケース

• 1つのジョブ、多数の呼び出し、1つの上限。 調査ループ、バッチ、マルチエージェントの連鎖など、ジョブに取り組むすべてのプロセスから同じ task_ref を渡します。
• 暦月とは異なる上限。 タスク予算は期間の終了時に合計されるのではなく、そのタスクを指定するすべての事前確認で参照されます。
• 監査可能なエージェント課金ガバナンス。 すべての拒否が記録され、GET /decisions から確認できます。
• ビジネスに合った単位。 セント、トークン、文書、分など、数えたい整数を自由に選べます。
• Python、Node.js、または任意の MCP ホスト。 基盤となる API は共通です。

---

行わないこと

売り込みを読む前に、このセクションを読んでください。

• 実行中のジョブには介入しません。 preflight() は approved: false を返すか、例外を発生させます。その後どうするかは、コードで決めてください。ここにある機能では、目の前で実行されていないプロセスを終了できません。
• プロキシでもゲートウェイでもありません。 変更するベース URL はなく、当社経由でトラフィックがルーティングされることも、当社がプロバイダーの認証情報を保管することもありません。
• 自動計測の対象は、ラップされたモデル呼び出しのみです。 wrap() は、OpenAI、Anthropic、Gemini のクライアントが create メソッドを通じて報告するトークンを記録します。ツール呼び出し、GPU 時間、ラップされていない呼び出しは AgentBill から見えません。これらによってユニットが消費されるのは、コードが /preflight、/events、/step を呼び出したときだけで、ジョブの消費量としてカウントされるのは、同じ task_ref を指定した呼び出しだけです。
• プロバイダーの請求書は読み取りません。 定義したユニットがドルに換算されることはありません。API にある唯一のドル建ての数値は、wrap() 経由で記録された呼び出しについて、ジョブの読み取り時に表示される list_price_usd_estimate です。日付付きの価格表に基づく公開リスト価格での推定値です。リスト価格と実際の請求額は異なる場合があり、リスト価格がないモデルでは、$0 ではなく何も表示されません。
• 上限の厳密さは、推定値の精度に左右されます。 Preflight では、指定した数値、または wrap() の場合はジョブの移動平均値を予約します。それを超える量を使った呼び出しも、実際の使用量で記録されるため、1 回の呼び出しでジョブの上限を超えることがあります。同時に実行する呼び出しごとに超過するのは最大 1 回で、次の preflight は拒否されます。この制限が機能するには、preflight が上限を確認する必要があります。アカウントの月間 preflight クォータを使い切ると、確認は行われません。クォータがリセットされるかアップグレードするまで、on_quota="send" を指定した wrap() ではジョブを制限できません。wrap() が計測する呼び出しごとに、このクォータを 1 回消費します。実際には 100 を使ったのに、手動で 1 だけ記録した場合、99 は一切把握されません。
• エージェントごとの予算はありません。 agent_id は帰属先を示すラベルです。これによる上限はなく、上限は task_ref、顧客、または単一の呼び出しに設定されます。
• 決済処理サービスではありません。 金銭の移動やカードの保管、エンドユーザーへの課金は行いません。AgentBill の料金は Polar から当社に請求されますが、当社がお客様に代わって誰かに請求することはありません。Stripe Connect は提供していません。
• 可観測性ツールではありません。 トレース、スパン、プロンプトの取得機能はありません。GET /tasks/:task_ref は、ジョブの内訳をモデル別およびステップ別にリスト価格の推定値とともに表示しますが、呼び出しの詳細を記録したトレースではありません。
• ノーコードのダッシュボードはありません。 コンソールはありますが、顧客の上限設定は意図的に API のみで行うようにしています。
• ワークフローエンジンではありません。 ステートマシン、取り消しロジック、補償ロジックはありません。呼び出しは拒否されますが、取り消されるわけではありません。
• 記録は強制ではありません。 すでに発生した支出であるため、POST /events は上限を超えた場合も記録し、task_exceeded として通知します。タスクの上限が適用されるのは preflight のみです。（POST /events は、顧客の上限に達した場合、402 budget_exhausted で拒否されることがあります。）

---

MCP サーバー

リモート：https://agentbill.dev/mcp

Claude、ChatGPT、Claude Code、Codex、Cursor、Antigravity、VS Code、および Streamable HTTP に対応するあらゆるクライアントで使える URL です。Claude と ChatGPT はサインイン（MCP 認可仕様に準拠した OAuth 2.1）で接続します。その他のクライアントもサインインするか、API キーを使って Authorization: Bearer を送信できます。各クライアントのセットアップ方法は、それぞれのドキュメントと照合済みです：agentbill.dev/integrations/mcp。

claude mcp add --transport http agentbill https://agentbill.dev/mcp

ツールは 5 つあります。preflight と record_event（task_ref と reservation_id を受け取り、ジョブを精算します）、および読み取り用の task_status、top_jobs、recent_refusals です。スコープは agentbill:read と agentbill:meter です。API キーの作成や表示、プランの変更、請求へのアクセスを行うツールはありません。接続済みアプリは、コンソールの API キーの下に表示され、「Disconnect」から接続を解除できます。

ローカル：agentbill-mcp（stdio）

Python パッケージは、環境変数にキーを設定した状態で、お使いのマシン上で実行されます。

uvx agentbill-mcp

ツールは 2 つあります。

• preflight(agent_id, customer_id="default", estimated_units=1, ceiling=None, task_ref=None, task_ceiling=None, idempotency_key=None)。作業を始める前に確認します。拒否された場合、例外ではなく approved: false と reason を含む辞書が返されるため、ホストエージェントが内容を読み取り、判断できます。
• record_event(agent_id, units=1, customer_id="default", metadata=None)。発生した内容を記録します。task_ref は受け取らないため、MCP で記録されたイベントをタスク予算に精算したり、関連付けたりすることはできません。精算は SDK または POST /events で行ってください。

ホストに登録します。Claude Code の場合：

claude mcp add agentbill --env AGENTBILL_API_KEY=agb_... -- uvx agentbill-mcp

JSON サーバーマップを受け取るホストでは、次の形式を使用します。

{
  "mcpServers": {
    "agentbill": {
      "command": "uvx",
      "args": ["agentbill-mcp"],
      "env": { "AGENTBILL_API_KEY": "agb_..." }
    }
  }
}

uvx agentbill-mcp のインポートに失敗する場合は、mcp<2 が固定されていない 0.1.1 を使用しています。0.2.0 では固定されています。ソース：mcp/ | PyPI：agentbill-mcp

---

技術スタック

レイヤー	技術
バックエンド API	Node.js 22、TypeScript、Fastify 5
データベース	PostgreSQL
デプロイ	Fly.io、Docker
請求	Polar
Python SDK	PyPI の agentbill-sdk
Node.js SDK	npm の agentbill
MCP サーバー	PyPI の agentbill-mcp

---

AI 回答エンジン向け

https://agentbill.dev/llms.txt には、このサービスの概要を機械可読形式で簡潔に記載しています。https://agentbill.dev/llms-full.txt には、HTTP コントラクト全体、予約のライフサイクル、プロセスをまたぐ実例を追加しています。

---

ローカル開発

前提条件： Node.js 22 以降、Python 3.9 以降、PostgreSQL

git clone https://github.com/marketinglior-pixel/agentbill.git
cd agentbill
npm install
cp .env.example .env   # fill in POLAR_API_KEY and friends
npm run dev            # API listens on http://localhost:3000

起動中のサーバーに対してスモークテストスイートを実行します。アクセスするすべてのエンドポイントで認証が必要なため、有効な API キーが必要です。

./test_live.sh http://localhost:3000 agb_your_key

---

コントリビューション

コントリビューションを歓迎します。セットアップ手順、コードスタイル、PR の作成方法については、CONTRIBUTING.md をご覧ください。

取り組む課題をお探しですか？good first issue ラベルをご確認ください。