AgentDraft▸agentdraft.io
Get API key
§ Protocol · v0.1

The AgentDraft protocol.

The wire spec for AI scheduling agents to coordinate against a shared source of truth. If an agent wants to book on a human's calendar without colliding with sibling agents — Cal.com handlers, OpenAI assistants, internal sales bots — this is the protocol it speaks.

This page is the readable summary. The endpoint reference — every path, payload, error code — lives in the Protocol docs.

Updated

§ 01

Goals

  • One source of truth. Every agent on a calendar queries the same coordination layer before booking.
  • Deterministic conflict resolution. Two agents racing for the same slot produce a single, predictable winner — no retries, no drift, no human in the loop.
  • Append-only audit. Every hold, commit, eviction, rule change is recorded. Application IAM has PutItem only.
  • Switching cost as moat. Once N agents speak the protocol, swapping the implementation is reconfiguring one endpoint per agent.
§ 02

Three primitives

01

Availability

Ask what's open — never the calendar directly. The response is filtered through buffer rules, focus blocks, and active holds from sibling agents.

GET /v1/availability
  ?user_id=usr_…
  &range_start=…
  &range_end=…
  &duration_minutes=30
02

Commit

Bookings commit through a single conditional write. When two agents collide, the priority engine resolves deterministically. No retries. No drift.

POST /v1/bookings
  agent: agt_sales       priority: 1
  slot:  16:00–16:30
  → 201 COMMITTED
POST /v1/bookings
  agent: agt_recruit     priority: 3
  slot:  16:00–16:30
  → 409 OUTRANKED
       winning_agent_id: agt_sales
03

Audit

Every hold, commit, eviction and rule change is written immutably. Enterprise governance review is a curl away.

GET /v1/audit
  ?resource=bkg_3f9
  → 7 events, signed
§ 03

Resolution semantics

  1. Each user ranks their own agents by trust. Priority 1 is highest.
  2. A higher-priority commit overwrites a lower-priority commit only inside its bump window (default 30s).
  3. Past the bump window, a commit is frozen. Even priority 1 can't evict it.
  4. Holds are softer — any same-or-higher-priority commit displaces them inside their 30s TTL.
  5. The losing agent receives 409 with the winner's identity so its retry / fallback is one except Conflict away.
§ 04

Webhook envelope

Outbound webhooks are Stripe-shaped: X-AgentDraft-Signature: t=<unix>,v1=<hmac-sha256(body, secret)>. Delivery is at-least-once with idempotency via data.id. The dispatcher persists every row to DynamoDB before the network call so a process restart between persist and deliver does not drop the event.

Currently emitted event types:

  • booking.committed
  • booking.evicted (priority-bump or external-event cleanup)
  • hold.invalidated
  • booking.cancelled
§ 05

Status

This page describes the AgentDraft Protocol v0.1. Stable for the v0.x release series. RFC-style comments, integration questions, and proposed additions go to hello@agentdraft.io.

§ 06

Frequently asked

Is the wire format stable?

Stable for the v0.x release series. Breaking changes are gated by a major version bump and announced on the changelog at least one release ahead. Additive fields (new optional inputs, new response keys) ship under the existing v0.x umbrella.

Where does the implementation live?

The reference implementation is the AgentDraft API itself — FastAPI in front of DynamoDB, with the conflict engine in app/conflict/engine.py. The wire spec on this page is the contract; the implementation is one of several possible conformant servers.

Protocol docs Get an API key