Build an Agent

Use AdCP SDK skill files to generate storyboard-compliant agents with a coding agent in minutes.

The fastest way to build an AdCP agent is to point a coding agent (Claude Code, Codex, Cursor, Windsurf) at a skill file from an AdCP SDK. Each skill produces a protocol-compliant, storyboard-validated agent in 2–8 minutes.

Publisher without an engineering team? Protocol compliance is one piece of going live — product management, activation into your ad server, and hosting are separate lifts. See Operating an Agent for the three paths: partner with a managed platform, self-host a prebuilt agent, or build your own.

Install the SDK

Each SDK handles protocol compliance — schema validation, error formats, version negotiation, and response builders — so you write business logic, not protocol plumbing.

JavaScript/TypeScript

npm install @adcp/sdk

The JS/TS SDK provides typed tool registration, response builders, and a built-in storyboard runner. Most agents in production use this SDK.

• NPM Package
• GitHub Repository

Python

pip install adcp

The Python SDK provides the same capabilities — subclass ADCPHandler, implement tools, and use response builders for every return value:

from adcp.server import ADCPHandler, serve
from adcp.server.responses import capabilities_response

class MySeller(ADCPHandler):
    async def get_adcp_capabilities(self, params, context=None):
        return capabilities_response(["media_buy"])

    # ... implement tools, use response builders for every return

serve(MySeller(), name="my-seller")

Response builders (adcp.server.responses) handle schema compliance so you don’t construct raw JSON. Use them for every tool return.

• PyPI Package
• GitHub Repository

Go

go get github.com/adcontextprotocol/adcp-go/adcp

The Go SDK provides typed tool registration, response builders, and a compliance test controller. Types are generated from canonical AdCP schemas.

Component	Import
Tool registration	adcp.AddTool(server, name, desc, handler)
HTTP server	adcp.Serve(createAgent)
Response builders	adcp.ProductsResponse(data), adcp.MediaBuyResponse(data)
Test controller	adcp.RegisterTestController(server, store)

See the Go SDK README for complete examples.

Response builders (adcp.ProductsResponse(), adcp.MediaBuyResponse(), etc.) handle schema compliance so you return typed structs, not raw JSON.

• GitHub Repository

Use the SDK for your language. All three SDKs — JS/TS, Python, and Go — handle schema validation, error formats, and protocol negotiation. You do not need to use a different language for protocol compliance.

Choose a skill

Each SDK ships skills that walk a coding agent through building a specific agent type. Common skills across SDKs:

• build-seller-agent — publisher, SSP, or media network selling inventory
• build-signals-agent — CDP or data provider serving audience segments
• build-creative-agent — ad server or CMP rendering creatives
• build-generative-seller-agent — AI ad network generating ads from briefs
• build-retail-media-agent — retail media network with catalog-driven creative

For example, the JS/TS seller skill lives at adcp-client/skills/build-seller-agent/SKILL.md. Skill coverage and naming vary per language since each SDK includes implementation guidance specific to its stack. Browse the directory for your language:

• JS/TS — adcp-client/skills
• Python — adcp-client-python/skills
• Go — adcp-go/skills

Which domain and specialisms do you claim?

Each agent declares its supported_protocols (domains) and specialisms on get_adcp_capabilities. Each skill’s storyboard verifies the domain baseline — to also claim a specialism, your agent must pass that specialism’s storyboard. Skills-to-specialism mapping:

Skill	Typical supported_protocols	Typical specialisms (pick one or combine)
build-seller-agent	["media_buy", "creative"]	sales-guaranteed, sales-non-guaranteed
build-generative-seller-agent	["media_buy", "creative"]	creative-generative + sales-non-guaranteed
build-retail-media-agent	["media_buy", "creative"]	sales-catalog-driven
build-signals-agent	["signals"]	signal-owned, signal-marketplace
build-creative-agent	["creative"]	creative-ad-server, creative-template

Picking a sales specialism: See Choosing a sales specialism in the Compliance Catalog for the full decision tree. Quick reference:

