Ad Context Protocol (AdCP) Advertising Skill#

Overview#

Automate your advertising campaigns with AI. This skill enables OpenClaw agents to discover ad inventory, launch campaigns, manage creatives, and optimize performance across display, video, CTV, audio, and more - all through natural language commands.

No dashboards. No forms. No ad platform expertise required.

What You Can Do#

• 🎯 Launch campaigns in minutes - "Create a $10k display campaign targeting tech professionals in California"
• 🔍 Discover ad inventory instantly - "Find premium video placements for luxury brands"
• 🎨 Upload ads with ease - "Upload these banner images as creatives"
• 📊 Track ROI in real-time - "Show me campaign performance and CTR by creative"
• 🎛️ Auto-optimize spend - "Reallocate budget to top-performing packages"
• 🌐 Target precisely - Demographics, behaviors, interests, locations, devices, times

Perfect For#

Marketing teams running Facebook ads, Google ads, and multi-channel campaigns

Media buyers managing programmatic ad spend across publishers

Agencies automating client campaign management and reporting

E-commerce brands launching product ads and retargeting campaigns

Startups running lean marketing with AI-powered automation

Why Choose This Skill?#

Skip the learning curve - No need to master complex ad platforms

Save time - Launch in 5 minutes vs. hours of manual setup

Spend smarter - AI automatically optimizes budgets to top performers

Scale faster - Manage unlimited campaigns through simple commands

Test risk-free - Public test agent included, no setup required

Official AdCP Repository: https://github.com/adcontextprotocol/adcp

Official AdCP Documentation: https://docs.adcontextprotocol.org

Complete Documentation Index: https://docs.adcontextprotocol.org/llms.txt

When to Use This Skill#

Trigger this skill when users ask about:

Campaign Management

• "Create a display ad campaign"
• "Launch Facebook ads for my product"
• "Set up a $5000 video advertising campaign"
• "Pause my underperforming campaigns"

Ad Discovery & Media Buying

• "Find advertising inventory for luxury brands"
• "Show me CTV ad placements in major cities"
• "What display ad options are available?"
• "Buy media for a tech startup"

Creative Management

• "Upload these banner images"
• "Which creative is performing best?"
• "Add video ads to my campaign"
• "Manage my ad library"

Performance & Optimization

• "How is my campaign performing?"
• "Show me ROI by channel"
• "Optimize my ad spend"
• "Reallocate budget to top performers"
• "Track impressions and click-through rates"

Targeting & Audiences

• "Target professionals in California"
• "Set up demographic targeting"
• "Create a retargeting campaign"
• "Target by device type and time of day"

Quick Start#

Launch Your First Campaign (5 Minutes)#

No setup required. Use the included test agent to try everything:

Step 1: Discover what's available

text

"Show me advertising capabilities"

Browse available channels, publishers, and formats.

Step 2: Find ad inventory

text

"Find display ads for a tech startup, budget $5000"

AI searches and shows matching products with pricing.

Step 3: Launch campaign

text

"Create campaign with Product prod_123, $5000 budget, targeting California tech professionals"

Campaign goes live instantly.

Step 4: Upload your ads

text

"Upload these banner images as creatives"

Drop files, get instant creative IDs.

Step 5: Monitor performance

text

"Show campaign metrics and ROI"

Real-time impressions, clicks, CTR, spend.

Real-World Usage Examples#

Quick campaign launch:

text

User: "I need to run display ads for my SaaS product"
Agent: [Discovers products] "Found 5 display packages. Want details?"
User: "Create campaign with Product 1, $10k budget, target CTOs"
Agent: [Creates campaign] "Campaign live! ID: mb_abc123"

Performance optimization:

text

User: "How are my video ads performing?"
Agent: [Shows metrics] "Package A: 2.3% CTR, Package B: 0.8% CTR"
User: "Move $5k from B to A"
Agent: [Reallocates] "Budget updated. Package A now $15k"

Multi-channel campaign:

text

User: "Launch omnichannel campaign: display in CA, video in NYC, $50k total"
Agent: [Creates packages] "3 packages created across display and video"

How It Works#

Natural Language Understanding#

Speak naturally. The skill understands:

• Budgets: "$5000", "five thousand dollars", "5k budget"
• Locations: "California", "major US cities", "New York and LA"
• Audiences: "tech professionals", "age 25-45", "high income"
• Goals: "brand awareness", "drive conversions", "increase sales"

Progressive Workflow#

1. Discovery Phase

text

"Find video advertising for luxury brands"

↓ Agent searches inventory ↓ Shows matched products with pricing ↓ Explains targeting and formats

2. Campaign Creation

text

"Create campaign with Product 1, $25k, target professionals"

↓ Agent creates media buy ↓ Sets up targeting overlay ↓ Returns campaign ID and status

