| name | optimize-agentic-workflow |
| description | Analyze and reduce token consumption in agentic workflows — guardrail-specific entry points, measurement, and optimization techniques. |
Agentic Workflow Token Optimizer
Help users reduce the AI token usage and cost of GitHub Agentic Workflows in this repository.
Load These References First
Load these files from github/gh-aw (they are not available locally).
.github/aw/github-agentic-workflows.md.github/aw/token-optimization.md.github/aw/workflow-editing.md.github/aw/syntax.md
Load these only when relevant:
.github/aw/experiments.md.github/aw/safe-outputs.md
Available Commands
gh aw audit <run-id> --json
gh aw audit <base-run-id> <optimized-run-id>
gh aw logs <workflow-name> --json
gh aw compile <workflow-name>
gh aw status
Start the Conversation
Ask for one of these inputs:
- a workflow run URL (or run ID) to analyze
- a workflow name to review the source
- the guardrail that was exceeded (max-ai-credits, max-daily-ai-credits, max-tool-denials, max-turns / timeout)
Fast Path: Run URL Provided
If the user gives a GitHub Actions run URL:
- Extract the run ID
- Run
gh aw audit <run-id> --json
- Inspect
agent_usage.aic, agent_usage.input_tokens, agent_usage.output_tokens, agent_usage.cache_read_tokens
- Identify the most expensive phases before asking additional questions
Guardrail-Specific Entry Points
max-ai-credits exceeded
The workflow was stopped because it consumed more AI Credits than the configured per-run budget.
Priority checks:
- Which tool calls dominated token usage? (
token-usage.jsonl)
- Is the prompt front-loading large payloads that could be fetched on demand?
- Are there repetitive extraction steps that sub-agents could handle cheaply?
- Does the frontier model handle tasks that a small model could do?
max-daily-ai-credits exceeded
The workflow is being blocked because its 24-hour AI Credits budget is exhausted.
Priority checks:
- What is the run cadence? (scheduled too frequently?)
- Does the workflow use cheap triage before escalating to the frontier model?
- Is batching or caching applicable to reduce run frequency?
- Are there noop early-exits for events that do not require agent action?
max-tool-denials exceeded
The Copilot SDK hit the tool-denial threshold, indicating the prompt attempted actions outside the allowed tool policy.
Priority checks:
- What tool was repeatedly denied? (last denied reason in the failure issue)
- Is the tool missing from the workflow's permissions/firewall config?
- Can the prompt be revised to avoid the denied operation entirely?
- Would a DataOps pre-step satisfy the data need without a tool call?
Timeout / max-turns exceeded
The agent ran out of time or turns before completing the task.
Priority checks:
- Is the task decomposable into smaller, faster sub-tasks?
- Are there long-running tool calls that could be replaced with DataOps pre-steps?
- Is the prompt asking the agent to do too much in one run?
- Can
max-turns or timeout-minutes be raised, or should the task be split?
Optimization Analysis Plan
After measuring token usage, produce a prioritized plan:
- Measure — run
gh aw audit <run-id> --json and summarize AI Credits and per-call token breakdown
- Identify top cost drivers — list the three most expensive phases/tool calls
- Apply quick wins first — DataOps pre-steps,
gh-proxy, cli-proxy, prompt trimming
- Sub-agent delegation — identify repetitive per-item loops suitable for small-model workers
- Prompt caching — verify stable context appears before dynamic content
- Experiment — add an
experiments: entry with metric: "aic" to measure the change
- Validate quality — confirm the optimized run produces equivalent safe outputs
Present the plan clearly before making any edits. Confirm with the user before applying changes.
Editing Workflow
- Edit
.github/workflows/<workflow-name>.md
- Recompile:
gh aw compile <workflow-name>
- Commit both the source and the generated
.lock.yml
- Report the estimated savings and link to the PR or commit
