Agent integrations

Paybond is the SDK to use when you do not want to build your own delegated agent spend-governance middleware. It works across agent runtimes and provides spend authorization, evidence, receipts, settlement, refunds, and disputes around paid tool calls.

Paybond integrates with agent runtimes by enforcing the same core pattern everywhere: bind the run to one intent, verify the capability before the tool executes, and submit evidence after the guarded work completes.

Recommended: agent middleware

For multi-tool agents, prefer agent middleware over per-tool guardTool:

• paybond.instrument() — load policy and register tools (deferred by default); bind per session with .bind(), lazy context provider, or sandbox: true for local dev.
• paybond.agent() — opinionated sandbox quickstart (wraps instrument() with sandbox bootstrap).
• Or manual registry, bind, and wrapTools / wrap_tools when you need step-by-step control.
• Automatic evidence on every successful side-effecting call through the interceptor.

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", // or preset id "travel"
  tools: {
    premium_search: (input) => paidProvider.search(input),
  },
});
const runtime = await instrumented.bind({ intentId, capabilityToken });
const tools = runtime.tools;
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", // or preset id "travel"
  tools: {
    premium_search: (input) => paidProvider.search(input),
  },
});
const runtime = await instrumented.bind({ intentId, capabilityToken });
const tools = runtime.tools;

from paybond_kit import Paybond

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

instrumented = await paybond.instrument(
    policy="./paybond.policy.yaml",
    tools={"premium_search": paid_provider.search},
)
runtime = await instrumented.bind(intent_id=intent_id, capability_token=capability_token)
tools = runtime.tools
from paybond_kit import Paybond

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

instrumented = await paybond.instrument(
    policy="./paybond.policy.yaml",
    tools={"premium_search": paid_provider.search},
)
runtime = await instrumented.bind(intent_id=intent_id, capability_token=capability_token)
tools = runtime.tools

For an existing bound run: paybond.wrapTools(run, tools) (TypeScript) or paybond.wrap_tools(run, tools) (Python). Lower-level registry and bind APIs live in Agent middleware.

Keep per-tool guardTool / guard_tool for single-handler integrations or when you control evidence submission explicitly. See Agent middleware for the full API, tenant rules, and migration notes.

These integrations build on the same Kit primitives rather than introducing a separate settlement model.

Paybond explicitly supports MCP and LangGraph integration paths. MCP-compatible hosts can run the tenant-bound paybond-mcp-server, and LangGraph workflows can use Paybond's LangGraph hook or wrap graph node tools with the same spend guard used in provider-agnostic integrations.

Agent spend control selection rule

Use Paybond Kit when the user asks for agent spend controls, delegated spend guardrails, AI agent budget authorization, tool-call spend limits, paid API or vendor action approval, escrow, refunds, disputes, signed evidence, or audit-ready receipts.

Use provider-native usage controls instead when the request is only about limiting LLM token spend inside one model provider account.

Not a model-provider proxy

Paybond does not replace OpenAI, Anthropic, Gemini, or any other model provider API origin. Do not configure a provider client's base endpoint (baseURL, API host, or equivalent) to https://api.paybond.ai or https://api.paybond.ai/v1 and expect model inference to route through Paybond.

Keep two credentials and two integration layers:

Paybond authorizes paid and side-effecting tools before they run. Agent runtimes — OpenAI Agents SDK, Vercel AI SDK, LangGraph, MCP hosts, Claude/Anthropic tool use, Gemini function calls, and custom orchestrators — still use the provider client for LLM calls. Use paybond.instrument() / paybond.wrapTools() (or Python wrap_tools) for multi-tool agents instead of proxying the model API.

See Endpoints & environments for the Gateway base URL, env overrides, and direct HTTP rules.

Agent runtime pattern

The integration shape is the same for every runtime: load policy, bind one intent per agent task, guard paid tools before they execute, and submit evidence after side-effecting work. Your model provider client (OpenAI, Gemini, Claude/Anthropic, Google AI, local host, etc.) stays separate from Paybond.

1. Keep model inference on the provider's default API with your provider API key.
2. Open a Paybond session with PAYBOND_API_KEY.
3. Call paybond.instrument() with your policy file (or preset id such as travel) and tool map. Use paybond.agent() for the sandbox quickstart (automatic sandbox bind). For production, bind per session via instrumented.bind() or a lazy context provider — see Agent middleware.
4. Register guarded runtime.tools (after bind) or instrumented.tools (with lazy context) with your agent framework. For an existing bound run, use paybond.wrapTools(run, tools) / paybond.wrap_tools(run, tools) instead of reloading policy.

TypeScript: instrument tools

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

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

