agentdraft

agentdraft — Python SDK

AgentDraft is the coordination layer for AI scheduling agents. When two or more agents — your sales bot, a Cal.com handler, an internal recruiter, a Claude/OpenAI assistant — write to the same calendar, AgentDraft is the one API that decides who wins, atomically, with a tamper-evident audit row for every commit.

This is the official Python SDK. It gives an agent a typed, one-line surface to participate.

• Protocol spec: https://agentdraft.io/spec
• Why it exists: https://agentdraft.io/why
• Live API reference: https://agentdraft.io/docs

Install

pip install agentdraft

Requires Python 3.9+.

Upgrade

pip install -U agentdraft

Release notes: https://agentdraft.io/changelog

Quickstart

from datetime import datetime, timedelta, timezone
from agentdraft import Client, Conflict

client = Client(api_key="avs_live_...")   # or set AGENTDRAFT_API_KEY

start = datetime.now(timezone.utc) + timedelta(hours=4)
end   = start + timedelta(minutes=30)

try:
    booking = client.bookings.commit(
        start=start, end=end,
        idempotency_key="ik_call_42",
        title="Discovery call",
        invitee={"name": "Ada Lovelace", "email": "ada@example.com"},
    )
    print("booked:", booking.booking_id)
except Conflict as e:
    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")

title and invitee ({name, email, notes}, all optional) are first-class fields: they're persisted on the booking, echoed back on the returned Booking, and shown to the calendar owner in the dashboard. A top-level title supersedes the legacy metadata={"title": ...}. client.agents.me() also returns the owner's timezone so a client can render slots in their zone.

A losing agent gets a typed Conflict exception, not a timeout — it knows who won, by what priority, and where the audit row lives, so fallback behavior (propose an alternate, escalate, defer) is a clean except clause away.

Why a separate API?

Coordinator frameworks (LangChain, LangGraph, CrewAI, AutoGen, Composio, the OpenAI Agents SDK) coordinate work between agents — sequential, parallel, or graph orchestration of LLM calls and tools. None of them solve write contention on the calendar itself: two agents firing POST /events against Google Calendar at the same moment will both succeed, and you have a double-booking.

AgentDraft solves only that problem, and solves it once. Every agent the calendar owner runs calls bookings.commit(...) against AgentDraft before touching the real calendar. The conflict engine uses time-bucketed conditional writes in DynamoDB inside a single TransactWriteItems — atomic, race-free, no locks. The user ranks their agents in the dashboard; ties go to the higher-rank agent; recent commits can be evicted by higher-priority agents inside a configurable bump window.

See the race

The repo ships a multi-agent race demo. With the local stack up:

git clone https://github.com/ryabinski-labs/agentdraft && cd agentdraft
docker compose up -d dynamodb
pip install -e ".[dev]" -e sdks/python
uvicorn app.main:app --port 8080 &
python scripts/demo_race.py            # 5 agents, ranked priorities, one slot

Five agents fire concurrently at the same target slot. The highest-rank agent wins; the rest get 409 outranked with the winner's identity for graceful fallback. The demo prints per-agent latency, the winning booking id, and a link to the audit trail of the whole race.

Authentication

API keys are issued from the AgentDraft dashboard and start with avs_live_. Pass it explicitly or let the client read it from the environment:

Client(api_key="avs_live_...")
# or
import os; os.environ["AGENTDRAFT_API_KEY"] = "avs_live_..."
Client()

For local development against a dev backend, point at it via AGENTDRAFT_BASE_URL or the base_url= kwarg.

Surface

All blocking I/O. An async client is on the roadmap; for now wrap with asyncio.to_thread if you need concurrency.

Error types

Every failure is a typed exception so callers can branch precisely:

• Conflict — your write was outranked. Carries winning_booking_id, winning_agent_id, winning_agent_priority, your_priority, and reason. The winning booking's audit_event_id is available on the returned Booking model for the agent that did win.
• AuthError — bad / missing / expired API key.
• RateLimited — token bucket exhausted. Has retry_after (seconds).
• RuleViolation — request was syntactically valid but violated a rule (focus block, daily cap, business hours).
• AgentDraftError — base class; catch this if you only need a catch-all.

Idempotency

Pass idempotency_key= to bookings.commit(...). The server caches the result by (agent_id, key) for 24 hours, so a retry over a flaky network returns the original booking, not a duplicate.

Use with LangChain / CrewAI / AutoGen

The SDK is framework-agnostic — wrap any method in a Tool and pass it to your agent. A first-party agentdraft-langchain package with ready BookingTool / AvailabilityTool / ConflictAwareBookingTool wrappers is on the roadmap.

Links

• Protocol spec: https://agentdraft.io/spec
• API docs: https://agentdraft.io/docs
• Changelog: https://agentdraft.io/changelog
• Source & issues: https://github.com/ryabinski-labs/agentdraft
• TypeScript SDK: agentdraft

Security

Found a vulnerability? See https://agentdraft.io/security — do not open a public issue for a security report.

License

MIT — see https://agentdraft.io/legal/license.