Spend controls for Pydantic AI tools

Pydantic AI agents call tools through Tool instances and plain callables. Paybond hooks that execution boundary — spend verify before side-effecting tools execute, then auto-evidence after success. Model inference stays on your provider client.

Python only — install paybond-kit[pydantic-ai] for the native adapter.

Adapter reference: /docs/kit/pydantic-ai.

• spend verify before Tool

  Wrapped Tool / callable handlers authorize operation and amount before paid work.

• Auto-evidence

  Guarded tools finalize spend and submit signed evidence after success.

• Policy budgets

  Versioned YAML caps per-call and intent spend for type-safe Python agents.

• Python native

  Install paybond-kit[pydantic-ai] — TypeScript stacks use agent-agnostic or another adapter.

Why Paybond (not just Pydantic AI checks)?

Pydantic AI prepare hooks and host approvals do not enforce a spend limit, a per-operation permission check (capability token), or a signed completion receipt tied to a spend agreement (intent).

How it works

3-minute quickstart

Smoke the pydantic-ai adapter sandbox contract:

paybond login
paybond agent demo pydantic-ai smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format table

paybond login
paybond agent demo pydantic-ai smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format table

Install the extra first:

pip install "paybond-kit[pydantic-ai]"

pip install "paybond-kit[pydantic-ai]"

When the smoke succeeds you should see:

• ✓ Spend approved
• ✓ Tool completed
• ✓ Evidence verified (cost_and_completion)

What success looks like

Scaffold

paybond init agent-middleware --framework pydantic-ai --out paybond_pydantic_ai.py
paybond policy init --preset saas --out paybond.policy.yaml

paybond init agent-middleware --framework pydantic-ai --out paybond_pydantic_ai.py
paybond policy init --preset saas --out paybond.policy.yaml

Wire middleware

from pydantic_ai import Agent
from paybond_kit import Paybond
from paybond_kit.agent.registry import create_paybond_tool_registry
from paybond_kit.pydantic_ai import create_paybond_pydantic_ai_config

# Price lives in your fare table — not in an LLM-invented amount_cents.
FARES = {"SFO-SEA": 18_900}

def book_flight(route: str, seats: int = 1) -> dict:
    """Book a flight. Fare comes from the fare table, not the model."""
    return {
        "status": "completed",
        "route": route,
        "cost_cents": FARES[route] * seats,
    }

paybond = await Paybond.open(api_key=os.environ["PAYBOND_API_KEY"])
run = await paybond.agent_run.bind(
    {
        "bootstrap": {
            "kind": "sandbox",
            "operation": "book_flight",
            "requested_spend_cents": 18_900,
            "completion_preset": "cost_and_completion",
        },
        "registry": create_paybond_tool_registry(
            {
                "default_deny": True,
                "side_effecting": {
                    "book_flight": {
                        "operation": "book_flight",
                        "evidence_preset": "cost_and_completion",
                        "spend_cents": lambda args: FARES[args["route"]]
                        * int(args.get("seats", 1)),
                    }
                },
            }
        ),
    }
)
guarded = create_paybond_pydantic_ai_config(run, [book_flight, search_catalog]).tools
agent = Agent("openai:gpt-4o", tools=guarded)

Manual hook wiring

When you already bound a PaybondAgentRun:

from paybond_kit.pydantic_ai import create_paybond_pydantic_ai_config

config = create_paybond_pydantic_ai_config(run, tools)
guarded_tools = config.tools
# Or wrap incrementally: config.wrap_tool(new_tool)

Approval holds: when Paybond returns an approval hold, guarded tools raise pydantic_ai.ModelRetry with a Paybond message. Approve in the tenant console, then retry with the same operation, amount, metadata, and approvalToken. Hard denials must not execute the tool.

Bypass classes: provider native tools, unwrapped MCP/toolsets, and tools registered with @agent.tool without going through Paybond wrap are not governed.

Production checklist

Works with

Ready to test?

Related guides

• Agent middleware — run binding and policy hot-reload
• Agent policy-as-code — long-lived agents with GitOps YAML
• Agent-agnostic spend controls — fallback for mixed runtimes

Developer reference: /docs/kit/pydantic-ai.