組み込み方

ゲートウェイ URL（言語を問わない）

curl -H "X-Spendctl-Agent: researcher" "http://127.0.0.1:8402/https://api.example.com/report?id=42"

宛先を X-Spendctl-Target ヘッダで渡し、http://127.0.0.1:8402/ に送る形でも構いません。レスポンスには x-spendctl-attempt、x-spendctl-decision、x-spendctl-amount が付きます。

wrapFetch（TypeScript / JavaScript）

import { wrapFetch, readRefusal, AgentClient } from "@spendctl/client";

const pay = wrapFetch({ agent: "researcher" });
const res = await pay("https://api.example.com/report");
const refusal = await readRefusal(res);   // 支払い済み・無料なら undefined
const budget = await new AgentClient({ agent: "researcher" }).budget();

MCP

claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcp

ツールは pay（費用がかかるかもしれない URL を取得）、check_budget、list_receipts の3つです。MCP サーバーは薄いクライアントで、鍵も承認権限も持ちません。

HTTP_PROXY

spendctl run --agent researcher -- python agent.py

プロキシの認証情報にエージェント名を入れた HTTP_PROXY を設定して起動します。管理対象になるのは平文の http:// だけで、https:// は中身を見ずにトンネルします。有料の HTTPS API にはゲートウェイ URL を使ってください。

フレームワークのサンプル

• Claude Agent SDK：mcpServers で MCP サーバーを渡す
• OpenAI Agents SDK：wrapFetch を使う関数ツール
• LangGraph：wrapFetch の上に tool() と createReactAgent

この3つの動くサンプルは、公開のクライアント SDK リポジトリ github.com/miraistudio/spendctl-sdk に置く予定です。

エージェント間の連鎖

spendctl は W3C baggage の spend.root、spend.parent、spend.depth を読み、上流に引き継ぎます。あなたのエージェント自体が有料サービスなら、受け取った baggage を外向きの呼び出しに引き継いでください（OpenTelemetry を使っていれば自動です）。spendctl trace <attempt-id> で木構造を表示できます。