Spend SDK quickstart

The SDK has no hard dependency on any provider. You bring your own OpenAI, Anthropic or Bedrock client. The next time your agent tries to spend over the cap, AgentGuard throws before the provider is called, so the blocked request is never dispatched or billed.

1. Install.
   Node.js

   npm install @agentguard-run/spend

   Python

   pip install agentguard-spend

2. Wrap your provider client. One call. Pass in your existing client, declare a cap, use the guarded client the same way.
   Node.js

   import Anthropic from '@anthropic-ai/sdk';
   import { withSpendGuardAnthropic } from '@agentguard-run/spend';
   
   const policy = {
     id: 'daily-cap-v1',
     name: 'Daily cap',
     scope: { tenantId: 'acme' },
     caps: [{ amountCents: 2000, window: 'per_day', action: 'block' }],
     mode: 'enforce',
     version: 1,
     effectiveFrom: new Date().toISOString(),
   };
   
   const guarded = withSpendGuardAnthropic(new Anthropic(), {
     policy,
     scope: { tenantId: 'acme', agentId: 'my-agent' },
   });
   
   await guarded.messages.create({
     model: 'claude-opus-4-7',
     max_tokens: 1024,
     messages: [{ role: 'user', content: 'hello' }],
   });

   Python

   from agentguard_spend import easy_install
   from anthropic import Anthropic
   
   client = easy_install(Anthropic(), daily_cap_dollars=20)
   
   client.messages.create(
       model="claude-opus-4-7",
       max_tokens=1024,
       messages=[{"role": "user", "content": "hello"}],
   )

   Every call through the wrapped client now runs a local preflight. Cost is projected from estimated input tokens and max_tokens. If the scope’s daily spend would cross the cap, AgentGuardBlockedError is thrown and the provider method is not invoked.
3. Watch it block. Drop the cap to a few cents and trigger a real call.
   Node.js

   try {
     await guarded.messages.create({ /* ... */ });
   } catch (err) {
     if (err.name === 'AgentGuardBlockedError') {
       console.log(err.toString()); // human-readable trace
       console.log(err.decision);   // policy decision; not a signed entry by itself
     }
   }

   Python

   from agentguard_spend import AgentGuardBlockedError
   
   try:
       client.messages.create(...)
   except AgentGuardBlockedError as err:
       print(err)                    # color-coded trace
       print(err.decision.action)    # "block"
       print(err.decision.cap_hit)   # which cap fired

4. Verify a receipt. Direct wrappers create signed entries only when config.signingKeys is supplied. The CLI demo creates local throwaway keys and a real signed chain.
   CLI

   agentguard demo
   agentguard verify
   # ✓ full chain valid
   # ✓ entry hashes match canonical JSON
   # ✓ signatures match supplied public key
   # ✓ no sequence gaps (ledger appears complete)

   Node API

   import { verifyChain } from '@agentguard-run/spend';
   
   const result = await verifyChain(entries, publicKey);
   console.log(result.ok ? 'valid' : result.reason);

State is single-process by default

In-memory state is single-process only. The public package exports an NDJSON decision-log store. Redis and Postgres implementations exist in source but are not exported by the package map. Implement the store interfaces before promising cross-worker state.

CapabilitiesCap windows, actions, scope dimensions, capability tiers, locales, CLI.

npm: @agentguard-run/spendPackage license permits production use up to 10,000 enforcement calls per calendar month.