Cost Overrun Alert Prompt for Token Usage

This prompt is designed for engineering teams running multi-step agent workflows where LLM token consumption directly impacts operating costs. It sits inside a monitoring layer that receives cumulative token counts and a plan estimate, then produces a structured cost variance report. Use it when you need an automated, readable alert that explains which steps are driving overruns and what to do about it, rather than a raw token counter. The ideal user is a platform engineer or AI operator responsible for cost governance who needs to detect budget anomalies before they become billing surprises.

This prompt assumes you already have token accounting instrumentation in your agent runtime. It does not replace that instrumentation; it interprets its output. You should wire this prompt into a monitoring callback that fires when cumulative token consumption exceeds a configured threshold (e.g., 80% of plan estimate) or when a step's token delta is anomalous. The prompt requires three inputs: the original plan with per-step token estimates, the actual cumulative token counts per step, and the current execution state. Without accurate token instrumentation, this prompt will produce misleading variance reports.

Do not use this prompt for real-time per-token billing calculations, as it is designed for periodic aggregate reporting. Do not use it as a budgeting tool during plan creation—that belongs to a separate plan estimation prompt. Avoid using this prompt when the agent runtime lacks step-level token attribution, because the output will lack the granularity needed for actionable recommendations. If your workflow involves regulated data or financial commitments, always route the alert through a human review step before taking automated cost-mitigation actions such as aborting workflows or switching models.

This prompt is designed to be called by your monitoring harness at configurable intervals or after each agent step. It receives the current token accounting state and the original plan's cost estimates, then decides whether to generate an alert. The prompt is structured to produce a machine-readable JSON output that your harness can route to logging, dashboards, or paging systems. Replace every square-bracket placeholder with runtime values from your token accounting system and plan store before sending the request.

textCopy
SYSTEM:
You are a cost monitoring agent for an LLM-powered workflow system. Your job is to compare actual cumulative token consumption against the plan's estimated budget and determine whether a cost overrun alert is warranted. You must be precise about token counts, conservative in your projections, and clear about which steps are driving variance. Never invent token counts. If data is missing, flag it as unknown rather than guessing.

USER:
Review the following token consumption data and plan estimates. Produce a structured cost variance report.

## PLAN ESTIMATES
[PLAN_ESTIMATES_JSON]

## ACTUAL CONSUMPTION
[ACTUAL_CONSUMPTION_JSON]

## THRESHOLDS
- Warning threshold: [WARNING_PERCENT]% of total plan budget
- Critical threshold: [CRITICAL_PERCENT]% of total plan budget
- Projection confidence requires at least [MIN_COMPLETION_PERCENT]% of steps completed

## CONSTRAINTS
- Report only on steps present in both the plan and actual consumption data.
- If a step is missing from actuals, mark it as "not_started" with zero consumption.
- If a step is missing from the plan, flag it as "unplanned_step" and include its consumption in the variance.
- Project remaining cost using: (average tokens per completed step) × (remaining steps).
- If fewer than [MIN_COMPLETION_PERCENT]% of steps are complete, set projection_confidence to "low" and note the limitation.
- Do not hallucinate token counts or step names.

## OUTPUT SCHEMA
Return a single JSON object with this structure:
{
  "alert_level": "none" | "warning" | "critical",
  "total_plan_budget_tokens": number,
  "total_consumed_tokens": number,
  "projected_total_tokens": number | null,
  "budget_remaining_tokens": number,
  "percent_consumed": number,
  "percent_projected": number | null,
  "projection_confidence": "low" | "medium" | "high",
  "per_step_breakdown": [
    {
      "step_id": string,
      "step_name": string,
      "estimated_tokens": number,
      "actual_tokens": number,
      "variance_tokens": number,
      "variance_percent": number,
      "status": "not_started" | "in_progress" | "completed" | "unplanned_step"
    }
  ],
  "top_variance_steps": [
    {
      "step_id": string,
      "step_name": string,
      "variance_tokens": number,
      "explanation": string
    }
  ],
  "optimization_recommendations": [string],
  "should_alert": boolean,
  "alert_reason": string | null
}

Adapt this template by adjusting the threshold values to match your organization's risk tolerance. For production deployments, ensure your harness validates the output JSON against the schema before acting on the alert. If the model returns malformed JSON, implement a retry with the validation error included as additional context. For high-cost workflows where a false negative could cause significant budget overruns, configure the harness to escalate to a human reviewer when projection_confidence is "low" and alert_level is "warning" or higher. Log every alert decision—including "none" outcomes—to build a traceable audit history of cost monitoring decisions.

The Cost Overrun Alert Prompt is designed to sit inside an agent monitoring loop, not as a standalone chat interaction. It should be invoked by a scheduler or hook that fires after each agent step completes, or at configurable token-consumption checkpoints (e.g., every 10,000 tokens consumed). The prompt expects a structured input payload containing the original plan with per-step token estimates, cumulative actual token usage, and the current step identifier. Wire this into your agent framework by capturing token counts from each model API response and accumulating them in a session-level cost tracker before passing them to the alert prompt.

Implement a pre-invocation guard that skips the prompt entirely if cumulative usage is below 50% of the total estimated budget. This avoids unnecessary inference cost for early-stage checks. When the guard passes, assemble the input payload with: the full plan array (each step with step_id, description, estimated_tokens), a cumulative_tokens_used integer, the current_step_id, and the cost_threshold_percentage that triggers an alert (e.g., 90). Validate this payload against a JSON Schema before calling the model. If validation fails, log the malformed input and fall back to a conservative alert that flags the step as unmonitored.

Model choice matters here. This prompt performs structured comparison and threshold arithmetic, not creative generation. Use a fast, cost-efficient model such as Claude 3.5 Haiku, GPT-4o-mini, or Gemini 1.5 Flash. The output schema must be strictly validated: expect a JSON object with alert_triggered (boolean), projected_total_tokens (integer), overrun_percentage (float), per_step_breakdown (array of objects with step_id, estimated, actual, variance), and optimization_recommendations (array of strings). If the model returns malformed JSON, retry once with a repair prompt that includes the raw output and the expected schema. After two failures, escalate to a human operator with the raw response and session context.

Log every invocation result to your observability stack, including the input token counts, output token counts, alert decision, and model latency. Tag logs with session_id, agent_run_id, and checkpoint_sequence_number so you can reconstruct the cost trajectory during post-mortems. If alert_triggered is true, publish an event to your notification bus. Downstream consumers—such as a Slack webhook, PagerDuty integration, or agent supervisor module—should receive the structured alert payload, not the raw prompt output. This decouples the detection prompt from the notification channel and lets you add or change alerting targets without touching the prompt logic.

Avoid wiring this prompt directly to an agent pause or abort action. The alert prompt detects and reports; a separate policy engine or human operator should decide whether to halt execution, reduce context, switch to a cheaper model, or continue. This separation prevents a single prompt output from triggering an unrecoverable workflow stop. Test the harness with synthetic token trajectories that simulate normal completion, gradual overrun, sudden spike, and estimate-free plans to verify that the guard, validation, retry, and logging paths all behave correctly before deploying to a live agent.