Agents SDK tutorial

This tutorial track shows how to add Paybond to an OpenAI Agents workflow without weakening the core invariants:

• tenant scope is derived from authenticated credentials
• capability checks run before a tool executes
• evidence is signed and attached to the same intent lifecycle
• Harbor decides the settlement outcome from deterministic inputs

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 assume your Harbor environment funds the intent during creation and returns capability_token in the create response. If your settlement rail funds asynchronously, wait until the intent is funded before starting the agent run.

Choose a language

Python

Use Paybond's first-party OpenAI Agents guardrail.

• Tutorial: Agents SDK tutorial (Python)
• Example: examples/paybond-kit-openai-agents-python
• Key surface: paybond_kit.agents_sdk.paybond_capability_input_guardrail()

TypeScript

Use the existing @paybond/kit client plus a thin app-side wrapper around your OpenAI tool handler.

• Tutorial: Agents SDK tutorial (TypeScript)
• Example: examples/paybond-kit-openai-agents-typescript
• Key surface: PaybondCapabilityBinding + harbor.verifyCapability(...)

Shared prerequisites

• 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 Harbor environment that can fund the example intent

Supporting docs

• TypeScript quickstart
• Python quickstart
• Authentication & tenant binding
• Capabilities
• Harbor API reference