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
| 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. Carrieswinning_booking_id,winning_agent_id,winning_agent_priority,your_priority, andreason. The winning booking'saudit_event_idis available on the returnedBookingmodel for the agent that did win.AuthError— bad / missing / expired API key.RateLimited— token bucket exhausted. Hasretry_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 / AutoGen / CrewAI
The SDK is framework-agnostic — wrap any method in a Tool and pass it
to your agent.
- LangChain, LangGraph, AutoGen — install
agentdraft-langchainfor readyBookingTool/AvailabilityTool/ConflictAwareBookingToolwrappers. - CrewAI — it accepts only its own
crewai.tools.BaseTool, so subclass that over this SDK: seeexamples/crewai_quickstart.pyand https://agentdraft.io/integrations/crewai.
Verify an approval receipt
A downstream service can verify a signed approval or consent receipt offline with the public JWKS:
from agentdraft import hash_evidence, verify_approval_token
claims = verify_approval_token(
receipt,
audience="https://deploy.example.com",
action_type="deploy.production",
evidence_sha256=hash_evidence(request_payload),
)
# claims["sub"] is the human; claims["act"]["sub"] is the agent.
verify_approval_token checks the Ed25519 signature, issuer, audience, expiry,
act.sub, and the RAR entry. Pass jwks= for an air-gapped verifier; otherwise
the public JWKS is fetched and cached for five minutes.
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.
Metadata
Release files for agentdraft 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentdraft-0.1.3.tar.gz | 20.6 kB | Without provenance | Details for agentdraft-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentdraft-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for agentdraft-0.1.3-py3-none-any.whl |
Total release size: 40.2 kB
Release files / agentdraft-0.1.3.tar.gz
| Download URL | agentdraft-0.1.3.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7759cb2414c0ae93375056e3e67369f308f311cc2f077b4ee8aaea7139557236
|
|
BLAKE2b-256 checksum How to use checksums |
a189edf550a586976ac5a100424a61ed747fc66945fa1e0b1a4165a35079f18c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / agentdraft-0.1.3-py3-none-any.whl
| Download URL | agentdraft-0.1.3-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e81b8eede279ff74f92c12683341fb9efc248dcf1f091a12a743c7d4ca64506e
|
|
BLAKE2b-256 checksum How to use checksums |
964d44caa0461e5a2f413a0c00f51cc64a3ac352936ea6e1a223b8a85f7de5b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for agentdraft 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.