Python example projects

Runnable Python examples for Paybond Kit — agent middleware and framework adapters with TypeScript parity where available.

Paybond ships runnable Python examples under examples/ in the repository. Use them as reference implementations when you want a complete application structure beyond the Python quickstart.

Each example installs paybond-kit from the local monorepo (editable or path dependency) so SDK and example changes can be tested together. External apps should install the published wheel with pip install paybond-kit instead.

Example catalog

Example	Path	What it demonstrates
Agent-agnostic middleware	`examples/paybond-kit-runtime-agent-python/`	`create_paybond_generic_agent_config` with registry, bind, and auto-evidence
LangGraph	`examples/paybond-kit-langgraph-python/`	`run_langgraph_sandbox_demo` and `paybond_awrap_tool_call` on the ToolNode boundary
Claude Agent SDK	`examples/paybond-kit-claude-agents-python/`	`create_paybond_claude_agents_config` for in-process MCP tools

Choose an example

Adding spend controls to an agent? Pick the row that matches your runtime:

No agent framework (custom orchestrator, direct tool-use API) → Agent-agnostic adapter + paybond-kit-runtime-agent-python
LangGraph → LangGraph adapter + paybond-kit-langgraph-python
Claude Agent SDK → Claude Agents adapter + paybond-kit-claude-agents-python

TypeScript-only frameworks: Vercel AI SDK and OpenAI Agents SDK adapters are TypeScript-only today. Use the agent-agnostic path in Python, or see TypeScript example projects for those runtimes.

CLI smoke commands

Each example has a matching CLI smoke check. Pass --runtime python for Python kit execution:

paybond login   # optional for sandbox; required for real API

# Agent-agnostic
paybond agent demo generic smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

# LangGraph
paybond agent demo langgraph smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

# Claude Agents
paybond agent demo claude-agents smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json
paybond login   # optional for sandbox; required for real API

# Agent-agnostic
paybond agent demo generic smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

# LangGraph
paybond agent demo langgraph smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

# Claude Agents
paybond agent demo claude-agents smoke \
  --runtime python \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

For the fastest local path without an API key, use paybond dev loop --offline — see Agent quickstart.

Cloneable starter templates

Use standalone templates under templates/ or scaffold with either CLI:

paybond init --template invoice-agent
paybond init --template travel-agent --force
paybond init --template invoice-agent
paybond init --template travel-agent --force

The Python-native starter is paybond-invoice-agent (LangGraph + saas preset). Other templates are TypeScript-first but copy cleanly from Python kit as well.

Running from a source checkout

Each example directory includes a README with setup steps. The usual pattern:

cd examples/<example-name>
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py
cd examples/<example-name>
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Middleware examples typically need PAYBOND_API_KEY from paybond login or PAYBOND_API_KEY=pb_test_sandbox with a mock Gateway.

Optional extras for framework adapters:

pip install "paybond-kit[langgraph]"
pip install "paybond-kit[claude-agents]"
pip install "paybond-kit[langgraph]"
pip install "paybond-kit[claude-agents]"

Partner dry run (Python)

examples/partner-dry-run-wiremock/ is a WireMock + Testcontainers harness for local Gateway and Signal contract testing. It is not an agent middleware demo — use it when validating HTTP integration contracts without a live Paybond stack. See the example README for Docker Compose and Testcontainers entry points.

What these examples are for

Understanding paybond-kit in a complete end-to-end agent middleware flow.
Seeing Python parity with the TypeScript adapter docs for LangGraph and Claude Agents.
Copying proven patterns for sandbox bootstrap, tool wrapping, and auto-evidence.
Validating a framework adapter in CI with the matching paybond agent demo … smoke --runtime python command.

For most teams, follow the Python quickstart or Agent quickstart first, then open the example that matches your stack.