paybondpaybond
Sign in

Agent-agnostic spend controls

Framework-agnostic agent spend controls with createPaybondGenericAgentConfig — no vendor SDK required. Install @paybond/agent or @paybond/kit/agent. TypeScript and Python parity.

Paybond's recommended default when you have no agent framework SDK — or when you call Claude/Gemini tool-use, a custom orchestrator, or a queue worker directly. One createPaybondGenericAgentConfig call wraps { name, execute } tools with full middleware: Harbor verify, approval holds, spend finalize, and auto-evidence.

Install

Install

npm install @paybond/agent

Import from @paybond/agent

import { createPaybondGenericAgentConfig } from "@paybond/agent";
  • Equivalent subpath on the core package: `@paybond/kit/agent` — use `@paybond/kit` when you need multiple adapters in one app.

One-liner (sandbox): paybond.instrument({ policy, tools, sandbox: true }) or paybond.agent({ policy, tools }) returns guarded tools on .tools. Production: deferred default + bind() per session.

Manual wiring: bind a PaybondAgentRun, then call createPaybondGenericAgentConfig(run, tools) when you need step-by-step control.

See Agent middleware for policy files, registry rules, and tenant isolation.

TypeScript

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({ apiKey: process.env.PAYBOND_API_KEY! });

const instrumented = await paybond.instrument({
  policy: "./paybond.policy.yaml",
  tools: {
    "travel.book_hotel": async (args: { city: string; estimatedPriceCents: number }) =>
      bookHotel(args),
    searchWeb: async (args: { query: string }) => searchWeb(args),
  },
});

const run = instrumented.run;
const tools = instrumented.tools;

// Optional authorize-only pre-check before execute:
import { createPaybondGenericInputGuard } from "@paybond/kit";
const inputGuard = createPaybondGenericInputGuard(run);

const preflight = await inputGuard.evaluate({
  toolName: "travel.book_hotel",
  toolCallId: "call-1",
  arguments: { city: "Lisbon", estimatedPriceCents: 18_700 },
});

const bookHotelTool = tools.find((t) => t.name === "travel.book_hotel")!;
const result = await bookHotelTool.execute({
  toolName: "travel.book_hotel",
  toolCallId: "call-1",
  arguments: { city: "Lisbon", estimatedPriceCents: 18_700 },
});

Python

import os

from paybond_kit import Paybond

paybond = await Paybond.open(api_key=os.environ["PAYBOND_API_KEY"])

result = await paybond.instrument(
    policy="./paybond.policy.yaml",
    framework="generic",
    tools={
        "travel.book_hotel": book_hotel,
        "search.web": search_web,
    },
)

tools = result.agent_tools
run = result.run

from paybond_kit.agent import create_paybond_generic_input_guard

input_guard = create_paybond_generic_input_guard(run)
preflight = await input_guard.evaluate(
    {
        "tool_name": "travel.book_hotel",
        "tool_call_id": "call-1",
        "arguments": {"city": "Lisbon", "estimated_price_cents": 18_700},
    }
)

wrapped = next(t for t in tools if t["name"] == "travel.book_hotel")
result = await wrapped["execute"](
    {
        "tool_name": "travel.book_hotel",
        "tool_call_id": "call-1",
        "arguments": {"city": "Lisbon", "estimated_price_cents": 18_700},
    }
)

When to use agent-agnostic vs framework adapters

SituationUse
Custom orchestrator, queue worker, or direct tool-use APIAgent-agnostic (generic)
LangGraph ToolNodeLangGraph adapter
Claude Agent SDK in-process MCPClaude Agents adapter
Vercel AI SDKVercel AI adapter (TypeScript only)
OpenAI Agents SDKOpenAI Agents adapter (TypeScript only)
MCP hostsMCP server
Mastra / CrewAI / Cloudflare AgentsPlanned — request an adapter

Scaffold and smoke

paybond init agent-middleware --framework generic --out ./paybond-generic.ts

paybond agent demo generic smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

The smoke command exercises authorize → execute → auto-evidence without a live LLM. Use --runtime python with the Python CLI or --runtime typescript with the TypeScript CLI.

Example apps: examples/paybond-kit-agent-middleware-typescript, examples/paybond-kit-runtime-agent-python.