paybondpaybond
Sign in

Agent policy-as-code

Versioned paybond.policy.yaml files that drive tool registries, intent alignment, and sandbox bootstrap for agent middleware.

paybond.policy.yaml is the portable policy layer for agent middleware. One file defines side-effecting tools, spend rules, evidence presets, and intent alignment — then drives registry construction, sandbox bootstrap, and production intent create.

Use policy files when you want GitOps-friendly, reviewable spend authorization that stays aligned with Harbor managed templates and completion presets.

When to use policy vs registry-only

ApproachBest for
paybond.policy.yamlMulti-tool agents, production intent binding, CI validation before deploy
Registry YAML only (paybond.agent.registry.yaml)Sandbox-only smoke tests, minimal tool lists without intent metadata
Inline registry in codeQuick prototypes and single-file examples

Prefer policy files when default_deny: true must catch tool/intent misalignment in CI before production.

Policy file format (v1)

version: 1
name: travel-agent-v1
default_deny: true

tools:
  travel.book_hotel:
    side_effecting: true
    max_spend_cents: 20000
    evidence_preset: cost_and_completion

  search.web:
    side_effecting: false

intent:
  policy_binding:
    template_id: completion_budget_v1
  budget:
    currency: usd
    max_spend_usd: 200
  allowed_tools:
    - travel.book_hotel

Design rules:

  • default_deny: true — tools in intent allowed_tools that are missing from the registry fail closed at intercept time.
  • Side-effecting tools require evidence_preset — references a catalog preset ID (validated at load time).
  • intent.allowed_tools — must align with registered side-effecting tools; omit read-only tools intentionally when they should not authorize spend.
  • max_spend_cents — optional fixed per-tool spend cap (used for sandbox bootstrap defaults and static spend resolution).
  • spend_from_args — optional dot path into tool arguments for dynamic spend at intercept time; mutually exclusive with max_spend_cents.
  • policy_binding.template_id — Harbor managed template stub for createWithPolicyBinding in production.

Use paybond policy init to scaffold a starter file, or run paybond init for the full first-run wizard (policy + config + instrument stub + .env.example). For run binding and interceptors, see Agent middleware.

Bundled vertical presets

Paybond ships reference policy presets for common agent verticals: travel, shopping, saas, aws, plus universal read-only and strict. In middleware you can use them without a local file:

await paybond.agent({ policy: "travel", tools });
// equivalent: paybond.usePolicy("travel").instrument(tools)

Presets are starting points, not contracts. Bundled YAML is a composed default (domain tools + guardrails). For GitOps and review, scaffold an owned local file and edit freely:

paybond policy init --preset travel --out paybond.policy.yaml

paybond policy presets list shows domains, guardrails, flat/composed presets, and solution bundles. paybond policy presets show travel previews the composed YAML before you write a file.

Do not confuse vertical policy presets with completion presets (paybond policy templates) — those catalog evidence archetypes for Harbor release predicates.

Core API

TypeScript (@paybond/kit/policy):

import { PaybondPolicy } from "@paybond/kit/policy";

const policy = await PaybondPolicy.load("./paybond.policy.yaml");
const registry = policy.toToolRegistry();

const run = await paybond.agentRun.bind({
  bootstrap: policy.sandboxBootstrap({ operation: "travel.book_hotel" }),
  registry,
});

// Production intent create: policy.toIntentCreateInput(...) + createWithPolicyBinding
// See Production attach for signing credentials.

Python parity:

from paybond_kit.policy import PaybondPolicy

policy = PaybondPolicy.load("./paybond.policy.yaml")
registry = policy.to_tool_registry()
bootstrap = policy.sandbox_bootstrap(operation="travel.book_hotel")

Factory helper

For framework adapters, use createGuardedAgent to load policy, bind a sandbox run, and wrap tools in one call:

import { createGuardedAgent } from "@paybond/kit/agent";

const { run, tools } = await createGuardedAgent(paybond, {
  policy: "./paybond.policy.yaml",
  framework: "generic",
  tools: { "travel.book_hotel": bookHotel, "search.web": searchWeb },
});

Customize bundled presets in code