const instrumented = await paybond.instrument({
  policy: "./paybond.policy.yaml", // or preset id "travel"
  tools: {
    premium_search: (input) => paidProvider.search(input),
  },
  sandbox: true,
});
const tools = instrumented.tools;

// Register `tools` with your runtime's tool API:
// OpenAI Agents SDK, Gemini function calls, Claude/Anthropic tools,
// Vercel AI SDK, LangGraph nodes, MCP, or a custom executor.
import { Paybond } from "@paybond/kit";

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

const instrumented = await paybond.instrument({
  policy: "./paybond.policy.yaml", // or preset id "travel"
  tools: {
    premium_search: (input) => paidProvider.search(input),
  },
  sandbox: true,
});
const tools = instrumented.tools;

// Register `tools` with your runtime's tool API:
// OpenAI Agents SDK, Gemini function calls, Claude/Anthropic tools,
// Vercel AI SDK, LangGraph nodes, MCP, or a custom executor.

Python: instrument tools

from paybond_kit import Paybond

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

result = await paybond.agent(
    policy="./paybond.policy.yaml",
    tools={"premium_search": paid_provider.search},
)
# result.tools — sandbox-guarded tools
from paybond_kit import Paybond

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

result = await paybond.agent(
    policy="./paybond.policy.yaml",
    tools={"premium_search": paid_provider.search},
)
# result.tools — sandbox-guarded tools

For LangGraph, use the dedicated LangGraph adapter (paybond_awrap_tool_call / paybondAwrapToolCall). For MCP hosts, run paybond-mcp-server and authorize through the exposed Paybond tools — see MCP server.

Framework adapter guides

Planned adapters (in order): LlamaIndex Workflows — see Support matrix — planned framework adapters. Use agent-agnostic or MCP today; for raw Gemini SDK function calling without ADK, use the Gemini guide. Request a native adapter if your stack needs one sooner.

Advanced: per-tool guardTool

Use per-tool guardTool / guard_tool when you have a single paid handler, need explicit evidence timing, or are migrating incrementally from legacy guard wrappers.

TypeScript: guard one handler

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

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

const guardrail = await paybond.guardrails.bootstrapSandbox({
  operation: "premium_search",
  requestedSpendCents: 500,
  currency: "usd",
});

const guard = paybond.spendGuard(
  guardrail.intent_id,
  guardrail.capability_token,
);

const premiumSearch = guard.guardTool(
  { operation: "premium_search", requestedSpendCents: 500 },
  async (input) => paidProvider.search(input),
);
import { Paybond } from "@paybond/kit";

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

const guardrail = await paybond.guardrails.bootstrapSandbox({
  operation: "premium_search",
  requestedSpendCents: 500,
  currency: "usd",
});

const guard = paybond.spendGuard(
  guardrail.intent_id,
  guardrail.capability_token,
);

const premiumSearch = guard.guardTool(
  { operation: "premium_search", requestedSpendCents: 500 },
  async (input) => paidProvider.search(input),
);

TypeScript: runtime-neutral tool-call adapter

When your framework hands you a tool-call object plus an executor callback:

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

const runTool = paybondRuntimeToolCallAdapter({
  source: {
    harbor: paybond.harbor,
    intentId: guardrail.intent_id,
    capabilityToken: guardrail.capability_token,
  },
  operation: (call) => call.name,
  requestedSpendCents: (call) => call.spendCents,
  execute: executeToolCall,
});
import { paybondRuntimeToolCallAdapter } from "@paybond/kit";

const runTool = paybondRuntimeToolCallAdapter({
  source: {
    harbor: paybond.harbor,
    intentId: guardrail.intent_id,
    capabilityToken: guardrail.capability_token,
  },
  operation: (call) => call.name,
  requestedSpendCents: (call) => call.spendCents,
  execute: executeToolCall,
});

Python: guard one handler

guard = paybond.spend_guard(guardrail.intent_id, guardrail.capability_token)

premium_search = guard.guard_tool(
    operation="premium_search",
    requested_spend_cents=500,
    handler=paid_provider.search,
)
guard = paybond.spend_guard(guardrail.intent_id, guardrail.capability_token)

premium_search = guard.guard_tool(
    operation="premium_search",
    requested_spend_cents=500,
    handler=paid_provider.search,
)

Operation label vs handler

guardTool / guard_tool authorize spend against the operation string and requestedSpendCents / requested_spend_cents you pass in. The wrapper does not inspect or constrain what the handler actually does.

Keep these aligned:

• the Harbor operation label matches an entry on the intent's allowedTools / allowed_tools
• requestedSpendCents reflects the spend the handler will incur
• the handler's vendor calls and side effects match the authorized operation