• sales-guaranteed — IO approval, fixed pricing. Set media_buy.supports_proposals: true if you support RFP/proposal flows; false (or omit) for direct-buy only.
• sales-non-guaranteed — auction / PMP.
• sales-broadcast-tv, sales-catalog-driven, sales-social — channel-specific; see the decision tree.

You can claim more than one. See the Compliance Catalog for the full taxonomy and per-specialism storyboards.

Building a brand rights agent (licensing talent, music, stock media)? There’s no skill today — see the Brand Protocol docs and claim brand-rights under the brand domain.

See the Compliance Catalog for every domain and specialism with its storyboard and status (stable, preview, deprecated).

Storyboard passing earns the AAO Verified (Spec) qualifier — validated against seeded test data on a test-mode endpoint. Once your agent is running against real production inventory, consider enrolling in the (Live) qualifier, which adds continuous observability of real delivery on a dedicated compliance account. An agent can hold (Spec), (Live), or both; enterprise buyers that treat AdCP as production infrastructure filter on (Live).

Build the agent

Point your coding agent at the skill file for your agent type. In Claude Code:

JavaScript/TypeScript

Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-client/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports news publisher with guaranteed CTV and OLV inventory.

Python

Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-client-python/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports news publisher with guaranteed CTV and OLV inventory.

Point at the adcp-client-python skill for your agent type. If the exact skill isn’t there yet, browse adcp-client-python/skills for the closest match.

Go

Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-go/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports publisher.

In Cursor or Windsurf, download the skill file and include it as context with your prompt. Each skill walks the coding agent through:

1. Business model decisions (what you sell, how you price, approval workflow)
2. Tool registration with correct schemas
3. Response shapes that pass storyboard validation
4. Error handling and edge cases

Validate with storyboards

The storyboard runner requires Node.js, regardless of what language your agent is written in.

Once the agent is running, validate it against the matching storyboard:

# JS/TS agent
npx tsx agent.ts &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json

# Python agent
python agent.py &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json

# Go agent
go run main.go &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json

Storyboards exercise every required tool call and validate response shapes. The storyboard runner uses sandbox mode by default — your agent receives sandbox: true on all account references and should return simulated data without real platform calls. A passing run means your agent is protocol-compliant.

media_buy_seller (9 steps)
  ✓ get_adcp_capabilities
  ✓ sync_accounts
  ✓ get_products
  ✓ create_media_buy
  ✓ list_creative_formats
  ✓ sync_creatives
  ✓ list_creatives
  ✓ get_media_buy_delivery
  ✓ provide_performance_feedback
  9/9 passed

Protocol-compliant ≠ production-ready. A passing run means your agent speaks AdCP correctly. Going live requires business infrastructure behind each tool call — products and pricing, activation into your ad server, order management, hosting, and discovery registration via adagents.json. See Operating an Agent for the full list and whether to partner, self-host, or build.

Each skill includes variant storyboards for different business models — non-guaranteed, guaranteed with approval, proposal mode, and more. Run npx @adcp/sdk@latest storyboard list to see all available storyboards.

See Validate Your Agent for the full testing workflow — debugging failing steps, running compliance checks, and validating interactively through Addie. If your agent wraps an upstream platform (DSP, SSP, retail data, creative server, signal marketplace), see Validate adapter agents with mock upstream fixtures for the pre-staging gate that surfaces façade bugs storyboards alone don’t catch.

Additional resources

The JS/TS SDK includes documentation designed for both humans and coding agents:

Resource	JS/TS location	Purpose
Protocol spec	node_modules/@adcp/sdk/docs/llms.txt	Full protocol in one file — tools, types, error codes, examples
Server guide	node_modules/@adcp/sdk/docs/guides/BUILD-AN-AGENT.md	Server-side implementation patterns

Python and Go equivalents are in each SDK’s GitHub repository. See adcp-client-python and adcp-go.

What’s next

• Validate Your Agent — Storyboards, compliance checks, and the build-validate-fix loop
• Operating an Agent — What sits behind the protocol layer, and whether to partner, self-host, or build
• Choose your SDK — Schema access, CLI tools, and SDK package exports
• MCP integration guide — Transport, sessions, and auth details
• Task lifecycle — Status values, transitions, and polling
• Error handling — Error categories, codes, and recovery