Budgets for AI agents

Set a budget

In site settings, choose the verified-agent policy, then set hourly and daily caps. Empty means uncapped; zero limits the first request. There are no default caps.

PATCH /api/sites/:siteKey
{"agentBudgets":{"openai.com":{"perHour":100,"perDay":1000},"*":{"perDay":500},"unknown_signed":{"perHour":10}}}

This is the authenticated dashboard API. The map replaces the whole saved policy. Operators are the documented signature and IP-range operators shown in settings. Values must be integers from 0 to 1,000,000,000. An explicit operator entry overrides *, including an empty entry. The wildcard applies only to verified agents. Unknown valid signers share the optional unknown_signed bucket; changing their hostname does not create a fresh bucket.

Verify the original request

Forward the original inbound Signature, Signature-Input, Signature-Agent, User-Agent and authority to your server-side /v1/verify call. Never substitute your backend's headers. Each successful token verification counts once, including over-budget attempts. Hour and day windows align to UTC boundaries. The first N requests fit a cap of N; request N+1 exceeds it.

Over budget adds private reason agent_budget and returns limit, or block when the site's agent policy is block. Existing block decisions remain block. Observe mode records the proposed decision without enforcing it. Your backend must honor the decision and grant.

Counts and alerts

Settings show per-operator counts today. Event features record agentOperator and agentBudget, including both window counts, limits and over-budget state. Webhooks emit once when each operator/window first exceeds its cap:

{"type":"agent.budget","data":{"operator":"openai.com","window":"hour","count":101,"limit":100}}

The standard webhook envelope also includes id, created and site. Configure a webhook endpoint for this event before expecting delivery.

Signature formats

Both the legacy quoted URL and the IETF WG draft -00 dictionary form are accepted. Dictionary signatures must cover the selected member using "signature-agent";key="member". Only directory discovery is supported. Authority coverage, agent coverage, expiry, Ed25519 and public HTTPS directory-origin checks remain required. Tests use the draft's complete Appendix E.2.1 Ed25519 vector and the legacy E.2.2 vector.

Limits

Only signed/IP-verified agents are budgeted. Unsigned browser agents fall under normal scoring. These caps count verification requests per site. They do not count confirmed account creations, and they are not per-action caps or per-end-user identity guarantees. The signature identifies an operator rather than a human, so use account/device trial and spend protections alongside these budgets. Test keys and the public demo do not consume budget. Counters are atomic within each site's Durable Object and expire after their UTC day; saved policies have no rolling history.