@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

npm install @adcp/sdk              # 16.x, AdCP 3.2
npm install @adcp/sdk@adcp-3.1     # 13.x, maintained AdCP 3.1 line
npm install @adcp/sdk@adcp-3.0     # 7.11.x, AdCP 3.0

AdCP 2 reached end of life on August 1, 2026. This checkout supports AdCP 3 agents only; review the AdCP 2 retirement guide before upgrading an integration that still calls AdCP 2 sellers.

Upgrading to SDK 16? Read the SDK 16 release notes and release-bound upgrade worksheet. The npm latest tag tracks SDK 16 (AdCP 3.2); SDK 13 stays available on adcp-3.1 as the maintained AdCP 3.1 line. SDK 16 requires Node.js ^20.19.0 || >=22.12.0. Earlier migration guides: SDK 15 OAuth, 13-to-14, 12-to-14, 12-to-13, MIGRATION-v8.md, and 8.0-to-8.1.

Narrow type imports (@adcp/sdk/types/<tool>)

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:

import type { SyncAccountsRequest } from '@adcp/sdk/types/sync-accounts';

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/<tool> 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:

import {
  EventSourceHealthSchema,
  SyncAudiencesResponseSchema,
  SyncEventSourcesResponseSchema,
} from '@adcp/sdk/schemas/browser';…