SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsadcp

adcp

Marketing & growth

View repository

Updated 10-15 10:31

About this skill

AdCP CLI

Use adcp (or npx @adcp/sdk@latest) to interact with AdCP advertising agents, run compliance tests, and query the AdCP registry.

Quick start — zero config

Built-in test agents work immediately with no setup:

# Try AdCP right now
adcp test-mcp                                          # List tools on the MCP test agent
adcp test-mcp get_products '{"brief":"coffee brands"}' # Call a tool
adcp test-a2a get_products '{"brief":"coffee brands"}' # Same thing over A2A

# Run compliance tests
adcp test test-mcp discovery                           # Test tool discovery
adcp test test-mcp full_sales_flow                     # Full media buy lifecycle

Built-in aliases (no setup needed):

  • test-mcp — Public test agent via MCP (pre-authenticated)
  • test-a2a — Public test agent via A2A (pre-authenticated)
  • test-no-auth — MCP without auth (demonstrates auth errors)
  • test-a2a-no-auth — A2A without auth
  • creative — Official creative agent (MCP, requires --auth or ADCP_AUTH_TOKEN)

Calling agent tools

adcp <alias|url> [tool-name] [payload] [options]

Discover tools (omit tool name)

adcp https://agent.example.com
adcp my-alias

Call a tool

adcp https://agent.example.com get_products '{"brief":"coffee brands"}'
adcp https://agent.example.com create_media_buy @payload.json
echo '{"brief":"travel"}' | adcp https://agent.example.com get_products -

Authentication (priority order)

adcp my-alias get_products '{}'                                         # 1. Saved config
adcp https://agent.example.com get_products '{}' --auth $TOKEN          # 2. Flag
export ADCP_AUTH_TOKEN=your-token && adcp https://agent.example.com get_products '{}' # 3. Env
adcp https://agent.example.com/mcp --oauth                              # 4. OAuth (MCP only)

Output modes

adcp test-mcp get_products '{"brief":"test"}'          # Pretty print (default)
adcp test-mcp get_products '{"brief":"test"}' --json   # Raw JSON for scripting
adcp test-mcp get_products '{"brief":"test"}' --debug  # Connection diagnostics

Force protocol (default is auto-detect)

adcp https://agent.example.com get_products '{}' --protocol mcp
adcp https://agent.example.com get_products '{}' --protocol a2a

Testing: comply vs storyboard vs test

Three testing commands, each for a different purpose:

  • comply — Full compliance assessment. "Does my agent work?" Runs all applicable storyboards, reports by track.
  • storyboard — Debug a specific flow step by step. Stateless, context-in/context-out.
  • test — Individual legacy scenarios. Use comply for new work.

Compliance assessment (comply)

The primary way to test an AdCP agent. Runs storyboard-driven assessments grouped by capability track.

adcp comply <agent> [options]

Recommended workflow

  1. Run full compliance to see the big picture:
adcp comply my-agent --json

  1. Parse the failures array for actionable items — each failure includes storyboard_id, step_id, and a fix_command you can run directly.

  2. Debug specific failures with storyboard step:

adcp storyboard step my-agent media_buy_seller sync_accounts --json
  1. Fix and re-run. Use --storyboards to re-test only the relevant storyboard:
adcp comply my-agent --storyboards media_buy_seller --json

Filtering options (resolution priority)

Flag When to use Example
--storyboards IDS You know exactly which storyboards to run --storyboards media_buy_seller,error_compliance
--platform-type TYPE You know your platform type and want curated tests + coherence checking --platform-type retail_media
--tracks TRACKS You want to test specific capability areas --tracks media_buy,products
(none) Run everything applicable to your agent's tools adcp comply my-agent

When --platform-type and --tracks are both set, --tracks controls which storyboards run, and --platform-type adds coherence checking.

Options

  • --json — Structured JSON output (recommended for agents)
  • --platform-type TYPE — Declare platform type for curated storyboards + coherence
  • --storyboards IDS — Comma-separated storyboard IDs (highest priority)
  • --tracks TRACKS — Comma-separated tracks to test
  • --list-platform-types — Show available platform types
  • --debug — Verbose logging
  • --dry-run — Preview steps without executing

JSON output structure

The --json output includes a failures array for quick iteration:

{
  "overall_status": "partial",
  "storyboards_executed": ["capability_discovery", "media_buy_seller"],
  "failures": [
    {
      "track": "media_buy",
      "storyboard_id": "media_buy_seller",
      "step_id": "sync_accounts",
      "step_title": "Establish account relationship",
      "error": "Unknown tool: sync_accounts",
      "expected": "Return the account with account_id, status, ...",
      "fix_command": "adcp storyboard step <agent> media_buy_seller sync_accounts --json"
    }
  ],
  "summary": { "headline": "1 passing, 3 partial" },
  "tracks": [ ... ]
}

Storyboard testing

Explore and debug individual storyboard flows.

adcp storyboard list [--platform-type TYPE] [--json]    # List storyboards
adcp storyboard show <id> [--json]                       # Show structure and narratives
adcp storyboard run <agent> <id> [options]               # Run full storyboard
adcp storyboard step <agent> <id> <step_id> [options]    # Run single step

Step-by-step debugging (agent-friendly)

Each step returns context and a preview of the next step:

# Run step 1
adcp storyboard step my-agent media_buy_seller sync_accounts --json > step1.json

