@agentdraftio/sdk

@agentdraftio/sdk — TypeScript SDK

The official TypeScript / JavaScript 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 Node and edge agents a typed, one-line surface to participate.

Install

npm install @agentdraftio/sdk

ESM-only. Requires Node 18+.

Upgrade

npm install @agentdraftio/sdk@latest

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

Quickstart

import { AgentDraft, Conflict } from "@agentdraftio/sdk";

const client = new AgentDraft({ apiKey: process.env.AGENTDRAFT_API_KEY! });

const start = new Date(Date.now() + 4 * 60 * 60 * 1000);
const end   = new Date(start.getTime() + 30 * 60 * 1000);

try {
  const booking = await client.bookings.commit({
    start, end,
    idempotencyKey: "ik_call_42",
    metadata: { title: "Discovery call" },
  });
  console.log("booked:", booking.bookingId);
} catch (e) {
  if (e instanceof Conflict) {
    console.log(`outranked by ${e.winningAgentId} (rank ${e.winningAgentPriority})`);
  } else {
    throw e;
  }
}

A losing agent gets a typed Conflict error, not a timeout — it knows who won, by what priority, and where the audit row lives, so fallback behavior is a clean instanceof away.

Authentication

API keys are issued from the AgentDraft dashboard and start with avs_live_. Pass it via the constructor or set AGENTDRAFT_API_KEY in the environment.

new AgentDraft({ apiKey: "avs_live_..." });
// or:
process.env.AGENTDRAFT_API_KEY = "avs_live_...";
new AgentDraft();

For local development against a dev backend, pass baseUrl: or set AGENTDRAFT_BASE_URL.

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

Error types

• Conflict — your write was outranked. Carries winningAgentId, winningAgentPriority, winningBookingId, auditEventId.
• AuthError — bad/missing/expired API key.
• RateLimited — token bucket exhausted. Has retryAfterSeconds.
• RuleViolation — request was syntactically valid but violated a rule.
• ApiError — base class.

Idempotency

Pass idempotencyKey to bookings.commit({...}). The server caches the result by (agentId, key) for 24 hours, so retries return the original booking, not a duplicate.

Supply chain

Releases are cut from the publish-typescript-sdk.yml workflow on ts-sdk-v* tag pushes. npm view @agentdraftio/sdk shows the published tarball metadata. npm provenance attestations are temporarily disabled pending a move to github-hosted runners — see GipsyChef/agentdraft#168.

Links

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

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/typescript/.

License

MIT — see LICENSE.