agentdraft — TypeScript SDK

The official TypeScript / JavaScript SDK for AgentDraft — the ops API for AI agents with inbox, conflict-free calendar, and audit trail.

AgentDraft gives each agent an inbox and routes every calendar hold or commit through one deterministic engine, so multiple agents can act on the same calendar without double-booking.

This SDK gives Node and edge agents a typed, one-line surface to participate.

Install

npm install agentdraft

ESM-only. Requires Node 18+.

Upgrade

npm install agentdraft@latest

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

Quickstart

import { AgentDraft, Conflict } from "agentdraft";

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",
    title: "Discovery call",
    invitee: { name: "Ada Lovelace", email: "[email protected]" },
  });
  console.log("booked:", booking.bookingId);
} catch (e) {
  if (e instanceof Conflict) {
    console.log(`outranked by ${e.winningAgentId} (rank ${e.winningAgentPriority})`);
  } else {
    throw e;
  }
}

title and invitee ({ name?, email?, notes? }) are first-class fields: persisted on the booking, returned on the Booking object, and shown to the calendar owner in the dashboard. A top-level title supersedes a 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 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 agentdraft shows the published tarball metadata. npm provenance attestations are temporarily disabled pending a move to github-hosted runners — see ryabinski-labs/agentdraft#168.

Links

• Protocol spec: https://agentdraft.io/spec
• API docs: https://agentdraft.io/docs
• Changelog: CHANGELOG.md
• Issues / source: https://github.com/ryabinski-labs/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 ryabinski-labs/agentdraft monorepo under sdks/typescript/.

License

MIT — see LICENSE.