paybondpaybond
Sign in

Agent quickstart

Add Paybond to an agent in under five minutes — sandbox login, optional `paybond init` scaffold, CLI smoke, then paybond.agent() in TypeScript or Python.

Get a guarded agent tool working in sandbox in under five minutes. You can smoke-test with zero app code, or run paybond init first to scaffold owned policy and integration files in your repo.

Prerequisites: Node.js 22+ or Python 3.11+. Network access to the Paybond sandbox Gateway is required for real sandbox smoke; use paybond dev loop --offline when you want a fully local path with no API key.

The fastest way to see authorize → execute → evidence end-to-end is paybond dev loop. It scaffolds the travel policy preset, validates tools locally, runs smoke, and prints trace and audit log paths.

No API key (offline mock):

paybond dev loop --offline

Real sandbox (login when needed):

paybond dev loop

Visual trace

After smoke, open the local trace dashboard (same project directory):

paybond dev trace

The UI renders a vertical timeline at http://127.0.0.1:9477 using events from .paybond/dev-trace.jsonl. Hosted replay: /demo/agent-trace.

For the full architecture — event model, phase colors, HTTP API, deep links, CLI trace, and traceSink — see Middleware trace.

For HTTP-level sandbox against a local WireMock Gateway (Docker required), run paybond dev up and pass --gateway to subsequent smoke commands. See CLI contract for all dev subcommands.

Step 1 — Log in

paybond login

TypeScript without a global install:

npx -p @paybond/kit paybond login

Python entrypoint alias:

paybond-kit-login

The command writes PAYBOND_API_KEY to .env.local (mode 0600) and adds the file to .gitignore when needed. Tenant scope comes from the credential — never pass tenant IDs from user input.

Step 2 — Scaffold or clone a starter template

Option A — scaffold from bundled assets (copies from @paybond/kit/templates/):

paybond init --template travel-agent --framework langgraph
paybond login
npm install
npm run smoke

Option B — clone a public GitHub template (full catalog):

git clone https://github.com/nonameuserd/paybond-travel-agent.git
cd paybond-travel-agent
cp .env.example .env.local
paybond login
npm install
npm run smoke

Each template ships paybond.policy.yaml (from a Plan 5 preset), .env.example, npm run smoke using --policy-file paybond.policy.yaml, and GitHub Actions CI (PAYBOND_SANDBOX_API_KEY secret).

Browse templates on /kit/agent-middleware#starter-templates.

Step 2b — Wizard scaffold (custom integration files)

Run the interactive wizard to create owned starter files without a framework template: paybond.policy.yaml, client bootstrap (paybond.config.ts or paybond.config.py), framework instrument stub (paybond.instrument.ts or paybond.instrument.py), .env.example, and an npm run smoke script (TypeScript projects).

paybond init

The wizard asks for solution (Shopping, Travel, SaaS, MCP server, AWS operator), maximum spend, and framework (OpenAI Agents, LangGraph, MCP, Generic). Non-interactive CI or templates:

paybond init \
  --solution travel \
  --max-spend-usd 500 \
  --framework langgraph \
  --non-interactive

Presets are reference implementations — edit the generated YAML freely. See Agent policy for paybond policy init when you only need the policy file.

Step 3 — Smoke test (CLI)

If you already ran paybond dev loop above, you can skip to Step 4 — the loop includes smoke with travel preset defaults.

Otherwise, run one end-to-end sandbox lifecycle manually: bind a run from the bundled travel policy preset, authorize spend, execute a tool, and submit auto-evidence.

paybond dev smoke --preset travel

Or the lower-level command (same lifecycle, explicit result body):

paybond agent sandbox smoke \
  --preset travel \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

A successful response includes bind (run id, intent id, travel.book_hotel operation) and execute with evidence.submitted: true. This step is language-agnostic — no application code required.

If you ran Step 2, use the generated smoke script:

npm run smoke

Policy file only (without the full wizard): scaffold travel defaults to a local YAML file you can edit and validate in CI:

paybond policy init --preset travel --out paybond.policy.yaml
paybond policy validate-tools --file paybond.policy.yaml --local-only

See Agent policy for policy presets list|show, --max-spend, and domain + guardrails composition.

Step 4 — Guard tools in your app

Install the Kit, load the sandbox key from .env.local, and call paybond.agent() with the same travel preset. Paybond binds a sandbox run, wraps your side-effecting tools, and submits evidence after each successful call.

If you ran paybond init, open paybond.instrument.ts (or .py) and wire createInstrumentedAgent() into your runtime instead of the inline example below.

TypeScript

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

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

const { tools } = await paybond.agent({
  policy: "travel",
  tools: {
    "travel.book_hotel": async () => ({ status: "completed", cost_cents: 18_700 }),
  },
});

const bookHotel = (tools as Array<{ execute: (call: object) => Promise<unknown> }>)[0]!;
await bookHotel.execute({
  toolName: "travel.book_hotel",
  toolCallId: "call-1",
  arguments: { city: "Paris" },
});

await paybond.aclose();

Python

pip install paybond-kit
import asyncio
import os

from paybond_kit import Paybond


async def main() -> None:
    paybond = await Paybond.open(
        api_key=os.environ["PAYBOND_API_KEY"],
        expected_environment="sandbox",
    )
    agent = await paybond.agent(
        policy="travel",
        tools={
            "travel.book_hotel": lambda _args: {"status": "completed", "cost_cents": 18_700},
        },
    )
    book_hotel = next(t for t in agent.tools if t["name"] == "travel.book_hotel")
    await book_hotel["execute"](
        {
            "tool_name": "travel.book_hotel",
            "tool_call_id": "call-1",
            "arguments": {"city": "Paris"},
        }
    )
    await paybond.aclose()


asyncio.run(main())

Register the returned tools with your agent runtime (OpenAI, LangGraph, Claude, MCP, or a custom orchestrator). For framework-specific wiring, pass framework: "langgraph" (or "claude-agents", "vercel-ai", "openai-agents") to paybond.agent().

What you just did

  1. (Optional) Ran paybond dev loop for a guided local smoke + trace path, or authenticated a tenant-bound sandbox session with paybond login.
  2. (Optional) Scaffolded owned policy and integration files with paybond init.
  3. Bound a run with the travel vertical preset (travel.book_hotel, spend cap, cost_and_completion evidence).
  4. Guarded a paid tool call — Harbor authorized spend, your handler ran, Paybond submitted evidence.

Production flows use paybond.instrument() with bind() or a lazy context provider — see Agent middleware. paybond.agent() is the sandbox quickstart only.

Next steps