# Feed context to step 2
adcp storyboard step my-agent media_buy_seller get_products_brief \
  --context @step1_context.json --json

The --context flag accepts inline JSON or @file.json (read from file).

Step options

  • --context JSON or --context @file.json — Pass state from previous steps
  • --request JSON or --request @file.json — Override sample_request
  • --json — Structured output

Legacy test runner

Individual scenario testing. 24 built-in scenarios.

adcp test <agent> [scenario] [options]
adcp test --list-scenarios                               # List all scenarios

Common scenarios

Scenario What it tests
health_check Basic connectivity
discovery get_products, list_creative_formats
full_sales_flow Full lifecycle: discovery, create, update, delivery
signals_flow Signals: get_signals, activate
capability_discovery v3: get_adcp_capabilities

Run adcp test --list-scenarios for all 24 with descriptions.

Test options

  • --json — Machine-readable output for CI
  • --debug — Verbose logging
  • --protocol mcp|a2a — Force protocol
  • --dry-run — Preview steps without executing
  • --brief "text" — Custom brief for product discovery tests

Registry

Look up brands, properties, agents, and publishers in the AdCP registry.

adcp registry <command> [args] [options]

Lookups

adcp registry brand nike.com
adcp registry brands nike.com adidas.com --json
adcp registry property nytimes.com
adcp registry enrich-brand nike.com

Discovery and validation

adcp registry discover https://agent.example.com
adcp registry validate nytimes.com
adcp registry validate-publisher nytimes.com
adcp registry lookup nytimes.com
adcp registry check-auth https://agent.com domain nytimes.com

Listing and search

adcp registry agents --type sales --health
adcp registry search nike --json
adcp registry publishers
adcp registry stats

Save operations (requires --auth or ADCP_REGISTRY_API_KEY)

adcp registry save-brand acme.com "Acme Corp" --auth $KEY
adcp registry save-property example.com '{"properties":[{"property_type":"website","name":"Example","identifiers":[{"type":"domain","value":"example.com"}],"tags":["news"]}]}' --auth $KEY

Agent management

adcp --save-auth prod https://prod-agent.com           # Interactive setup
adcp --save-auth prod https://agent.com --auth $TOKEN  # With token
adcp --save-auth prod https://agent.com --no-auth      # No auth
adcp --save-auth prod https://agent.com/mcp --oauth    # OAuth (MCP only)
adcp --list-agents
adcp --remove-agent prod
adcp --show-config

Config stored at ~/.adcp/config.json.

Async/webhook support

For long-running operations (e.g. create_media_buy with human-in-the-loop approval):

adcp https://agent.example.com create_media_buy @payload.json --auth $TOKEN --wait
adcp http://localhost:3000/mcp create_media_buy @payload.json --wait --local
  • --wait — Start webhook listener, wait for async response
  • --local — Local webhook without ngrok (for localhost agents)
  • --timeout MS — Webhook timeout (default: 300000 = 5 min)

Remote --wait requires ngrok: brew install ngrok

Exit codes

  • 0 — Success
  • 1 — Network or JSON error
  • 2 — Invalid arguments
  • 3 — Agent error (auth failure, task failed, webhook timeout)

Task: $ARGUMENTS

Step 1: Check installation

which adcp 2>/dev/null && echo "installed" || echo "use npx @adcp/sdk@latest"

If not installed, prefix all commands with npx @adcp/sdk@latest. Requires Node.js 18+.

Step 2: Route the request

  • "try AdCP" / "show me how it works" / no specific agent — Use built-in test-mcp
  • "what tools" / "discover" / "list tools" — adcp <agent> with no tool name
  • "test" / "compliance" / "validate agent" / "does my agent work" — adcp comply <agent> --json
  • "debug a specific failure" / "why does this step fail" — adcp storyboard step <agent> <storyboard_id> <step_id> --json
  • "run a specific scenario" — adcp test <agent> [scenario] (legacy)
  • "brand" / "property" / "registry" / "look up" / "validate domain" — adcp registry <command>
  • Specific tool name mentioned — adcp <agent> <tool> '<payload>'
  • "compare protocols" — Run same call with --protocol mcp then --protocol a2a, diff results
  • "build an agent" / "implement AdCP" / "server side" — Read docs/guides/BUILD-AN-AGENT.md for server setup, and storyboards/ for expected tool call sequences. Use docs/llms.txt for the protocol overview.

Step 3: Handle authentication

  1. Built-in aliases test-mcp and test-a2a have auth included — use for demos
  2. creative alias has no auth bundled — user must provide --auth or ADCP_AUTH_TOKEN
  3. Saved aliases may have auth — check with adcp --list-agents
  4. --auth $TOKEN flag or ADCP_AUTH_TOKEN env var
  5. --oauth for MCP agents using OAuth (opens browser, saves tokens to alias)
  6. If no auth and agent requires it, ask the user

Step 4: Choose output format

  • Default (pretty print) for exploration and debugging
  • --json when piping, parsing, or running in CI
  • --debug when troubleshooting connection or protocol issues

Step 5: Run and interpret

  • Run the command
  • Exit code 1: network/parsing error — suggest --debug
  • Exit code 2: bad arguments — check syntax
  • Exit code 3: agent error — check auth token, try --debug, verify agent is reachable
  • Empty results are valid — do not fabricate data
  • For --json output, parse and summarize the key fields for the user