Cost-capping autonomous agents with AgentGuard

An autonomous agent that loops on a complex task can make hundreds of LLM calls before you notice. At $5–21/MTok for frontier models, a runaway loop can cost hundreds of dollars before a human intervenes. AgentGuard is PRYSM’s safety layer. It enforces spending constraints at the API level — not in your agent’s code, not in a client-side wrapper — so the caps hold regardless of how the agent calls the LLM.

The four controls

Control	Mechanism	Effect
Per-request cap	`X-Max-Cost-USD` header	Auto-downgrade or 402 if estimated cost exceeds cap
Monthly cap	Plan config / `monthly_cap_usd` key attribute	Hard stop when monthly spend is exhausted
80% webhook	`PRYSM_BUDGET_WEBHOOK_URL` env var	Fire-and-forget POST when you cross 80% of monthly cap
Remaining balance	`X-Prysm-Budget-Remaining` response header	Agent reads its own remaining budget and self-throttles

Per-request cap: `X-Max-Cost-USD`

Add one header to your OpenAI client and every call gets a hard cost ceiling:

from openai import OpenAI

client = OpenAI(
    api_key="prysm_sk_...",
    base_url="https://api.prysm1.com/v1",
    default_headers={"X-Max-Cost-USD": "0.005"},  # $0.005 per call
)

What happens when the routed model would exceed the cap:

PRYSM estimates cost before calling the provider (input tokens × rate + max_tokens × rate).
If estimated cost > cap, PRYSM selects the cheapest live model that fits within the cap.
If no model fits (extremely tight cap), PRYSM returns HTTP 402:

{
  "error": "per_request_cap_exceeded",
  "message": "Estimated cost $0.00720 exceeds X-Max-Cost-USD $0.005. No model fits within the cap.",
  "estimated_cost_usd": 0.007200,
  "cap_usd": 0.005000
}

The auto-downgrade is transparent — your agent code doesn’t change. The prysm.routing.why field tells you what happened:

"why": "auto-downgraded by X-Max-Cost-USD cap $0.005000"

Per-agent cap in LangChain

from langchain_openai import ChatOpenAI

cheap_agent_llm = ChatOpenAI(
    model="auto",
    openai_api_key="prysm_sk_...",
    openai_api_base="https://api.prysm1.com/v1",
    default_headers={"X-Max-Cost-USD": "0.001"},  # $0.001 max per step
)

frontier_agent_llm = ChatOpenAI(
    model="auto",
    openai_api_key="prysm_sk_...",
    openai_api_base="https://api.prysm1.com/v1",
    default_headers={"X-Max-Cost-USD": "0.05"},   # $0.05 for heavy reasoning
)

Self-throttling agent loop

The X-Prysm-Budget-Remaining header is emitted on every authenticated response. Agents can read it and slow themselves down before hitting the monthly cap:

import httpx, time, os

PRYSM_URL = "https://api.prysm1.com/v1/chat/completions"
HEADERS = {
    "Authorization": f"Bearer {os.environ['PRYSM_API_KEY']}",
    "X-Max-Cost-USD": "0.01",
    "Content-Type": "application/json",
}
SLOW_DOWN_THRESHOLD = 1.00   # slow down when < $1.00 remains
STOP_THRESHOLD      = 0.10   # hard stop when < $0.10 remains

def agent_call(messages: list[dict]) -> str | None:
    resp = httpx.post(PRYSM_URL, headers=HEADERS, json={"model": "auto", "messages": messages})
    remaining = float(resp.headers.get("X-Prysm-Budget-Remaining", "999"))

    if remaining < STOP_THRESHOLD:
        print(f"Budget exhausted (${remaining:.4f} left) — stopping agent loop")
        return None
    if remaining < SLOW_DOWN_THRESHOLD:
        print(f"Budget low (${remaining:.4f} left) — sleeping 5s between calls")
        time.sleep(5)

    return resp.json()["choices"][0]["message"]["content"]

80% webhook

Set PRYSM_BUDGET_WEBHOOK_URL to receive a POST when your monthly spend crosses 80%:

PRYSM_BUDGET_WEBHOOK_URL=https://your-app.com/api/budget-alert

Payload:

{
  "event": "budget_80pct_alert",
  "user_id": "u_abc123",
  "plan": "pro",
  "spent_usd": 40.00,
  "cap_usd": 50.00,
  "pct_used": 80.0,
  "timestamp": "2026-06-15T14:23:11Z"
}

The webhook fires once per API key per billing cycle (deduplicated in-process; use Redis for multi-process deploys). Use it to:

Send Slack/email alerts to the dev team
Automatically switch agents to budget models
Pause non-critical background jobs

BRAIN.md: team-level defaults

Set AgentGuard defaults for your entire team without touching agent code:

# BRAIN.md
model: auto
max_cost_per_request: 0.005
monthly_budget_usd: 50.00

rules:
  - when: simple
    model: deepseek-v4-flash   # always route simple tasks to budget
  - when: code
    model: claude-sonnet-4.5   # but give code tasks a proper model

intent: |
  Engineering team AI assistant. Prefer correctness over speed.
  Never suggest architectural changes without explicit request.

CrewAI: per-agent + crew-total budget

from crewai import Agent, Crew, LLM

def make_agent(role: str, cap: float) -> Agent:
    return Agent(
        role=role,
        llm=LLM(
            model="openai/auto",
            base_url="https://api.prysm1.com/v1",
            api_key="prysm_sk_...",
            extra_headers={"X-Max-Cost-USD": str(cap)},
        ),
    )

researcher  = make_agent("Senior Researcher",  cap=0.05)
writer      = make_agent("Technical Writer",   cap=0.005)
fact_checker = make_agent("Fact Checker",      cap=0.001)

crew = Crew(agents=[researcher, writer, fact_checker], tasks=[...])
result = crew.kickoff()

Each agent has its own budget, enforced server-side. The researcher gets

0.05/step; the writer gets

0.005; the fact-checker $0.001. No agent can accidentally overspend the others.

Summary: safe defaults for new agent deployments

# BRAIN.md template for any new agentic project
model: auto
max_cost_per_request: 0.005   # auto-downgrade above $0.005
monthly_budget_usd: 25.00     # $25/mo hard stop

# Python client template
client = OpenAI(
    api_key="prysm_sk_...",
    base_url="https://api.prysm1.com/v1",
    default_headers={"X-Max-Cost-USD": "0.005"},
)

Start conservative. Review your X-Prysm-Budget-Remaining trends after the first week and raise limits as you understand your agent’s spending patterns.

​The four controls

​Per-request cap: X-Max-Cost-USD

​Per-agent cap in LangChain

​Self-throttling agent loop

​80% webhook

​BRAIN.md: team-level defaults

​CrewAI: per-agent + crew-total budget

​Summary: safe defaults for new agent deployments