paybondpaybond
Sign in

Agent runtime tutorial

Build a Paybond-backed agent workflow in Python or TypeScript using a reusable runtime pattern.

Agent runtime tutorial

This tutorial track documents the Paybond pattern for agent runtimes. The examples use OpenAI Agents where that provides a concrete reference implementation, but the same settlement pattern applies to Claude, Google, local models, and application-owned runtimes.

The agent can still plan and execute flexibly, but the money-moving boundary remains explicit, verified, and replayable.

What the pattern does

  • Derives tenant scope from authenticated credentials.
  • Verifies the capability before a tool executes.
  • Submits signed evidence against the same intent lifecycle.
  • Leaves the release or refund decision to Harbor's deterministic settlement rules.

Shared lifecycle

Both language paths use the same flow:

  1. Open a tenant-bound Paybond session from POST /v1/auth/harbor-access.
  2. Create an intent whose allowed_tools / allowedTools exactly match your tool name.
  3. Read the capability_token returned when the intent reaches funded.
  4. Bind (harbor, intent_id, capability_token) to the run.
  5. Verify the capability before the tool executes.
  6. Run the tool work.
  7. Submit signed evidence and inspect Harbor's predicate result.

The examples in this track support both immediate funding and the x402_usdc_base path. If create does not return a capability token immediately, the example continues through the funding handshake before the tool runs.

Choose a language

Python

Use the first-party Python guardrail example.

TypeScript

Use @paybond/kit plus a thin application-owned wrapper around the tool handler.

Before you start

  • A paybond_sk_... service-account API key for one tenant realm
  • Reachable Gateway and Harbor base URLs
  • A principal DID and 32-byte signing seed
  • A payee DID and 32-byte signing seed
  • A Paybond environment that can fund the example intent
  • For x402_usdc_base, an x402 signer or facilitator that can answer the funding challenge

Supporting docs