agentdraft 0.1.0

Python SDK for AgentDraft — the scheduling source of truth for AI agents

agentdraft — Python SDK

The official Python SDK for AgentDraft — the scheduling source of truth for AI agents.

AgentDraft is the coordination layer that prevents AI scheduling agents from colliding on the same calendar. Every agent calls one API before booking; every commit goes through one deterministic engine; every action is recorded in one tamper-evident audit log.

This SDK gives Python agents a typed, one-line surface to participate.

Install

pip install agentdraft

Requires Python 3.9+.

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",
        metadata={"title": "Discovery call"},
    )
    print("booked:", booking.booking_id)
except Conflict as e:
    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")

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.

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

Attribute	Purpose
client.availability	Read merged availability across all agents writing to the calendar
client.bookings	hold, release, commit, cancel — the four state transitions
client.agents	me() — confirm key + current priority + scopes
client.mailbox	Inbound/outbound mail surface for agents that book via email

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_agent_id, winning_agent_priority, winning_booking_id, audit_event_id.
• 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.

Links

• Protocol spec: https://agentdraft.io/spec
• API docs: https://agentdraft.io/docs
• Changelog: CHANGELOG.md
• Issues / source: https://github.com/GipsyChef/agentdraft
• TypeScript SDK: @agentdraft/sdk

Security

Found a vulnerability? Please follow SECURITY.md — do not open a public issue for a security report.

Contributing

See CONTRIBUTING.md. This SDK lives inside the GipsyChef/agentdraft monorepo under sdks/python/.

License

MIT — see LICENSE.