From b5c5b4e3b4a638f842281ae0acd29df644ecc119 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:45:43 +0000 Subject: [PATCH] Clarify AI credit budget escalation guidance Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/aw/optimize-agentic-workflow.md | 4 ++++ .github/aw/token-optimization.md | 3 +++ 2 files changed, 7 insertions(+) diff --git a/.github/aw/optimize-agentic-workflow.md b/.github/aw/optimize-agentic-workflow.md index 85e0ba27cf0..b3c5ea0083c 100644 --- a/.github/aw/optimize-agentic-workflow.md +++ b/.github/aw/optimize-agentic-workflow.md @@ -57,6 +57,9 @@ Priority checks: 2. Is the prompt front-loading large payloads that could be fetched on demand? 3. Are there repetitive extraction steps that sub-agents could handle cheaply? 4. Does the frontier model handle tasks that a small model could do? +5. Can the workflow stay within its current budget after applying and measuring all applicable optimizations? + +Increasing `max-ai-credits` is the last resort. Recommend it only after the applicable optimizations below have been tried and measured, and the workflow still cannot complete with acceptable quality within the existing per-run budget. ### `max-daily-ai-credits` exceeded @@ -101,6 +104,7 @@ After measuring token usage, produce a prioritized plan: 7. **Prompt caching** — verify stable instructions and reusable experience appear before dynamic content 8. **Experiment correctness first** — add an `experiments:` entry, compare output quality first, and use `metric: "aic"` to choose among equivalent-quality variants 9. **Validate quality** — confirm the optimized run produces equivalent safe outputs +10. **Raise the per-run budget only if necessary** — consider increasing `max-ai-credits` only after all applicable optimizations have been exhausted and measured Present the plan clearly before making any edits. Confirm with the user before applying changes. diff --git a/.github/aw/token-optimization.md b/.github/aw/token-optimization.md index 52db137e8b0..ea363dc8ddc 100644 --- a/.github/aw/token-optimization.md +++ b/.github/aw/token-optimization.md @@ -30,6 +30,7 @@ Apply these in order, measuring cost and quality after each change: - [ ] **Telemetry**: Configure `observability.otlp` so token usage and run phases are measurable outside individual run logs - [ ] **AgenticOps**: Add `copilot-token-audit` / `copilot-token-optimizer` workflows so the repository keeps finding waste automatically - [ ] **Measure first**: Back every change with an `experiments:` field and `metric: "aic"` before promoting +- [ ] **Budget increase last**: Increase `max-ai-credits` only after all applicable optimizations above have been exhausted and measured --- @@ -367,6 +368,8 @@ To maximize cache hits: Two top-level frontmatter fields enforce AI Credit budgets directly, independent of the techniques above. Both accept an integer or a `K`/`M` short-form string (e.g. `100M`, `500K`). Typical workflow range: `100` to `2500`. +Do not treat a workflow exhausting its per-run budget as a reason to increase `max-ai-credits` immediately. First apply and measure every applicable cost optimization in this guide. Increase the limit only as a last resort when the workflow still cannot complete with acceptable quality within the existing budget. + - **`max-ai-credits:`** — Per-run AI credit budget enforced by the AWF firewall/API proxy (default `1000`). The agent is steered to stay within budget; set a negative value to disable enforcement and steering. - **`max-daily-ai-credits:`** — Per-user 24-hour guardrail. At activation, gh-aw sums the triggering user's AI credits across their runs of this workflow over the last 24 hours and blocks execution once the total exceeds the threshold. Enabled by default with a system default threshold; set `-1` to disable, or an explicit value to override the default.