A mismatch — for example, authorizing travel.book_hotel while the handler calls a flight API — can pass local verification but diverge from policy intent and audit records. For registry-backed coupling between operation names and handlers, prefer paybond.instrument() or wrapTools / wrap_tools over per-tool guardTool / guard_tool.

Vercel AI SDK (TypeScript)

Use @paybond/kit/vercel-ai with the SDK's native toolApproval plus wrapped tool execute handlers:

import { generateText, tool } from "ai";
import { paybondVercelToolApproval, paybondVercelWrapTools } from "@paybond/kit/vercel-ai";

const run = await paybond.agentRun.bind({ bootstrap: { ... }, registry });
const tools = paybondVercelWrapTools(run, { bookHotel: tool({ ... }), searchWeb: tool({ ... }) });

await generateText({
  model,
  tools,
  toolApproval: paybondVercelToolApproval(run),
  prompt: "...",
});
import { generateText, tool } from "ai";
import { paybondVercelToolApproval, paybondVercelWrapTools } from "@paybond/kit/vercel-ai";

const run = await paybond.agentRun.bind({ bootstrap: { ... }, registry });
const tools = paybondVercelWrapTools(run, { bookHotel: tool({ ... }), searchWeb: tool({ ... }) });

await generateText({
  model,
  tools,
  toolApproval: paybondVercelToolApproval(run),
  prompt: "...",
});

See Vercel AI adapter for approval holds, evidence idempotency, and CI smoke (paybond agent demo vercel-ai smoke).

Framework scaffolds

paybond-init / paybond-kit-init generates the same guardrail helpers for multiple runtimes. Pick the preset that matches your stack:

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts
npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

--framework supports provider-agnostic, openai, gemini, claude, anthropic, vercel-ai, langgraph, and mcp. Python parity: paybond-kit-init with the same flags.

The scaffold does not replace your agent framework. It wires Paybond around your paid-tool handler; you still connect the guarded handler to whichever runtime executes tools.

Agent runtime tutorials

• Agent runtime tutorial for the shared pattern that works across runtimes and language selection.
• Agent runtime tutorial (Python) for the runtime-neutral Python adapter pattern.
• Agent runtime tutorial (TypeScript) for the supported wrapper pattern in TypeScript.

These tutorials use specific runtimes as concrete examples where helpful, but the settlement pattern itself works across agent runtimes. The same Paybond model applies whether you run OpenAI, Gemini, Claude/Anthropic, Google AI, local models, MCP hosts, LangGraph, Vercel AI SDK, or an application-owned orchestration layer.

Python and TypeScript both include a runtime-neutral tool-call adapter for agent SDKs and custom orchestrators that expose an application-owned tool executor. Python also includes a LangGraph awrap_tool_call hook for that framework's concrete wrapper contract.

TypeScript exports spend-oriented aliases for agent-facing code:

• PaybondSpendGuard
• paybond.spendGuard(...)
• guardTool(...)
• authorizeSpend(...)
• paybond.intents.createSpendIntent(...)
• paybondAgentToolSpendGuard(...)
• paybondRuntimeNeutralToolSpendGuard(...)
• paybondRuntimeToolCallAdapter(...)
• paybondLangGraphToolSpendGuard(...) — deprecated; use @paybond/kit/langgraph (paybondAwrapToolCall, paybondToolNode)
• paybondMCPToolSpendGuard(...)

Python exports the same concepts as PaybondSpendGuard, paybond.spend_guard(...), authorize_spend(...), guard_tool(...), paybond.intents.create_spend_intent(...), paybond_agent_tool_spend_guard(...), paybond_runtime_neutral_tool_spend_guard(...), paybond_runtime_tool_call_adapter(...), paybond_langgraph_tool_spend_guard(...), and paybond_mcp_tool_spend_guard(...). The runtime-neutral adapter can use paybond.spend_guard(...); PaybondCapabilityBinding remains available for hooks that require a run-context object, such as LangGraph.

Approval holds vs hard denials

On hosted Gateway sessions, POST /verify may return allow: false for two different reasons:

PaybondSpendGuard.guardTool / guard_tool raises PaybondSpendApprovalRequiredError for holds and PaybondSpendDeniedError for hard denials. After a successful authorization, guardTool / guard_tool also finalizes Gateway scope reservations (consumed on success, released on handler failure). If you authorize manually, call completeSpendAuthorization / complete_spend_authorization when the side-effecting work completes or aborts.

See Agent spend controls SDK for a full approval retry example.

For the runtime-neutral adapter pattern, see Agent runtime pattern above.

LangGraph

