Pydantic AI: token-budget guardrails in one line
A hard monthly spend cap per workspace: past it, requests that would reach a provider get 402 budget_exceeded while cache hits still serve. Here is the change for Pydantic AI, the switch that turns it on, and the arithmetic on gpt-6.1-sol.
Pydantic AI reaches TokenZero with one base-URL argument and keeps your openai key. 100,000 reference calls on gpt-6.1-sol cost $700 a month at list price; with monthly_budget_usd set to 500 the gateway returns 402 budget_exceeded once routed spend reaches $500.00 and resets on the first of the month, so a runaway loop cannot overspend.
· Source: pricing table 2026-10-26; overhead from the published benchmark on /benchmarks
At a glance
- Framework
- Pydantic AI (Python)
- Capability
- token-budget guardrails
- Change
- agent.py: base URL argument
- Request shape
- OpenAI chat / Responses
- Turn it on
- X-TokenZero-Budget-Usd / -Spent-Usd / -Remaining-Usd / -Resets-At on every response
- Workspace setting
- monthly_budget_usd: 500
- Reference model
- gpt-6.1-sol ($2.00 in / $10.00 out per 1M, table 2026-10-26)
- Reference workload against a $500 budget
- $700/month on gpt-6.1-sol (computed)
- Gateway overhead (measured)
- 1.52 ms p50, 3.42 ms p95
- Parity floor
- 99.8%
- Free tier
- $500/month routed spend
Reference workload on gpt-6.1-sol: 2,000 input (1,500 static) / 300 output tokens, 100,000 calls per month, table 2026-10-26
| Scenario | Per call | Per month | Delta |
|---|---|---|---|
| List price, no gateway | $0.00700 | $700 | — |
| Static prefix cached (prompt compression) | $0.00415 | $415 | $285 (41%) |
| 20% exact-cache repeats | $0.00560 | $560 | $140 (20%) |
| All calls cascaded to gpt-6-luna | $0.00035 | $35 | $665 (95%) |
| Budget guardrail at $500/month | — | capped at $500.00 | 402 after 71,428 calls |
The change
1. Point Pydantic AI at the gateway (agent.py):
-agent = Agent('openai:gpt-6.1-sol')
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.openai import OpenAIProvider
+agent = Agent(OpenAIChatModel('gpt-6.1-sol', provider=OpenAIProvider(base_url='https://tokenzero.sh/v1')))Structured outputs and tool calls pass through unchanged; tool schemas are minified losslessly by the gateway.
2. Turn on token-budget guardrails. Per request: X-TokenZero-Budget-Usd / -Spent-Usd / -Remaining-Usd / -Resets-At on every response. Per workspace (applies to every call without touching code): PATCH /v1/workspaces/settings {monthly_budget_usd: 500} or the dashboard toggle.
3. Prove it. npx -y @tokenzero/cli doctor checks the gateway, the signer, the pricing table and your key; then watch spend against budget on the dashboard.
Questions people ask
How do I point Pydantic AI at TokenZero?
Pass base_url / baseURL = https://tokenzero.sh/v1 where Pydantic AI builds its client (agent.py) and keep your openai key; nothing else changes.
What does token-budget guardrails save on gpt-6.1-sol?
100,000 reference calls on gpt-6.1-sol cost $700 a month at list price; with monthly_budget_usd set to 500 the gateway returns 402 budget_exceeded once routed spend reaches $500.00 and resets on the first of the month, so a runaway loop cannot overspend.
Does token-budget guardrails change the model's output?
No. The guardrail only decides whether a request may reach the provider; past the cap it returns 402 with the reset time.
What does TokenZero cost?
Free up to $500 per month of routed spend; then 15% of verified savings with a 3x-ROI-or-$0 rule, capped plans available. Gateway overhead measured at 1.52 ms p50.