Quickstart

Use this guide to read the protocol in the order an implementation usually needs it. OSBP v0.1.0 is create-only: the agent can search, compare, and prepare freely, and it mutates only inside a user-approved BookingMandate. The full contract lives in the v0.1.0 specification.

1. Model the mandate

Start with the user’s approved bounds. The BookingMandate is the object the server validates before any action can change the platform’s booking state. In v0.1.0 it is unsigned JSON; the server still checks every field before a mutation.

{
  "id": "mnd_2026_05_01_001",
  "expires_at": "2026-05-01T23:59:59-07:00",
  "allowed_actions": ["booking.create"],
  "organization_id": "org_01jx2h9r8k6m4n3p2q1s0t9v8w",
  "service_ids": ["service_123"],
  "provider_ids": ["provider_123"],
  "schedule_ids": ["schedule_123"],
  "earliest_start": "2026-05-01T09:00:00",
  "latest_end": "2026-05-14T18:00:00",
  "max_price": { "amount_minor": 10000, "currency": "USD" },
  "allow_policy_fee": false,
  "max_extra_fee": { "amount_minor": 0, "currency": "USD" }
}

2. Know the eight tools

An OSBP adapter rides MCP for transport, but the booking semantics live in OSBP. v0.1.0 has exactly eight tools, and booking.create is the only mutation:

type OsbpTool =
  | 'service.describe'
  | 'availability.find'
  | 'policy.explain'
  | 'verification.send'
  | 'verification.verify'
  | 'booking.create'
  | 'booking.status'
  | 'handoff.request';

Holds, change, cancel, and reschedule are roadmap, not current surface.

3. Walk the flow

The happy path prepares with read tools, reads the policy back to the user, gets explicit approval, then creates:

1. The user approves a BookingMandate.
2. service.describe / availability.find / policy.explain gather the facts the agent needs to explain the booking. Each availability.find slot carries the create-ready organization_id, schedule_id, provider_id, and service_id.
3. The agent reads the policy impact back to the user and asks before booking.
4. The first booking.create omits approval; the adapter validates the mandate and slot and returns requires_user_confirmation with an exact summary and an opaque approval.token, without touching the platform.
5. After the user confirms that summary, the agent retries booking.create with the same idempotency_key and approval.
6. If the platform requires it, booking.create returns requires_verification. The agent calls verification.send, asks the user for the code out of band, and retries booking.create with the same idempotency_key, the same approval, and the raw verification_code. (verification.verify is for non-booking flows that need explicit pre-verification; for booking, supply the code to booking.create directly.)
7. booking.status reads the current appointment state from the create receipt’s booking_id.
8. handoff.request is the fallback when the adapter cannot safely complete: payment or deposit is required, the slot disappeared, the request exceeds mandate scope, or verification fails.

4. Validate before mutation

Canonical mandate policy comes from the protocol core (validateMandate in @osbp/core, consumed from the public monorepo workspace in v0.1.0), not the adapter. It must run before any platform create call. In the reference, the adapter performs it: createBooking fetches the service and policy, builds the Slot, and calls validateMandate before issuing any create.

Keep presentation separate from the wire. OSBP uses canonical values such as ISO 4217 minor units, IANA timezones, RFC 3339 instants, merchant-local wall clocks, E.164 phone numbers, and RFC email addresses; the agent or host localizes those values for the user. Branch on Problem.code, not the English Problem.message text.

import { validateMandate } from '@osbp/core';

const result = validateMandate(mandate, { slot, service, policy });
if (!result.ok) {
  // Return the Problem (for example price_exceeds_mandate or slot_too_late);
  // do not call the platform create endpoint.
  return result;
}

5. Return a receipt

The platform remains the system of record. A successful booking.create returns the receipt id, the platform booking_id, a human-readable summary, and an audit_event_id so the agent can explain what happened. Every tool call appends a redacted audit event locally.

Next, read the specification overview. To run OSBP without accounts or secrets, use the repository’s reference backend demo and conformance checks. To see how the real-platform companion is shaped, walk through the Openings example.