3. Creative Management

text

"Upload my banner ads"

↓ Agent syncs creatives ↓ Assigns to campaign ↓ Returns creative IDs

4. Monitoring & Optimization

text

"Show performance"

↓ Agent fetches delivery data

↓ Shows metrics by package/creative

↓ Suggests optimizations

Core Operations#

Create Campaign#

javascript

const campaign = await testAgent.createMediaBuy({
  buyer_ref: 'campaign-2026-q1',
  brand_manifest: { url: 'https://acme.com' },
  packages: [{ product_id: 'premium_display', budget: 10000 }]
});

Upload Creatives#

javascript

await testAgent.syncCreatives({
  creatives: [{
    buyer_ref: 'banner-300x250',
    url: 'https://cdn.acme.com/banner.jpg'
  }]
});

Monitor Performance#

javascript

const delivery = await testAgent.getMediaBuyDelivery({
  media_buy_id: 'mb_abc123'
});
console.log(`CTR: ${delivery.totals.ctr}%, Spend: $${delivery.totals.spend}`);

See REFERENCE.md for complete API docs and EXAMPLES.md for detailed workflows.

Core Concepts#

The 8 Media Buy Tasks#

AdCP provides 8 standardized tasks for the complete advertising lifecycle. Learn more in the Media Buy Protocol documentation.

1. get_adcp_capabilities - Discover agent features and portfolio (~1s)
2. get_products - Find inventory using natural language (~60s)
3. list_creative_formats - View creative specifications (~1s)
4. create_media_buy - Launch campaigns (minutes-days, may require approval)
5. update_media_buy - Modify campaigns (minutes-days)
6. sync_creatives - Upload creative assets (minutes-days)
7. list_creatives - Query creative library (~1s)
8. get_media_buy_delivery - Track performance (~60s)

Complete task reference: https://docs.adcontextprotocol.org/docs/media-buy/task-reference/

Brand Manifest#

Brand context can be provided two ways:

URL reference (recommended - agent fetches brand info):

json

{
  "brand_manifest": {
    "url": "https://brand.com"
  }
}

Inline manifest (full brand details):

json

{
  "brand_manifest": {
    "name": "Brand Name",
    "url": "https://brand.com",
    "tagline": "Brand tagline",
    "colors": { "primary": "#FF0000" },
    "logo": { "url": "https://cdn.brand.com/logo.png" }
  }
}

Pricing Models#

Products support various pricing models:

• CPM (Cost Per Mille/Thousand) - Fixed price per 1000 impressions
• CPM-Auction - Bid-based pricing for impressions
• CPCV (Cost Per Completed View) - Video completions
• Flat-Fee - Fixed campaign cost
• CPP (Cost Per Point) - Percentage of audience reached

For auction pricing, include bid_price in your package.

Asynchronous Operations#

AdCP is not a real-time protocol. Operations may take:

• ~1 second - Simple lookups (formats, creative lists)
• ~60 seconds - AI/inference operations (product discovery)
• Minutes to days - Operations requiring human approval (campaign creation)

Always check the status field in responses:

• completed - Operation finished successfully
• pending - Awaiting approval or processing
• failed - Operation failed (check error details)

Targeting Capabilities#

Apply targeting overlays to campaigns:

javascript

{
  targeting_overlay: {
    geo: {
      included: ['US-CA', 'US-NY'],  // DMA codes or regions
      excluded: ['US-TX']
    },
    demographics: {
      age_ranges: [{ min: 25, max: 44 }],
      genders: ['M', 'F']
    },
    behavioral: {
      interests: ['technology', 'gaming'],
      purchase_intent: ['consumer_electronics']
    },
    contextual: {
      keywords: ['innovation', 'design'],
      categories: ['IAB19'] // Technology & Computing
    }
  }
}

Common Workflows#

Workflow 1: Campaign Discovery to Launch#

javascript

// 1. Discover capabilities
const caps = await agent.getAdcpCapabilities({});

// 2. Find products
const products = await agent.getProducts({
  brief: 'Q1 2026 brand awareness campaign for tech startup',
  brand_manifest: { url: 'https://startup.com' },
  filters: { channels: ['display', 'video'] }
});

// 3. Check creative formats
const formats = await agent.listCreativeFormats({
  format_types: ['display', 'video']
});

// 4. Create campaign
const campaign = await agent.createMediaBuy({
  buyer_ref: 'q1-2026-awareness',
  brand_manifest: { url: 'https://startup.com' },
  packages: [
    {
      buyer_ref: 'pkg-001',
      product_id: products.products[0].product_id,
      pricing_option_id: 'cpm-standard',
      budget: 15000
    }
  ],
  start_time: { type: 'asap' },
  end_time: '2026-03-31T23:59:59Z'
});

