Spend controls for OpenAI Agents SDK tools

The OpenAI Agents SDK runs tools through FunctionTool.invoke. Paybond hooks that boundary — Harbor verifies spend before side effects and auto-submits evidence after success — not as model middleware.

Install @paybond/openai-agents (npm) or paybond-kit[openai-agents] (pip). Adapter reference: /docs/kit/openai-agents.

• spend verify before invoke

  Input guardrails authorize operation and amount before FunctionTool.invoke runs.

• Auto-evidence

  Wrapped invoke finalizes spend and submits signed evidence after tool success.

• Policy budgets

  Versioned YAML caps per-call and intent spend — default-deny for side-effecting tools.

• TypeScript and Python

  Same openai-agents adapter on npm (@paybond/openai-agents) and pip (paybond-kit[openai-agents]).

Why Paybond (not just SDK guardrails)?

OpenAI Agents SDK guardrails check model input/output and can pause for approvals. They 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 openai-agents adapter sandbox contract — no OpenAI credentials required for this check:

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

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

When the smoke succeeds you should see:

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

What success looks like

Scaffold

# TypeScript
paybond init agent-middleware --framework openai --out paybond-openai-agents.ts
# Python
paybond init agent-middleware --framework openai --out paybond_agent_middleware_openai.py
paybond policy init --preset travel --out paybond.policy.yaml

# TypeScript
paybond init agent-middleware --framework openai --out paybond-openai-agents.ts
# Python
paybond init agent-middleware --framework openai --out paybond_agent_middleware_openai.py
paybond policy init --preset travel --out paybond.policy.yaml

Validate before deploy:

paybond policy validate-tools --file paybond.policy.yaml --local-only

paybond policy validate-tools --file paybond.policy.yaml --local-only

Wire middleware

import { tool, Agent, Runner } from "@openai/agents";
import { z } from "zod";
import { Paybond } from "@paybond/kit";

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

const bookHotelTool = tool({
  name: "travel.book_hotel",
  description: "Book a hotel room",
  parameters: z.object({
    city: z.string(),
    estimatedPriceCents: z.number().int().nonnegative(),
  }),
  execute: async (args) => bookHotel(args),
});

const { agentTools: tools, runConfig } = await paybond.agent({
  policy: "travel",
  framework: "openai-agents",
  tools: [bookHotelTool, searchWebTool],
});

const agent = new Agent({ name: "Travel", tools });
await Runner.run(agent, "Book a hotel in Lisbon under $200.", { ...runConfig });

import { tool, Agent, Runner } from "@openai/agents";
import { z } from "zod";
import { Paybond } from "@paybond/kit";

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

const bookHotelTool = tool({
  name: "travel.book_hotel",
  description: "Book a hotel room",
  parameters: z.object({
    city: z.string(),
    estimatedPriceCents: z.number().int().nonnegative(),
  }),
  execute: async (args) => bookHotel(args),
});

const { agentTools: tools, runConfig } = await paybond.agent({
  policy: "travel",
  framework: "openai-agents",
  tools: [bookHotelTool, searchWebTool],
});

const agent = new Agent({ name: "Travel", tools });
await Runner.run(agent, "Book a hotel in Lisbon under $200.", { ...runConfig });

Install Python extra: pip install "paybond-kit[openai-agents]". The scaffold (paybond_agent_middleware_openai.py) shows FunctionTool and create_guarded_agent for policy-driven bootstrap.

Manual hook wiring

When you already bound a PaybondAgentRun:

import { createPaybondOpenAIAgentsConfig } from "@paybond/kit/openai-agents";

const config = createPaybondOpenAIAgentsConfig(run, sdkTools);
const guardedTools = config.tools;

import { createPaybondOpenAIAgentsConfig } from "@paybond/kit/openai-agents";

const config = createPaybondOpenAIAgentsConfig(run, sdkTools);
const guardedTools = config.tools;

Production: omit sandbox defaults on paybond.agent() / paybond.instrument(), use deferred bind, then instrumented.bind({ intentId, capabilityToken }) per session. Tenant and intent IDs come from the Paybond session binding — never from unauthenticated tool args.

Production checklist

Works with

Ready to test?

Related guides

• Agent middleware — bind, registry, tenant isolation
• OpenAI Responses API spend controls — Responses API tool boundary
• Agent policy-as-code — versioned YAML
• Agent-agnostic spend controls — default { name, execute } wiring

Developer reference: /docs/kit/openai-agents.