paybondpaybond
Sign in

Cloudflare Agents adapter

Paybond adapter for Cloudflare Agents — wrap getTools AI SDK tool execute handlers with spend verify and auto-evidence.

Paybond integrates with Cloudflare Agents at the getTools() / AI SDK tool() boundary — spend verify runs before side-effecting tools execute, then auto-evidence fires after success. Model inference stays on your Cloudflare Agent; Paybond guards paid and side-effecting tool calls only.

TypeScript only. Python Kit does not ship a Cloudflare Agents adapter — use agent-agnostic middleware or MCP for Python hosts.

Install

Install

npm install @paybond/cloudflare-agents agents ai

Import from @paybond/cloudflare-agents

import { createPaybondCloudflareAgentsConfig } from "@paybond/cloudflare-agents";
  • Equivalent subpath on the core package: `@paybond/kit/cloudflare-agents` — use `@paybond/kit` when you need multiple adapters in one app.
  • TypeScript only. Python Kit does not ship a Cloudflare Agents adapter — use agent-agnostic middleware or MCP.
  • Optional peers: agents >= 0.10.0 and ai >= 4.0.0 (Cloudflare Agents uses AI SDK tools in getTools(); smoke requires ai only).
  • Smoke: `paybond agent demo cloudflare-agents smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json`.

One-liner (sandbox): paybond.instrument({ policy, framework: "cloudflare-agents", tools, sandbox: true }) or paybond.agent({ policy, framework: "cloudflare-agents", tools }) returns guarded tools plus hooks.toolApproval for AI SDK turns. Production: omit sandbox and call instrumented.bind() per session.

import { tool } from "ai";
import { z } from "zod";
import { Paybond } from "@paybond/kit";

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

const { tools, hooks } = await paybond.instrument({
  policy: "./paybond.policy.yaml",
  framework: "cloudflare-agents",
  tools: {
    "travel.book_hotel": tool({
      description: "Book a hotel room",
      inputSchema: z.object({
        city: z.string(),
        estimatedPriceCents: z.number().int().nonnegative(),
      }),
      execute: async (args) => bookHotel(args),
    }),
  },
});

// Return `tools` from your Agent `getTools()` and pass `hooks.toolApproval` to streamText/generateText.

Already bound a run? Use createPaybondCloudflareAgentsConfig(run, tools) from @paybond/kit/cloudflare-agents or @paybond/cloudflare-agents.

See Agent middleware for run binding, registry rules, and tenant isolation.

Advanced / manual wiring

When you need step-by-step control over registry and bind:

  1. Bind a PaybondAgentRun with a tool registry (sandbox bootstrap or production attach).
  2. Register side-effecting tools on the registry — tool names must match registry keys.
  3. Wrap tools with createPaybondCloudflareAgentsConfig(run, tools) before returning from getTools().
import { createPaybondCloudflareAgentsConfig } from "@paybond/cloudflare-agents";

const { tools: guardedTools, toolApproval } = createPaybondCloudflareAgentsConfig(run, agentTools);

Paybond wraps execute only on side-effecting registry tools. Schema, descriptions, and tool metadata pass through unchanged.

Known limitations (same as Vercel AI)

Cloudflare Agents reuse the Vercel AI SDK tool() / toolApproval boundary. Provider-executed tools (isProviderExecuted: true) bypass local spend verify unless you fail closed via policy or adapter options:

# paybond.policy.yaml
adapter:
  deny_provider_executed_tools: true
const { tools, toolApproval } = createPaybondCloudflareAgentsConfig(run, agentTools, {
  denyProviderExecutedTools: true,
});

Only locally executed registry tools are governed. See Vercel AI known limitations.

Scaffold and smoke

Clone the shopping checkout template for a full Cloudflare Agents and Paybond starter (policy, smoke script, Workers-oriented agent scaffold):

paybond init --template cloudflare-shopping-agent --force
cd paybond-cloudflare-shopping-agent
cp .env.example .env.local
paybond login
npm install
npm run smoke

The smoke command exercises authorize → execute → auto-evidence without a Cloudflare Workers runtime or LLM.

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

Scaffold:

npm install @paybond/cloudflare-agents agents ai
paybond init agent-middleware --framework cloudflare-agents --out paybond-cloudflare-agents.ts

Optional peers: agents >= 0.10.0 and ai >= 4.0.0 — required for the native adapter and smoke demo.

Cloudflare Workers / Durable Objects wiring

Cloudflare Agents run on Workers and expose tools through getTools() on your Agent class. Paybond guards the AI SDK tool() execute boundary — model inference and Agent lifecycle stay on Cloudflare:

  1. Bind a PaybondAgentRun per agent session (sandbox bootstrap locally; production attach with intent and capability).
  2. Register side-effecting tool names in paybond.policy.yaml.
  3. Return guarded tools from getTools() and pass toolApproval to streamText / generateText.

See src/agent.ts in the paybond-cloudflare-shopping-agent template for a Durable Object–ready scaffold. Deploy with wrangler deploy after adding your Worker entrypoint and secrets (PAYBOND_API_KEY, model provider keys).

Selection rule

Use Paybond for paid tools, delegated spend, receipts, and spend authorization. Use provider-native limits only for LLM token caps.