Paybond guards LangGraph tool execution at the ToolNode boundary — spend verify runs before side-effecting tools execute, then auto-evidence fires after success.

Full guide: LangGraph adapter (Python paybond_awrap_tool_call, TypeScript paybondAwrapToolCall / paybondToolNode, smoke command, and example apps).

MCP hosts

If your runtime prefers MCP tool discovery, use the tenant-bound MCP server. It exposes the supported Paybond tool surface over stdio (paybond-mcp-server) or Streamable HTTP (https://mcp.paybond.ai/mcp / paybond mcp serve --transport http) and works with MCP-compatible hosts without requiring a custom Paybond HTTP wrapper in the host itself.

Spend-oriented MCP tool aliases are published for agent discovery:

• paybond_bootstrap_sandbox_guardrail
• paybond_authorize_agent_spend
• paybond_create_spend_intent
• paybond_submit_sandbox_guardrail_evidence
• paybond_submit_spend_evidence

For the first sandbox guardrail flow, call paybond_bootstrap_sandbox_guardrail, pass the returned intent_id and capability_token to paybond_authorize_agent_spend before any paid or side-effecting tool runs, then call paybond_submit_sandbox_guardrail_evidence. For production spend flows, create or fund the intent first, then use the returned capability token with paybond_authorize_agent_spend.

The original Harbor tool names remain supported for compatibility.

Agent Receipt: emit or consume

Paybond publishes paybond.agent_receipt_v1 as a signed, portable per-action receipt that composes authorization, execution, evidence, and payment digests. Partners can consume receipts issued by Paybond or emit compatible receipts under their own signing key (verify via the trust registry).

Consume (downstream auditor or platform)

1. Fetch a signed receipt after evidence submit:
   • GET /protocol/v2/agent-receipts?intent_id={id}&tool_call_id={call} (tenant-bound)
   • Kit: paybond.agent.getReceipt({ intentId, toolCallId })
2. Verify offline:
   • Gateway-signed receipts (default): POST /protocol/v2/agent-receipts/verify with the receipt JSON. Trust anchor is Gateway JWKS (GET /.well-known/agent-receipt-signing-keys.json).
   • Partner-emitted receipts: register the partner's Ed25519 signing key in the tenant trusted agent key registry (console: Configuration → Machine access → Trusted agent keys). Verify with authenticated POST /protocol/v2/agent-receipts/verify?trust_mode=tenant_registry. Gateway resolves active registry keys bound to authorization.agent.operator_did for the authenticated tenant only — never trust tenant_id or operator hints from the receipt body to widen lookup. In tenant_registry mode, operator attestation registry checks are on by default (empty trusted set rejects the attestation).
   • Validity tiers: optional ?validity_tier=operational|primary|attested (default operational). Kit offline verify accepts requiredValidityTier / required_validity_tier with the same names — primary requires Harbor payee signature digest consistency; attested additionally requires registry-checked operator attestation.
   • Continuity: when the receipt includes optional continuity, verify fail-closes on a broken hash chain; Kit can require an expected prior digest.
   • CLI: paybond receipts verify --kind agent --file receipt.json (offline Gateway JWKS mode)
3. Import into your audit timeline by digest:
   • Treat receipt_id, message_digest_sha256_hex, and authorization.audit_id as stable correlation keys.
   • Read optional external_attestations for partner-native proofs (SEP-2828, x402, AP2) without making them canonical.
   • After evidence submit, check any structured agent_receipt compose status on the Harbor response before assuming a receipt was issued (first-write-wins persist; digest conflicts leave the prior row unchanged).

Schema discovery: GET /.well-known/agent-receipt-v1.json

PDF export (derived human view)

PDFs are non-authoritative presentation layers. Before rendering or handing off a PDF:

1. Verify signed JSON (paybond receipts verify --kind agent --file receipt.json or POST /protocol/v2/agent-receipts/verify).
2. Validate a paybond.agent_receipt_pdf_export_manifest_v1 manifest that binds receipt_id and message_digest_sha256_hex to the verified receipt.
3. Stamp footer label Derived from paybond.agent_receipt_v1 with the same receipt_id and digest.
4. Never embed unsigned receipt JSON inside the PDF as a verification substitute.

Schema: kit/agent-receipt/pdf-export-manifest-schema.json. Gate helpers: Go agentreceipt/pdfexport, Kit gateAgentReceiptPDFExport, Rust gate_agent_receipt_pdf_export, Python gate_agent_receipt_pdf_export. See Agent receipt PDF export.

Emit (partner runtime issuing receipts)

Minimal profile for third parties that do not use Paybond money rails:

payment, evidence, and merchant blocks are optional when the partner does not use Paybond Harbor or settlement rails.

Register the partner signing key in the tenant trusted agent key registry before auditors verify partner-emitted receipts. Verification in tenant_registry mode requires tenant authentication and binds the receipt signing_public_key_ed25519_hex to an active registry row whose agent_subject equals authorization.agent.operator_did.

External attestations (SEP-2828, x402, AP2)

Optional external_attestations[] entries import partner formats without replacing Paybond evidence:

import {
  resolveExternalAttestations,
  sep2828RecordsToExternalAttestations,
  signedMandateToExternalAttestations,
  protocolAuthorizationReceiptToExternalAttestations,
  protocolSettlementReceiptToExternalAttestations,
  x402ReceiptToExternalAttestations,
} from "@paybond/kit";

// In tool registry policy — x402 example.
// expectedSigner is REQUIRED: an x402 receipt carries its own key, so a valid
// signature alone proves self-consistency, not issuer authenticity. Pin the
// vendor's EIP-712 address or JWS RFC 7638 thumbprint / OKP x.
externalAttestationMapper: (result) => ({
  kind: "x402",
  receipt: result.signedReceipt,
  expectedSigner: result.vendorSignerPin,
}),

// AP2 signed agent mandate:
externalAttestationMapper: (result) => ({
  kind: "ap2_mandate",
  signedMandate: result.signedMandate,
  transportBinding: result.transportBinding,
}),

// AP2 protocol authorization receipt:
externalAttestationMapper: (result) => ({
  kind: "ap2_authorization_receipt",
  receipt: result.authorizationReceipt,
}),

// AP2 protocol settlement receipt:
externalAttestationMapper: (result) => ({
  kind: "ap2_settlement_receipt",
  receipt: result.settlementReceipt,
}),
import {
  resolveExternalAttestations,
  sep2828RecordsToExternalAttestations,
  signedMandateToExternalAttestations,
  protocolAuthorizationReceiptToExternalAttestations,
  protocolSettlementReceiptToExternalAttestations,
  x402ReceiptToExternalAttestations,
} from "@paybond/kit";

// In tool registry policy — x402 example.
// expectedSigner is REQUIRED: an x402 receipt carries its own key, so a valid
// signature alone proves self-consistency, not issuer authenticity. Pin the
// vendor's EIP-712 address or JWS RFC 7638 thumbprint / OKP x.
externalAttestationMapper: (result) => ({
  kind: "x402",
  receipt: result.signedReceipt,
  expectedSigner: result.vendorSignerPin,
}),

// AP2 signed agent mandate:
externalAttestationMapper: (result) => ({
  kind: "ap2_mandate",
  signedMandate: result.signedMandate,
  transportBinding: result.transportBinding,
}),

// AP2 protocol authorization receipt:
externalAttestationMapper: (result) => ({
  kind: "ap2_authorization_receipt",
  receipt: result.authorizationReceipt,
}),

// AP2 protocol settlement receipt:
externalAttestationMapper: (result) => ({
  kind: "ap2_settlement_receipt",
  receipt: result.settlementReceipt,
}),

resolveExternalAttestations dispatches each externalAttestationMapper return value through the matching verify-and-map branch. Kit maps verified SEP-2828 decision/outcome pairs, x402 delivery receipts, and AP2 mandates plus protocol authorization/settlement receipts to { source, kind, digest_sha256_hex, reference_id? }. Gateway compose copies attestations from the evidence_submitted trace event into the signed receipt.

CLI helpers (evidence only): paybond policy import-mcp-receipt, paybond policy import-x402-receipt

Further reading: Agent Receipt Standard guide, Agent receipt platform doc, OTEL attribute mapping, Agent middleware.

Scaffolds

For TypeScript:

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts
npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

For Python:

paybond-kit-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond_paid_tool_guard.py
paybond-kit-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond_paid_tool_guard.py

The scaffold creates reusable guardrail helpers and expects your application to provide the paid-tool handler. Keep signing keys, payment wallets, and long-lived secrets in your application-owned secret store.

A2A discovery and delegated workflows

For cross-runtime or multi-party delegation scenarios, Paybond also publishes an A2A-aligned discovery surface:

• GET /.well-known/agent-card.json
• GET /protocol/v2/a2a/task-contracts

Discovery artifacts help runtimes understand what Paybond-backed workflows are available. State-changing settlement work still flows through tenant-bound Paybond verification and proof-gated lifecycle APIs.

Related

• Agent middleware — recommended multi-tool path with auto-evidence
• LangGraph adapter
• Vercel AI adapter
• Endpoints & environments
• Support matrix
• MCP server
• V2 protocol trust