AdCP Creative Protocol

This skill enables you to execute the AdCP Creative Protocol with creative agents. Use the standard MCP tools (list_creative_formats, build_creative, preview_creative) exposed by the connected agent.

Buyer-side basics — idempotency replay, oneOf variants, async status:'submitted' polling, error recovery from adcp_error.issues[] — live in skills/call-adcp-agent/SKILL.md. This skill covers per-task semantics only.

Overview

The Creative Protocol provides 4 standardized tasks for building and previewing advertising creatives:

| Task | Purpose | Response Time | |------|---------|---------------| | list_creative_formats | View format specifications | ~1s | | build_creative | Generate or transform creatives | ~30s-5m | | preview_creative | Get visual previews | ~5s | | get_creative_delivery | Variant-level delivery data | ~5-30s |

Typical Workflow

1. Discover formats: list_creative_formats to see available format specs
2. Build creative: build_creative to generate or transform a manifest
3. Preview: preview_creative to see how it renders
4. Sync: Use sync_creatives (media-buy task) to traffic the creative

---

Task Reference

list_creative_formats

Discover creative formats and their specifications.

Request:

{
  "type": "video",
  "asset_types": ["image", "text"]
}

Key fields:

• format_ids (array, optional): Request specific format IDs
• type (string, optional): Filter by type: video, display, audio, dooh
• asset_types (array, optional): Filter by accepted asset types
• max_width, max_height (integer, optional): Dimension constraints
• is_responsive (boolean, optional): Filter for responsive formats
• name_search (string, optional): Search formats by name

Response contains:

• formats: Array of format definitions with format_id, name, type, assets_required, renders
• creative_agents: Optional array of other creative agents providing additional formats

---

build_creative

Generate a creative from scratch or transform an existing creative to a different format.

Pure Generation (from brief):

{
  "message": "Create a banner promoting our winter sale with a warm, inviting feel",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "mybrand.com"
  }
}

Transformation (resize/reformat):

{
  "message": "Adapt this leaderboard to a 300x250 banner",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_728x90"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.mybrand.com/leaderboard.png",
        "width": 728,
        "height": 90
      },
      "headline": {
        "asset_type": "text",
        "content": "Spring Sale - 30% Off"
      }
    }
  },
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  }
}

Key fields:

• message (string, optional): Natural language instructions for generation/transformation
• creative_manifest (object, optional): Source manifest - minimal for generation, complete for transformation
• target_format_id (object, required): Format to generate - { agent_url, id }

Response contains:

• creative_manifest: Complete manifest ready for preview_creative or sync_creatives

---

preview_creative

Generate visual previews of creative manifests.

Single preview:

{
  "request_type": "single",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.example.com/banner.png",
        "width": 300,
        "height": 250
      }
    }
  }
}

With device variants:

{
  "request_type": "single",
  "creative_manifest": { /* includes format_id, assets */ },
  "inputs": [
    { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
    { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } }
  ]
}

Batch preview (5-10x faster):

{
  "request_type": "batch",
  "requests": [
    { "creative_manifest": { /* creative 1 */ } },
    { "creative_manifest": { /* creative 2 */ } }
  ]
}

Key fields:

• request_type (string, required): "single" or "batch"
• format_id (object, optional): Format identifier. Defaults to creative_manifest.format_id if omitted.
• creative_manifest (object, required): Complete creative manifest
• inputs (array, optional): Generate variants with different macros/contexts
• output_format (string, optional): "url" (default) or "html"

Response contains:

• previews: Array of preview objects with preview_url or preview_html
• expires_at: When preview URLs expire

---

get_creative_delivery

Retrieve variant-level creative delivery data from a creative agent. Returns what was generated, served, and how each variant performed.

Request:

{
  "media_buy_ids": ["mb_abc123"],
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "max_variants": 10
}

Key fields:

• media_buy_ids (array, optional): Filter to specific media buys
• creative_ids (array, optional): Filter to specific creatives
• start_date, end_date (string, optional): Delivery period (YYYY-MM-DD)
• max_variants (integer, optional): Max variants per creative (useful for generative creatives)
• account (object, optional): Account for routing and scoping

At least one scoping filter (media_buy_ids or creative_ids) is required.

Response contains:

• creatives: Array with variant-level delivery data
  • variant_id: Unique variant identifier (use in preview_creative with request_type: "variant")
  • generation_context: What triggered this variant (page topic, device, etc.)
  • delivery_metrics: Impressions, clicks, completions
  • ext: Platform engagement metrics (likes, shares, comments)

---

Key Concepts

Format IDs

All format references use structured objects:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  }
}

The agent_url specifies the creative agent authoritative for this format.

Creative Manifests

Manifests pair format specifications with actual assets:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  },
  "assets": {
    "banner_image": {
      "asset_type": "image",
      "url": "https://cdn.example.com/banner.png",
      "width": 300,
      "height": 250
    },
    "headline": {
      "asset_type": "text",
      "content": "Shop Now"
    },
    "clickthrough_url": {
      "asset_type": "url",
      "url": "https://brand.com/sale"
    }
  }
}

Asset Types

Common asset types:

• image: Static images (JPEG, PNG, WebP)
• video: Video files (MP4, WebM) or VAST tags
• audio: Audio files (MP3, M4A) or DAAST tags
• text: Headlines, descriptions, CTAs
• html: HTML5 creatives or third-party tags
• javascript: JavaScript tags
• url: Tracking pixels, clickthrough URLs

Brand identity

For generative creatives, provide brand context by domain:

{
  "brand": {
    "domain": "acmecorp.com"
  }
}

The agent resolves the domain to retrieve the brand's identity (name, colors, guidelines, etc.) from its brand.json file.

Generative vs Transformation

• Pure Generation: Provide target_format_id, brand, and a natural language message. Creative agent generates all output assets from scratch.
• Transformation: Complete manifest with existing assets. Creative agent adapts to target format, following message guidance.

---

Error Handling

Common error patterns:

• 400 Bad Request: Invalid manifest or format_id
• 404 Not Found: Format not supported by this agent
• 422 Validation Error: Manifest doesn't match format requirements

Error responses include:

{
  "error": {
    "code": "INVALID_FORMAT_ID",
    "message": "format_id must be a structured object with 'agent_url' and 'id' fields"
  }
}