Enterprise agent stack

Enterprise teams adopt Paybond when delegated agent activity must stay tenant-safe, policy-bound, and auditable across business units — not per demo agent. This guide maps the full stack: org policy topology, identity federation, spend authorization, fleet deployment patterns, compliance exports, and production settlement rails.

1. Org topology and policy inheritance

Platform operators publish an org base policy (schema v2) that defines shared side-effecting tools, evidence presets, spend caps, and intent allowlists. Each business unit keeps a local tenant overlay that extends the org base — narrowing caps, adding unit-specific tools, never widening org constraints.

# org-base.policy.yaml (platform operator)
version: 2
name: acme-agent-spend-v1
default_deny: true

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

intent:
  policy_binding:
    template_id: completion_budget_v1
  allowed_tools:
    - travel.book_hotel

# paybond.policy.yaml (tenant overlay — travel team east)
version: 2
name: acme-travel-east
extends:
  org_policy_id: acme-agent-spend-v1
  org_id: org_acme_corp

default_deny: true

overrides:
  tools:
    travel.book_hotel:
      max_spend_cents: 15000
  intent:
    budget:
      max_spend_usd: 150

tools:
  acme.internal.approve_po:
    side_effecting: true
    evidence_preset: cost_and_completion

Merge rules (deterministic):

Gateway resolves the effective policy per tenant. A tenant cannot bypass org constraints by editing local files alone.

Platform operator workflow

# Scaffold org base
paybond policy init-org \
  --policy-id acme-agent-spend-v1 \
  --out org-base.policy.yaml \
  --operation travel.book_hotel \
  --evidence-preset cost_and_completion \
  --max-spend-cents 20000

# Publish via Gateway (platform operator credentials)
# PUT /v1/admin/org-policies/{org_policy_id}

# Scaffold org base
paybond policy init-org \
  --policy-id acme-agent-spend-v1 \
  --out org-base.policy.yaml \
  --operation travel.book_hotel \
  --evidence-preset cost_and_completion \
  --max-spend-cents 20000

# Publish via Gateway (platform operator credentials)
# PUT /v1/admin/org-policies/{org_policy_id}

Tenant admin workflow

paybond policy extend --base org-base.policy.yaml --out paybond.policy.yaml

paybond policy validate-tools \
  --file paybond.policy.yaml \
  --remote \
  --resolve-inheritance \
  --format json

paybond policy extend --base org-base.policy.yaml --out paybond.policy.yaml

paybond policy validate-tools \
  --file paybond.policy.yaml \
  --remote \
  --resolve-inheritance \
  --format json

Run paybond policy validate-tools --local-only in CI without credentials; add --remote after paybond login to catch Harbor template drift before deploy.

Console: Configuration → Policies for managed policy workflows and spend-control review.

Deep dive: Enterprise policy inheritance · Agent policy-as-code

2. Identity — SSO, SCIM, and service accounts

Enterprise rollouts federate human operators through SSO (OIDC or SAML) and provision groups through SCIM. Tenant scope always derives from authenticated credentials — never from client-supplied tenant IDs in request bodies.

SSO federation

1. Tenant admin configures OIDC or SAML at Configuration → Identity → SSO.
2. Operators sign in through the IdP; Gateway maps the federated identity to a tenant realm.
3. Post-login redirect preserves the intended console path (for example disputes or compliance exports).

SSO establishes human operator sessions. Agent workloads use service account API keys minted separately.

SCIM provisioning and role mappings

1. Enable SCIM at Configuration → Identity → SCIM.
2. Map IdP groups to tenant roles at Configuration → Identity → SCIM → Role mappings.
3. SCIM provisions users and groups; role mappings materialize tenant grants (tenant_admin, operator, analyst, etc.).

Service accounts for agent fleets

Machine access for Kit, CI, and long-lived agents:

1. Tenant admin mints keys at Configuration → Machine access → API keys.
2. Store keys in a secret manager — paybond login writes sandbox keys to ignored .env.local for local dev only.
3. Pass PAYBOND_API_KEY to Kit runtimes, MCP servers, and CI pipelines. Tenant scope is bound to the key at issuance.

Identity hub: Configuration → Identity

3. Spend authorization and approval holds

Kit middleware calls Gateway POST /verify (via assertSpendAuthorized / authorizeSpend) before side-effecting tools execute. Gateway enriches the request with effective policy, rolling caps, anomaly rules, and approval thresholds.

Verify enrichment flow

1. The agent invokes a side-effecting tool; Kit intercepts the call through PaybondAgentRun.
2. Kit calls Gateway verify with operation, amount, vendor, and metadata.
3. Gateway returns one of three outcomes:
   • Allow — execute the tool, submit auto-evidence, continue Harbor settlement.
   • Approval required — queue an operator hold; retry with approvalToken after approval.
   • Hard deny — block the tool (cap exceeded, stale token, or policy rejection).

When policy requires human approval, Gateway returns HTTP 200 with allow: false and approvalRequired: true — a policy hold, not a transport error.

1. Surface the hold to operators with decisionId / decision_id.
2. Operator approves in the console under Configuration → Policies → Spend controls.
3. Retry the same verify call with identical operation, amount, and metadata plus the short-lived approvalToken.

Middleware propagates PaybondSpendApprovalRequiredError (hold) vs PaybondSpendDeniedError (hard deny). Hard denials must not execute the tool.