// 5. Upload creatives
await agent.syncCreatives({
  creatives: [...], // Your creative assets
  assignments: {
    'creative_001': ['pkg-001']
  }
});

// 6. Monitor performance
const delivery = await agent.getMediaBuyDelivery({
  media_buy_id: campaign.media_buy_id
});

Workflow 2: Update Running Campaign#

javascript

// Pause, adjust budget, and resume campaign
await agent.updateMediaBuy({
  media_buy_id: 'mb_abc123',
  updates: {
    status: 'paused',
    budget_change: 5000, // Add $5000
    end_time: '2026-04-30T23:59:59Z'
  }
});

// Resume after adjustments
await agent.updateMediaBuy({
  media_buy_id: 'mb_abc123',
  updates: { status: 'active' }
});

More workflow examples: See EXAMPLES.md for complete campaign scenarios including creative management, multi-channel campaigns, and optimization workflows.

Test Agent#

For development and testing, use the public test agent:

Agent URL: https://test-agent.adcontextprotocol.org/mcp

Auth Token: 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ

javascript

import { testAgent } from '@adcp/client/testing';

// No authentication needed for test agent
const result = await testAgent.getProducts({
  brief: 'Test campaign',
  brand_manifest: { url: 'https://example.com' }
});

Interactive testing available at: testing.adcontextprotocol.org

Error Handling#

Common error patterns:

400 Bad Request - Invalid parameters:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "budget must be greater than 0",
    "field": "packages[0].budget"
  }
}

401 Unauthorized - Missing or invalid auth:

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid authentication token"
  }
}

404 Not Found - Invalid ID reference:

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found",
    "resource": "product_id: premium_video_30s"
  }
}

Always check for errors before processing responses:

javascript

if (result.error) {
  console.error(`Error: ${result.error.message}`);
  return;
}

Best Practices#

1. Always Start with Capabilities#

Call get_adcp_capabilities first to understand what the agent supports before making other requests.

2. Use Clear Buyer References#

Use descriptive buyer_ref values for tracking:

• Good: 'campaign-2026-q1-tech-launch'
• Avoid: 'c1', 'test', 'abc'

3. Handle Async Operations#

Check status field and implement polling for pending operations:

javascript

let status = 'pending';
while (status === 'pending') {
  await sleep(5000); // Wait 5 seconds
  const update = await agent.getMediaBuyDelivery({
    media_buy_id: campaign.media_buy_id
  });
  status = update.status;
}

4. Write Detailed Briefs#

Better briefs lead to better product matches:

• Good: 'Premium video inventory for luxury automotive brand targeting high-income professionals aged 35-54 in major metros. Focus on brand awareness with completion rates above 70%.'
• Avoid: 'video ads', 'need advertising'

5. Validate Creative Formats#

Always check list_creative_formats to ensure your creatives meet requirements before uploading.

6. Monitor Budget Pacing#

Regularly check delivery metrics to ensure campaigns are pacing properly:

javascript

const delivery = await agent.getMediaBuyDelivery({
  media_buy_id: campaign.media_buy_id
});

const pacing = delivery.delivery.spend / delivery.delivery.budget;
console.log(`Budget pacing: ${(pacing * 100).toFixed(1)}%`);

Additional Resources#

Official AdCP Documentation#

• Main Documentation: https://docs.adcontextprotocol.org
• Complete Index: https://docs.adcontextprotocol.org/llms.txt
• Media Buy Protocol: https://docs.adcontextprotocol.org/docs/media-buy/
• Quick Reference: https://docs.adcontextprotocol.org/docs/media-buy/quick-reference
• Task Reference: https://docs.adcontextprotocol.org/docs/media-buy/task-reference/
• Quickstart Guide: https://docs.adcontextprotocol.org/docs/quickstart

This Skill's Documentation#

• REFERENCE.md - Complete API reference and schemas
• EXAMPLES.md - Real-world campaign examples
• PROTOCOLS.md - MCP vs A2A protocol details
• TARGETING.md - Advanced targeting strategies
• CREATIVE.md - Creative asset management guide

Key Reminders#

1. AdCP is asynchronous - Operations may take minutes to days
2. Human approval may be required - Check for pending status
3. Start with capabilities - Always call get_adcp_capabilities first
4. Brand context matters - Provide detailed brand manifests for better results
5. Targeting is additive - Product targeting + your overlay = final targeting
6. Creative formats are strict - Always validate against format specifications
7. Monitor performance - Regular delivery checks ensure campaign success

Support#

For help with AdCP:

• Official Repository: https://github.com/adcontextprotocol/adcp
• Documentation: https://docs.adcontextprotocol.org
• Interactive Testing: https://testing.adcontextprotocol.org
• Complete API Docs: https://docs.adcontextprotocol.org/llms.txt