Wattage: AIエージェント向けのトークン消費プロファイラーおよびコスト回帰ゲート
Wattage: A token-spend profiler and cost-regression gate for AI agents (github.com)
要約
Wattageは、AIエージェントのトークン消費を詳細に分析し、無駄遣いを特定するツールです。トークン消費のパターンをリアルなドル価格に換算し、修正策を提案します。CI/CDパイプラインに統合することで、エージェントのコストが増加した場合にビルドを失敗させることも可能です。
全文翻訳
フォルダとファイル
[画像: wattage]
[画像: CI] [画像: PyPI] [画像: npm] [画像: Python versions] [画像: License: Apache 2.0] [画像: Docs]
AIエージェントが無駄にしたトークンをドル単位で見つけ、修正し、変更によってエージェントのコストが高くなった場合にPRを失敗させます。
Wattageは、エージェントが既に生成しているトレースとセッションログ(ローカルのClaude Codeセッション、または任意のOpenTelemetry GenAIトレースエクスポート)を読み込み、検証済みの、日付付きの料金スナップショット(Anthropic、OpenAI、Google、Mistral、xAIの52モデル)に対して各コールを価格設定し、10個の無駄パターン検出器を実行して、それぞれがドル額と具体的な修正を提示します。そして、ダッシュボードが提供しない唯一のもの、つまりエージェントが静かに高価になった場合にビルドを失敗させるCIコスト回帰ゲートを提供します。完全にオフラインで、APIキー不要、何も外部に送信しません。
[画像: wattage demo](https://raw.githubusercontent.com/faizannraza/wattage/main/docs/assets/demo.gif)
uvx wattage demoの実際の出力 — vhs docs/assets/demo.tapeでこのGIFを再生成します。
最初のレポートを30秒で
uvx wattage demo # 設定不要で、発見事項が豊富なサンプルレポート
uvx wattage report --claude-code # 最新のClaude Codeセッション — すでに持っているデータ
uvx wattage report trace.json # 任意のOTLP GenAIトレースエクスポート
デモトレースは意図的に無駄の多い合成エージェントです — Wattageがそれに何をするか(抜粋;以下のすべての数値はコマンドの実際の出力です):
╭─ ⚡ wattage — demo_trace.json ─────────────────────╮
│ Token Efficiency: D (67) Total cost: $0.0557 │
╰───────────────────────────────────────────────────╯
┃ Detector ┃ Severity ┃ Wasted $ ┃ Fix ┃
│ nonconvergence │ critical │ $0.0037 │ 重複した非生産的なイテレーションの後に収束停止を追加… │
│ │ │ │ │
│ prefix_churn │ high │ $0.0123 │ 安定したプレフィックス(システムプロンプト+ツールスキーマ)でプロンプトキャッシュを有効化… │
│ │ │ │ │
│ cache_gap │ high │ $0.0001 │ キャッシュブレークポイントの後に揮発性フィールドを移動… │
│ │ │ │ │
│ reasoning_overspend │ medium │ ~$0.0060 │ このステップのreasoning_effortを減らす(またはextended thinkingを無効にする)。 │
│ │ │ │ │
measured waste: $0.0187 (gradesに計上) · estimated (~) findings: $0.0065 (報告済み、採点なし)
視覚的なレポートを希望しますか? --htmlは、各トークンをインタラクティブなフレイムグラフで表示する、自己完結型の共有可能なバーンマップを書き出します。統計情報ストリップと、お金を燃やした正確なフレームをハイライトする発見事項が含まれます:
uvx wattage report --claude-code --html burn.html
エージェントがより高価になった場合にPRを失敗させる
これは他のオープンソースツールが提供しない部分です:実際の測定済みトレース(トークン化されたプロンプト差分予測ではない)に対するコスト回帰ゲートで、合格した実行でのみ進むコミットされたベースラインがあります。
# .github/workflows/wattage.yml
name: Wattage
on:
pull_request:
paths: ["agents/**", "prompts/**", "src/**"]
permissions:
pull-requests: write # スティッキーなPRコメントのため(レポートはこれなしでもステップサマリーに表示されます)
concurrency:
group: wattage-${{ github.ref }}
cancel-in-progress: true
jobs:
token-efficiency:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate trace fixture
run: python scripts/run_agent_fixture.py > trace.json # YOUR agentのトレースを生成するものに置き換えてください
- name: Wattage cost-regression gate
uses: faizannraza/wattage@v0.2.0
with:
source: trace.json
baseline: .wattage/baseline.json
fail-on: "score_below:80,cost_delta_pct_above:5,any_critical:true"
pr-comment: "true"
回帰が発生した場合にビルドを失敗させ(exit 1)、(更新されるたびにインプレースで更新され、スパムにならない)1つのスティッキーなPRコメントで検出器ごとの差分テーブルを投稿し、ジョブのステップサマリーにレポートを書き込み、他のCIシステム用にSARIFとJUnit XMLを出力します。any_criticalは暴走ループに対するハードストップです:最後の生産的なステップの後に自身のコストの半分を消費した非収束ループは、クリティカルな深刻度にエスカレートします。もう1つのワークフロー(マージ時に実行され、コミットされたベースラインを最新の状態に保ちます)でセットアップが完了します — コピー&ペーストのペアはCI Integrationにあります。
何であり、何でないか
Wattageは診断+処方+ゲートであり、別のダッシュボードではありません。既存のツールが既に生成しているトレースを消費します。それらを置き換えるものではありません。
| Wattage | ccusage / spend counters | Langfuse / Helicone / dashboards | tokencost | promptfoo | |
|---|---|---|---|---|---|
| トレースからコールを価格設定する | ✅ | ✅ (合計) | ✅ | 価格ルックアップのみ | コールごと |
| 無駄パターン+修正を命名する | ✅ 10検出器 | — | — | — | — |
| 測定されたコスト回帰でPRを失敗させる | ✅ | — | — | — | コールごとの閾値のみ |
| ライブダッシュボード / ランタイムプロキシ | — | — | ✅ | — | — |
対象者:請求額に驚かされたLLMエージェントを出荷するチーム。トレースを持っている(または取得できる) — ラップトップ上のClaude Codeセッションは既にカウントされます — PRをレビューし、「この変更でエージェントはより高価になったか?」という質問にCIで自動的に、無料で答えてほしいと考えている人。
動作するもの
- Claude Code / Claude Agent SDKセッション —
~/.claude/projects下のセッション.jsonlファイルを直接読み込み、実際のセッションで検証済みです。5分/1時間のキャッシュ書き込みTTL分割が含まれているため、1時間のキャッシュ書き込みは実際の2倍のレートで価格設定されます(OTel形式では表現できない違い)。コストは標準APIレートです — サブスクリプションユーザーにとってはセッションのAPI相当額であり、レポートにその旨が記載されます。 - OpenTelemetry GenAI semconvトレース — 提供されたすべての属性生成:現在の名前(
gen_ai.provider.name,gen_ai.usage.input_tokens)、ほとんどのインストルメンテーションがまだエミットしているv1.37/v1.27より前の名前(gen_ai.system,gen_ai.usage.prompt_tokens)、OpenLLMetry/Traceloopバリアント、およびOpenInferencellm.*属性(Arize経由でのOpenAI Agents SDK、CrewAI、LangGraphのデフォルトインストルメンテーション)。単一オブジェクトOTLP JSON および仕様標準JSON Lines(OTel Collectorのファイルエクスポートが実際に書き込むもの)、camelCaseまたはsnake_case。 - mozilla-ai/any-agent — 実際のキャプチャ済みトレース(provenance)で検証済み。LiteLLMスタイルの
"provider/model"文字列も含まれます。
フォーマットは自動検出されます — wattage report <file>で動作します。完全なマトリックスと正直な注記:Adapters。
10個の検出器
| Detector | Catches |
|---|---|
prefix_churn | 安定したコンテキストがキャッシュされる代わりに再送信される |
cache_gap | キャッシュが試みられたが、後続の読み取りで十分に再利用されなかった |
nonconvergence | 進捗なしにスラッシング、振動、または停止するループ |
retry_storm | 同じリクエストが連続して再送信される — 各試行で完全なプロンプトを請求するリトライループ |
tool_result_bloat | 大きすぎるツール結果が後続のすべてのコールのコンテキストに再フィードされる |
verbosity | ステップが必要とした量のはるかに超える出力 |
redundant_tool_calls | 同じツールコールが繰り返される(正確またはあいまい) |
retrieval_thrash | 新しい証拠が得られない繰り返し検索 |
model_mismatch | より安価なモデルで処理できる作業を行う、より高価なモデル |
reasoning_overspend | 簡単なステップでの重い推論トークン消費 |
すべての発見事項は価格設定されており、具体的な修正が付属し、2つの正直さラベルが付いています。基盤:measured(測定済み)の発見事項(実際の請求トークンと実際のレートカード)がグレードとCIゲートを推進します。estimated(推定)の発見事項(文字数÷4の予測、ポリシー上限、仮定のダウングレード)は~と共に報告され、ビルドを失敗させることはありません。そして品質リスク:出力品質を変更する可能性のある修正(モデルのダウングレード、少ない推論)は、--qualityマップが実際の証拠で裏付けた場合にのみカウントされます。詳細:Detectors。
正直な数字、構造的に
- 価格設定されていないモデルは、そのコールのコストをゼロのままにし、
wattage ciを大声で失敗させます(exit 4) — 推定レートではありません。 - キャプチャされた使用量がゼロのトレースは、空虚なA(100)を印刷する代わりに、グレーディングを拒否します。
- ドロップまたは重複したスパンはカウントされ、報告され、決してサイレントに飲み込まれることはありません。
- 価格スナップショットは日付付きで出典が明記されています(
2026-08-23-verified、プロバイダー自身の価格ページからのすべての数値)、コンテキストティアを意識しています(Gemini/Grokは200kプロンプトトークンを超えるリクエスト全体を再価格設定します)、および有効日を意識しています(期限切れのプロモーションレートは、コールのタイムスタンプ自体によって価格設定されます)。公開されているがレートのない範囲(272Kコンテキストを超えるOpenAI)は、間違ったティアで請求されるのではなく、価格設定されずに残されます。
ベンチマーク済み、再現可能に
実際のキャプチャ済みエージェントトレースで、Wattageのprefix_churn修正シミュレーションは、安定したプレフィックスでのプロンプトキャッシュの有効化により44.7%のコスト削減($0.000199 → $0.000110)を示しました — 絶対額は少ないですが、これは3ターンのデモトレースのためです。メカニズムは本番スケールでも同一です。
収束エンジンの分類子は、10ループの手動ラベル付けされたスイートに対して、実際のSHA-256完全一致ベースラインに対して1.00 F1 vs 0.25のスコアを示します。その数値をそのまま受け取ってください:スイートは小さく、私たちによって書かれ、完全一致ループガードが構造的に見ることができない盲点を実証するために意図的に構築されています(リトライごとに新しいタイムスタンプ、振動戦略、生産的に見える停止) — これは盲点デモンストレーションおよび回帰スイートであり、フィールドスタディではありません。両方の数値は、隠されたセットアップなしで出荷されたコードから再現可能です:
uv run python -m benchmarks.harness
uv run python -c "from benchmarks.frontier import build_frontier; print(build_frontier())"
ベンチマークで示されていないものを含む、完全な方法論:The Convergence Engine。
バッジ
uvx wattage badge trace.json --out wattage-badge.svg
[](https://github.com/faizannraza/wattage)
マージ後のCIジョブに--badge-outをワイヤリングすると、READMEにエージェントが効率的であるという証明可能な主張が表示されます。
貢献
検出器はPythonのエントリポイントグループを通じて発見されるため、検出器を追加してもこのリポジトリのコアパイプラインに触れる必要はありません — 完全な「検出器の書き方」ウォークスルーについては、cache_gapを参考例として使用したCONTRIBUTING.mdを参照してください。
Wattageがトレースで実際の無駄を発見した場合、スターは他のチームがそれを見つけるのに役立ちます — そして、ロードマップのどの部分(Langfuseエクスポートアダプター、ライブOTLPテール、ランタイムループガード)を最初に構築すべきかを示してくれます。