> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prysm1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost-capping autonomous agents with AgentGuard

> Autonomous agents can burn through API budgets in minutes. AgentGuard gives you hard per-request caps, monthly limits, auto-downgrade, real-time budget headers, and 80% spend alerts — all from a single HTTP header.

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:

```python theme={null}
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:

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

```json theme={null}
{
  "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:

```json theme={null}
"why": "auto-downgraded by X-Max-Cost-USD cap $0.005000"
```

## Per-agent cap in LangChain

```python theme={null}
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:

```python theme={null}
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%:

```bash theme={null}
PRYSM_BUDGET_WEBHOOK_URL=https://your-app.com/api/budget-alert
```

Payload:

```json theme={null}
{
  "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:

```yaml theme={null}
# 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

```python theme={null}
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

```yaml theme={null}
# 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 theme={null}
# 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.