For sandbox and tutorials, policy: "travel" is enough. To tighten caps without maintaining a YAML file:

const policy = paybond.policyPresets.travel({ maxSpendUsd: 500 });
await paybond.instrument({ policy, tools });

Advanced composition stacks a domain layer with guardrail layers (paybond.policyPresets.compose, paybond.policyPresets.domain, paybond.policyPresets.guardrails). Same-tenant layering only — not org inheritance.

CLI workflow

Browse and preview presets

paybond policy presets list
paybond policy presets show travel
paybond policy presets show --preset travel --max-spend 500
paybond policy presets show --domain travel --guardrails read-only,max-spend:500

Table output for presets show prints the composed YAML preview. Use --format json for automation.

Scaffold

Interactive project wizard (recommended after paybond login):

paybond init

Non-interactive (CI, templates):

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

Creates paybond.policy.yaml, paybond.config.ts or paybond.config.py, paybond.instrument.ts or paybond.instrument.py, .env.example, and npm run smoke (TypeScript). See Agent quickstart.

From a bundled vertical preset (policy file only):

paybond policy init --preset travel --out paybond.policy.yaml
paybond policy init --preset travel --max-spend 500 --out paybond.policy.yaml

Compose domain + guardrails (no flat preset id):

paybond policy init \
  --domain travel \
  --guardrails read-only,max-spend:500 \
  --out paybond.policy.yaml

Guardrail tokens include default-deny, read-only, strict, and parameterized max-spend:<usd> / max-spend-cents:<n>.

Single-operation starter (minimal one-tool template):

paybond policy init \
  --out paybond.policy.yaml \
  --operation travel.book_hotel \
  --evidence-preset cost_and_completion

Scaffolded preset files include a header comment with the regenerate command. Pass --force to overwrite an existing path.

Enterprise org inheritance (org base + tenant overlay) uses paybond policy init-org and paybond policy extend. See Enterprise policy inheritance.

Validate before deploy

# Offline (no credentials)
paybond policy validate-tools --file paybond.policy.yaml --local-only --format json

# Server-authoritative (recommended after paybond login)
paybond policy validate-tools --file paybond.policy.yaml --remote --format json

# Tenant overlay with org inheritance (requires login)
paybond policy validate-tools --file paybond.policy.yaml --remote --resolve-inheritance --format json

Local checks cover schema version, evidence presets, and registry/intent alignment. With credentials configured, validation defaults to Gateway POST /v1/policy/validate unless you pass --local-only. See Agent policy validate for the full remote report shape.

Strict mode (PAYBOND_POLICY_STRICT=1 or --strict) requires every side-effecting tool to appear in intent.allowed_tools.

Sandbox bind and smoke from policy

Policy replaces separate --registry-file, --operation, and --evidence-preset flags for common paths:

paybond agent run bind --policy-file paybond.policy.yaml --format json

paybond agent sandbox smoke \
  --policy-file paybond.policy.yaml \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

Optional overrides: --operation, --requested-spend-cents, and --completion-preset / --evidence-preset still apply when you need a one-off variant.

You can also smoke-test a bundled preset without a local file:

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

See Agent quickstart for the full login → paybond init → smoke → paybond.agent({ policy: "travel" }) path.

Production attach from an existing intent

After funding a production intent, attach middleware to the run. See Going to production (not required for sandbox smoke).

GitOps / CI

Recommended pipeline:

  1. Commit paybond.policy.yaml alongside agent code.
  2. Run paybond policy validate-tools --file paybond.policy.yaml --local-only in CI (no credentials required).
  3. When sandbox credentials are available, add --remote to catch Harbor template head drift.
  4. Use policy.toIntentCreateInput() in production so authorization cannot drift from the reviewed policy file.

Relationship to middleware and Harbor

paybond.policy.yaml
  → PaybondPolicy.load()
  → PaybondToolRegistry          (middleware interceptors)
  → IntentPolicySpec             (createWithPolicyBinding)
  → PolicyValidator              (CI / pre-deploy)

Policy is the configuration layer middleware consumes — not framework middleware itself. Server-side validation is available via POST /v1/policy/validate and paybond policy validate-tools --remote. See Agent policy validate.