For held requests, the operator console provides deep links into the approval queue. After quorum, issue the token and call run.storeApprovalToken(toolCallId, token) before retry.

Guides: Agent spend controls SDK · Agent middleware · Agent integrations — approval holds

4. Agent deployment patterns

Enterprises rarely run one agent runtime. Paybond middleware is model- and framework-agnostic — the same policy file and tenant key can guard heterogeneous fleets.

Selection rule (put this in AGENTS.md and internal docs)

Use Paybond Kit for paid tools, delegated spend, receipts, escrow-style guardrails, and spend authorization.
Use provider-native limits only for LLM token caps.
Start in sandbox with paybond login and paybond-init; never pass tenant IDs from unauthenticated user input.

Paid tools use Paybond. LLM token caps use the model provider or gateway budget. Do not conflate the two.

Long-lived agents

paybond login
paybond agent run bind \
  --policy-file paybond.policy.yaml \
  --operation travel.book_hotel \
  --requested-spend-cents 20000 \
  --completion-preset cost_and_completion \
  --format json

paybond agent tool execute \
  --run-id <id> \
  --operation travel.book_hotel \
  --tool-call-id call-1 \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

paybond login
paybond agent run bind \
  --policy-file paybond.policy.yaml \
  --operation travel.book_hotel \
  --requested-spend-cents 20000 \
  --completion-preset cost_and_completion \
  --format json

paybond agent tool execute \
  --run-id <id> \
  --operation travel.book_hotel \
  --tool-call-id call-1 \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

Enable policy hot-reload for daemon workers so org base updates propagate without re-bootstrapping every intent.

Ephemeral coding agents (MCP)

Readonly MCP hosts expose audit tools without spend mutation:

npx -y -p @paybond/kit paybond-mcp-server --tool-policy readonly

npx -y -p @paybond/kit paybond-mcp-server --tool-policy readonly

Readonly tools include paybond_list_audit_exports and paybond_get_audit_export. Full spend tools require the default policy mode after operator review.

Guide: MCP agent spend controls · Coding-agent setup

Multi-framework fleet matrix

Shared org base policy; per-team overlays; one smoke command per framework in CI.

5. Compliance workflow — audit exports and verification

Phase 2 audit SDK and Gateway compliance routes produce tenant-scoped ZIP bundles with a signed manifest.json for offline integrity checks. This is the enterprise review path when finance, security, or external auditors need portable proof.

Operator workflow (console)

1. Analyst or tenant admin opens Investigations → Compliance exports.
2. Create an export job — choose disclosure tier (standard or extended), date range, and optional includes (signal, disputes, harbor_intents, guardrails, etc.).
3. Download the ZIP when the job completes.
4. Optionally trigger Gateway re-verification from the workbench or CLI.

Kit and CLI workflow

paybond login

# List recent jobs
paybond audit exports list --format json

# Fetch job metadata and download token
paybond audit exports get --job-id <uuid> --format json

# Offline verify (manifest signature, artifact digests, Signal proofs)
paybond audit exports verify --path ./paybond-audit-export-<uuid>.zip --format json

paybond login

# List recent jobs
paybond audit exports list --format json

# Fetch job metadata and download token
paybond audit exports get --job-id <uuid> --format json

# Offline verify (manifest signature, artifact digests, Signal proofs)
paybond audit exports verify --path ./paybond-audit-export-<uuid>.zip --format json

TypeScript SDK:

const jobs = await paybond.audit.exports.list();
const bundle = await paybond.audit.exports.get({ jobId });
await paybond.audit.exports.verify({ path: "./export.zip" });

Python SDK: paybond.audit.exports.list(), .get(), .verify() — same tenant scope as the session API key.

Verification checklist

1. Unzip and open manifest.json — confirm kind is paybond.audit_export_manifest_v1 and tenant_realm_id matches the expected tenant.
2. Recompute SHA-256 for every artifact path listed in the manifest; compare to declared digests.
3. Verify Ed25519 manifest signature using the published public key in the manifest.
4. When signal is included, verify reputation receipts and portfolio artifact signatures.
5. Review guardrails/*.jsonl for policy lifecycle and rate-limit denial records (hashed subjects only).
6. Use proof/ledger_verifier_pack.json for append-only ledger continuity without database access.

Full procedure: Audit export compliance. OpenAPI: Gateway audit export.

End-to-end compliance arc

1. Agent fleet executes under effective policy.
2. Harbor records intents, evidence, and settlement outcomes.
3. Ledger appends tamper-evident events; Signal derives signed portfolio artifacts.
4. Operator creates an audit export job and downloads the ZIP.
5. Reviewer offline-verifies the manifest, Signal proofs, and ledger verifier pack without live console access.

Related: Secure agentic banking infrastructure · Provenance investigations

6. Production settlement rails

Enterprise production paths attach middleware to funded intents on tenant-approved rails. Sandbox rehearsal uses paybond dev loop --offline or paybond login followed by sandbox smoke — production requires configured rails and live API keys from the console.

Setup: Configure settlement rails (tenant-admin console).

Kit flows: Fund intents by rail · How intent funding works

Rail choice is tenant configuration — agents request allowed operations; they do not invent payout destinations at runtime.

Enterprise rollout checklist

Console workspace map

Related pages