@adcp/sdk weekly downloads statistics

@adcp/sdk

Official TypeScript/JavaScript SDK for the Ad Context Protocol (AdCP). Use its buyer client to call agents, server framework to build them, and conformance tools to test them. The SDK supports MCP and A2A, with both immediate and asynchronous task results.

For AI Agents

Start with docs/llms.txt — the full protocol spec in one file (tools, types, error codes, examples). Building a server? See docs/guides/BUILD-AN-AGENT.md. Calling an AdCP agent as a buyer? Load skills/call-adcp-agent/SKILL.md — wire contract, async flow, and error-recovery priors that aren't in the type signatures. Setting up request signing? See docs/guides/SIGNING-GUIDE.md. For type signatures, use docs/TYPE-SUMMARY.md. Skip src/lib/types/*.generated.ts — they're machine-generated and will burn context.

These docs are also available in node_modules/@adcp/sdk/docs/ after install.

The Core Concept

AdCP operations are distributed and asynchronous by default. An agent might:

• Complete your request immediately (synchronous) • Need time to process and send results via webhook (asynchronous) • Ask for clarifications before proceeding • Send periodic status updates as work progresses

Your code stays the same. You write handlers once, and they work for both sync completions and webhook deliveries.

Installation

Upgrading to SDK 14? Read the release-bound upgrade worksheet, then use the 13-to-14 or 12-to-14 migration guide. The prerelease history covers changes made during the 14.0 beta cycle. The npm latest tag tracks SDK 14 (AdCP 3.2); SDK 13 stays available on adcp-3.1 as the maintained AdCP 3.1 line. SDK 14 requires Node.js ^20.19.0 || >=22.12.0. Older paths: 12-to-13, MIGRATION-v8.md, and 8.0-to-8.1.

Narrow type imports (@adcp/sdk/types/)

Adopters who only need a single AdCP tool's types can import a per-tool slice instead of the full surface. Each slice is a self-contained .d.ts covering the tool's Request / Response / Success / Error / Submitted types and every type they reference:

Why bother: the full @adcp/sdk type surface is ~45,000 lines and crashes tsc at Node's default 4 GB heap under strict + skipLibCheck:false. A single per-tool slice peaks at ~50 MB. That's the difference between adopters chasing the cryptic FATAL: mark-compact Node flag and just having their build pass.

Slices use kebab-case filenames matching the schema cache (sync_accounts → @adcp/sdk/types/sync-accounts). Requires moduleResolution: "node16" / "nodenext" / "bundler" on the adopter side. A machine-readable index of available slices ships at @adcp/sdk/types/per-tool-index.json.

TypeScript footprint in monorepos

Large workspaces should keep the generated schema surface out of the default type-check path unless they actually need runtime Zod validators. The root @adcp/sdk export and @adcp/sdk/types do not re-export generated Zod schemas; import those schemas from @adcp/sdk/schemas so ordinary SDK imports avoid pulling the full generated schema declaration set into tsc.

| Need | Recommended import |

| Client, server, signing, and response helpers | @adcp/sdk, @adcp/sdk/client, @adcp/sdk/server, or another focused runtime subpath | | One tool's request/response types | @adcp/sdk/types/ such as @adcp/sdk/types/sync-accounts | | Runtime Zod schemas and tool schema maps | @adcp/sdk/schemas | | Runtime Zod schemas in browser UIs | @adcp/sdk/schemas/browser | | Broad generated protocol type barrel | @adcp/sdk/types |

Browser widgets and dashboards can validate AdCP objects with the generated Zod schemas:

The browser entry also exports GetProductsRequestSchema and LegacyGetProductsRequestSchema, BiddingPolicySchema, CanonicalBudgetAllocationSchema, and the strict SyncCreatives* validators, with the same validation behavior as the Node entry. It has no Node built-ins in its import graph. JSON Schema loading and tool registration helpers remain available from @adcp/sdk/schemas. The generated schemas still initialize together, so importing one schema can retain the full generated module in a browser bundle; per-schema tree-shaking is tracked in #3178.

Focused client runtime (@adcp/sdk/client/core)

Applications that only call AdCP agents can avoid evaluating the SDK's server, compliance, testing, and unrelated protocol surfaces:

The existing @adcp/sdk/client path remains an alias of the package root for compatibility. Use /client/core when cold import and test-worker startup time matter.

For application monorepos, keep skipLibCheck: true unless you are intentionally auditing SDK declarations. If a package only needs request/response types for a few tools, prefer the per-tool slices over importing generated types through the root package or the broad @adcp/sdk/types barrel.

Quick Start: AdCP 3.2

SDK 14 makes the compact 3.2 lifecycle primary:

Start with the persona guide that matches your job:

• Build a seller • Call a seller • Adopt the account change feed • Upgrade from SDK 13 • Add AdCP to an existing platform • Run in production

The established get_products / create_media_buy / update_media_buy surface remains supported for AdCP 3.0/3.1 compatibility. Its detailed client patterns follow below.

Established lifecycle and distributed operations

Handling Clarifications (input-required)

When an agent needs more information, you can continue the conversation:

Webhook Pattern

All webhooks (task completions AND notifications) use one endpoint with flexible URL templates.

Configure Your Webhook URL Structure

Single Webhook Endpoint

URL Generation is Automatic

Activity Events

Get observability into everything happening:

Activity types:

• protocol_request - Request sent to agent • protocol_response - Response received from agent • status_change - Task status changed • webhook_received - Webhook received from agent

Notifications (Agent-Initiated)…

Description from the npm listing.