コスト管理
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/cost-management/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Ankole の運用コストの大半はモデルのトークン消費によるものですが、その金額はコントロール不能な利用量だけで決まるわけではなく、いくつかの明確な設定項目(レバー)によって大きく左右されます。このページでは、control plane に用意されている具体的なコスト制御レバーと、それぞれの効果、そして請求額が想定を超えたときに見直すべき順序を説明します。「とにかく Agent を使う回数を減らす」といった曖昧な精神論ではなく、すべて実在する設定ノブです。
基本となる考え方はシンプルです。コストは**「どのモデルを・何回・どれだけの規模で動かすか」**で決まります。以下の各レバーもこの 3 軸に対応しています。モデルプロファイルの階層で「どのモデルを使うか」を決め、Agent ループ予算で「1 ターンあたりの反復回数」を抑え、Workflow や Background Agent Job の上限で「並列展開(fanout)とリトライ回数」を制限します。まずはどこで消費が膨らんでいるかを特定し、そこに対応するレバーを調整してください。
レバー 1: model profile の階層
モデルプロファイル(Model Profile)は Console → Model Profiles の 3 層疎継承チェーン(Site -> Pod -> Agent/System)に従って解決されます。各 Agent は 7 つの標準スロット(4 つの言語モデルスロットと web_search、web_fetch、image_generate)を持ち、Site・Pod および組み込みの system Principal(ankole_brain、system)はさらに rerank、decision、speech、transcription、ocr、video、music の 7 つのスロットを持ちます。未指定のスロットは Pod と Site の既定値を継承し、さらに heavy -> primary と light -> primary のスロット間フォールバックが適用されます。
| スロット | 使われる場面 | コスト上の位置づけ |
|---|---|---|
primary |
メインの推論モデル(大半の通常 turn で使用) | 単一項目として最大のコスト要因 |
light |
高頻度・低リスクな軽量処理(未設定時は primary にフォールバック) |
大量処理が primary 単価にならないよう安価なモデルを割り当てる枠 |
heavy |
難易度の高い統合・推論処理、Background Agent Job、Dreaming(未設定時は primary にフォールバック) |
複雑な推論や長時間のバックグラウンド作業で使う Provider とモデルを決定 |
vision_fallback |
primary が画像入力に非対応のとき |
画像を扱う Agent にだけ設定する |
web_search、web_fetch |
Web 検索・ページ取得ツール | レバー 3 を参照 |
image_generate |
画像生成ツール | 1 回あたりの単価が高いため、必要な Agent にだけ設定する |
rerank(Site / Pod / system) |
Brain の想起再ランク付けと /rerank 既定経路 |
低コストで高速な rerank モデルを割り当てる枠 |
decision(Site / Pod / system) |
/decisions の確率付き回答 |
判定モデルを割り当てる枠。未設定時は light モデルが回答 |
speech(Site / Pod / system) |
/audio/speech の音声合成 |
音声合成モデルを割り当てる枠。未設定時は音声合成リクエストが失敗 |
transcription(Site / Pod / system) |
/audio/transcriptions の文字起こし |
文字起こしモデルを割り当てる枠。未設定時は文字起こしリクエストが失敗 |
ocr(Site / Pod / system) |
/ocr の PDF・画像の Markdown 読み取り |
PDF の読み取りに必要な OCR モデルを割り当てる枠。未設定時は言語モデルが画像だけを読み取る。割り当てると、Pod は新しくアップロードされた PDF のスキャンページも自動で送り、プロバイダーがページごとに課金する |
video(Site / Pod / system) |
/videos の動画生成 |
動画モデルを割り当てる枠。未設定時は動画リクエストが失敗。プロバイダーは生成ごとに課金 |
music(Site / Pod / system) |
/audio/music の音楽生成 |
音楽モデルを割り当てる枠。未設定時は音楽リクエストが失敗。プロバイダーは生成ごとに課金 |
Company Brain の保守と Pod Applet の呼び出しでは、実行主体が異なります。
ankole_brain: Company Brain のすべてのモデル呼び出しを実行し、使用量をankole_brainに計上します。会話や Source からの知識抽出にはlight(未設定時はprimary)、Dreaming と Skill 教訓の再確認にはheavy(未設定時はprimary)、URL Source の本文取得にはweb_fetch、想起時の再ランク付けにはrerankを解決し、embedding 生成には AppConfigure のサイト設定brain.embedding_modelを使用します。Brain 保守の予算帯を通常の Agent と分けたい場合は Console → Model Profiles でankole_brainの各スロットを個別に上書きできます。各プロファイルの準備状態は Brain → Health で確認できます(詳細は Brain を参照)。- Pod Applet
ctx.ai: 通常の呼び出しは現在の呼び出し元、管理用 capability は Applet の owner を主体として実行します。AIGateway はその主体に対応するプロファイルを解決し、使用量を記録します。Applet を起点とする呼び出しは Agent のトークンクォータ集計には入りません。
モデルプロファイルの見直しで特に効果が高いのは次の 2 点です。
- Site または Pod レベルで
lightに安価な軽量モデルを割り当てる:lightは未設定時にprimaryへフォールバックし、高頻度の補助処理やankole_brainの知識抽出を担います。既定レイヤーで低コストモデルを設定しておけば、継承するすべての Agent とankole_brainの消費をまとめて抑えられます。 primaryは最初から最上位モデルにせず、標準クラスから始める: 「想定よりコストが高い」と感じるケースの大半は、日常の定型作業に対してprimaryのモデルがオーバースペックになっていることが原因です。出力品質に不足を感じた専門 Agent だけprimaryやheavyを上位モデルへ上書きしてください。
Agent の上書きを変更する前に、Site と Pod から継承した実効プロファイルを確認します。実効の vision_fallback が未設定なら、画像入力のフォールバックは利用できません。画像生成の モデルのプロバイダーが実行 がオンの場合はメイン Provider のネイティブ機能を使い、専用プロファイルは使いません。image_generate を使うにはこのスイッチをオフにします。一方、heavy が未設定の場合は Background Agent Job も AIGateway 経由で primary へフォールバックするため、複雑な推論やバックグラウンドジョブを別 Provider や上位モデルへ割り当てたい場合に heavy を設定してください。
レバー 2: reasoning effort
Codex の推論強度(model_reasoning_effort)に対応する Provider では、minimal | low | medium | high | xhigh | max の 6 段階で推論トークン量を調整できます。Console には、選択したモデルが受け付ける段階だけが表示されます。段階を下げるほど低コストかつ高速になり、上げるほど難問への精度が高まる代わりに消費が増えます(既定値は high です)。
モデル自体を変更するよりも細かく効くレバーです。たとえば通常の業務応答で medium で十分な Agent が既定の high のまま動いていると、体感品質は変わらないまま推論トークンだけを余分に消費します。全 Agent を一律に引き上げるのではなく、まず primary プロファイルを業務難度に見合った段階へ下げ、複雑な統合判断を担う特定の Agent だけを高めに設定してください。
レバー 3: web ツールをオンデマンドで
web_search と web_fetch は呼び出しごとに課金が発生する独立プロファイルです。次の 2 点で無駄な呼び出しを防げます。
- 検索の実行先を確認する: Web 検索は既定で モデルのプロバイダーが実行 がオンです。専用の
web_searchプロファイルを使うにはオフにします。プロファイルを外すだけではネイティブ検索は無効にならないため、不要な検索は Agent の作業指示で抑えてください。 - 対象 URL がわかっている場面では
web_searchよりweb_fetchを優先させる: 既知の URL を直接読むなら 1 回の取得で済みますが、検索から入ると「検索 1 回 + 見つけたページへの複数回の取得」に膨らみます。
なお、AppConfigure の agent_workers.rendered_fetch_idle_ttl_ms キーは、レンダリング版 web_fetch で使用するブラウザサイドカーを未使用時に解放するまでのアイドル待機時間を制御するものです(URL レスポンスのキャッシュ設定ではありません)。
レバー 4: agent ループの予算とコールドウェイク・ローテーション
テナントスコープ(scope: :tenant)の AppConfigure キーを使うと、1 回の turn あたりの消費上限と、長期スレッドでのコールドキャッシュ再課金を制御できます。
| キー | 制限する対象 |
|---|---|
ai_agent.max_iterations |
1 turn あたりの Agent ループ最大反復回数 |
ai_agent.max_output_tokens |
1 回のモデル応答あたりの最大出力トークン数 |
ai_agent.inactivity_timeout_ms |
応答が途絶えた turn を回収・終了するまでの待機時間 |
sessions.wake_recycle |
コールドウェイク会話ローテーションポリシー(min_cold_gap_seconds: 3600、min_context_tokens: 128000、im_max_idle_seconds: 259200) |
ツールを過剰に呼び続けるループを抑えるのが max_iterations です。2 回のツール実行で済む作業で 10 回ツールを呼べば、その分だけモデルへの往復リクエストが 10 回発生します。上限を適切に絞ることで、手持ちの情報から結論をまとめるよう Agent に促せます。また、max_output_tokens は 1 回あたりの長文出力を抑えます。これら ai_agent.* キーはテナント既定値(未上書き時はサイト既定値を継承)として、普段の標準的な turn が無理なく収まる値に設定してください。ごくまれな難問で上限に達し「ここまでに集まった情報からの暫定回答」になるケースは許容するのが現実的です。
また、上流 Provider のプロンプトキャッシュが失効したあとに長大なモデル履歴をそのまま再開すると、次の turn で全履歴がキャッシュなし入力として再課金されます。sessions.wake_recycle はこの繰り返し課金を防ぎます。Session が min_cold_gap_seconds(既定 1 時間)以上アイドル状態になったあと min_context_tokens(既定 128,000 トークン)以上の文脈を抱えて再開するとき、または外部チャットチャネルで im_max_idle_seconds(既定 72 時間)以上経過して再開するとき、Ankole は公開チャット履歴をそのまま保ちつつ、簡潔な <wake-briefing> を引き継いだ新しい AIGateway モデル会話ブランチへ切り替えます。
レバー 5: Workflow の fanout とタスク試行
Workflow 内で実行される各 agent() タスクは、それぞれが完全な 1 回のモデル Turn です。さらに 1 つの呼び出しにつき最大 3 回まで試行され得るため、元の会話からは 1 回 Workflow を呼んだだけでも、内部で多数のタスクを展開(fanout)すればモデル呼び出しや Web ツールの消費は何十倍にも増幅します。
| AppConfigure キー | 既定値 | 最大値 | 制限する対象 |
|---|---|---|---|
workflow.max_concurrency_per_run |
8 |
32 |
1 つの run 内で同時に実行できるタスク数 |
workflow.max_running_per_agent |
8 |
64 |
1 つの Agent で複数の run にまたがって同時実行できる Workflow タスク数 |
workflow.max_agent_calls_per_run |
32 |
1,024 |
1 つの run が作成できるサブエージェント呼び出しの総数 |
同時実行数(concurrency)を変えても完了までの所要時間が変わるだけで、モデル呼び出しの総回数自体は減りません。入力件数に見合った呼び出し上限を設定し、インフラ負荷に応じた必要最小限の同時実行数にとどめてください。なお、個々の run で concurrency や max_agent_calls をより低い値に絞ることはできますが、複数 run 横断の max_running_per_agent を変えたり AppConfigure の上限を超えて引き上げたりすることはできません。
Workflow 全体に対する一括のトークン上限や金額上限はなく、各サブタスクに対して通常の Turn と同じ反復回数・出力トークン数・非アクティブ時間の上限が適用されます。各タスクのプロンプトを絞り、小さな構造化データで結果を受け取り、null(失敗)のハンドリングを入れたうえで、件数が多い場合は複数の run に分割してください。詳しくは Workflow を参照してください。
レバー 6: background job の再試行とスロット上限
Background Agent Job でもリトライや並列実行によってトークンが消費されます。関連する上限は次のとおりです。
| 上限項目 | 値 | 効果 |
|---|---|---|
max_execution_attempts |
5 |
実行失敗が 5 回に達すると failed になる |
max_consecutive_turn_failures |
5 |
Turn 失敗が 5 回連続した時点で処理を打ち切る |
max_running_per_agent |
3(既定値) |
Agent ごとの同時実行ジョブ上限。テナント設定 background_agent_jobs.max_running_per_agent(1..64)で変更可能 |
| 再試行遅延 | 約 30 秒 | 試行間の最小クールダウン間隔 |
実行失敗が累計 5 回に達するまで一時的なエラーを再試行でき、設定エラーは直ちに失敗が確定します。開始や再開の claim は別に数え、総上限は 25 回です。認証情報プールのバックプレッシャーは実行失敗の枠を消費しません。claim のたびに完全なモデル実行や同じ量のトークン消費が発生するとは限りません。運用では同時実行数も確認してください。3 つのジョブを並行稼働させている Agent は、裏で 3 本のモデルループを同時に回しています。そこまでの並列処理が不要であれば、上限を下げるか「一度に 1 つずつ順番に進める」よう Agent の指示を整えるだけで消費を抑えられます。
レバー 7: Agent ごとの token quota
ここまでの 6 つのレバーが「1 回の作業にかかる重さ」を整えるものであるのに対し、トークンクォータは「期間あたりの総消費量」に絶対上限を設ける安全弁です。指定した繰り返し期間内に Agent が消費したトークン数が上限に達すると、その期間が終わるまで AIGateway が該当 Agent のモデル呼び出しを遮断します。
設定は Agent 詳細ページで、期間の長さ(日数)・開始日時・トークン上限を入力して行います。画面上では現在の消費割合と期間の終了日時を確認できます。上限到達後にチャットメッセージが届くと、通常の応答の代わりに消費量・上限・期間終了日時を知らせる案内が返され、実行中または新規の Background Agent Job は次の期間を待たずに失敗終了します。業務上の正当な理由で一時的に利用が急増し、すぐに稼働を再開させたい場合は、期間をリセット を押すとその場から新しい期間が始まります。
なお、クォータは普段のペース配分を調整する機能ではなく、暴走や想定外の急増を止めるブレーカーとして使ってください(上限が近づいても Agent が自動で節約モードになるわけではなく、最後の 1 回の呼び出し分だけ上限をわずかに超えて停止することがあります)。次節の方法で普段のピーク週の実績を把握し、そこに少し余裕を持たせた値を設定するのがおすすめです。設定手順は Agents を参照してください。
消費が実際にある場所
モデルや並列度を変更する前に、まず「どの Agent の、どの会話・Workflow・Background Agent Job が実際に呼び出しを行っているか」を確認してください。
GET /api/v2/ai-gateway/conversationsを確認する: 直近の turn で行われたモデル呼び出し(解決されたプロファイル名、呼び出し回数、使用された provider)がわかります。コストの主因がprimaryの呼び出し回数なのか、heavyの高単価呼び出しなのか、それとも大量のweb_searchなのかを切り分ける最短ルートです。- メイン Agent に Workflow の実行履歴を確認させる: タスク数や失敗した呼び出し数から、過剰な fanout が起きていないか把握できます(Workflow 専用の Console 画面や run 単位の金額集計はありません)。
GET /api/v2/background-agent-jobsでattemptsを確認する: この値は claim 数です。実際のトークン消費は記録されたモデル呼び出しで確認してください。- control plane の構造化ログを集計する: provider 呼び出しイベントの構造化フィールドをログ基盤側で集計すれば、provider 別・Agent 別の内訳を継続的に可視化できます。
原因がわかれば、対処は「Agent の利用を控える」ことではなく、「特定の Agent の作業内容に対してずれていた設定レバーを適切な値に直す」ことに帰着します。
想定例
1 週間のトークン消費が 2 倍になったとします。会話履歴 API では primary の呼び出し回数が変わらず、may_intervene を使うチームアシスタントの web_search 呼び出しが 10 倍になっていました。この場合は、「事実確認の質問を受けたときだけ Web 検索を使う」と Agent の指示を明確にするか、Signal Binding の介入ポリシーを見直します。変更後の呼び出し履歴で、不要な検索が減ったかを確認してください。
コスト管理がそうでないもの
Ankole 自体にはリアルタイムの金額ダッシュボードはなく、「月額何ドルで停止する」といった通貨単位での直接キャップ機能もありません。ここで紹介したレバーが制御するのはあくまで呼び出し回数・トークン数・反復回数であり、最終的な請求額はそこに各 Provider の単価を掛けたものになります。また、実際の呼び出しログを確認せずに当てずっぽうで設定を絞っても品質が落ちるだけですので、まず消費箇所を特定してから該当するレバーを調整してください。
次のステップ
- Agent ごとのモデルプロファイルとクォータ設定については、Agents を参照してください。
ai_agent.*をはじめとする実行時制限キーについては、AppConfigure を参照してください。- 使用状況の確認に使う会話・ジョブ系 API については、Console API リファレンス を参照してください。
- 上限付きサブエージェント展開の仕様については、Workflow を参照してください。
- バックグラウンドジョブのリトライとスロット管理については、Background Agent Jobs を参照してください。