adcp-creative

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:

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

---

Canonical formats (AdCP 3.1+)

Products and manifests use the canonical-formats vocabulary — 11 canonical format_kind values that name the underlying creative shape (image / html5 / display_tag / video_hosted / video_vast / audio_hosted / audio_daast / image_carousel / responsive_creative / sponsored_placement / agent_placement / custom).

A ProductFormatDeclaration carries:

• format_kind: the canonical (discriminator)
• params: per-canonical parameters narrowing the format (dimensions, durations, codecs, char limits, CTA enums, sizes[], etc.)
• Optional capability_id: stable identifier for routing when a product carries multiple declarations of the same kind
• Optional v1_format_ref: [{agent_url, id}]: always an array — links this v2 declaration to one or more v1 named formats. Multi-size declarations should carry one ref per size in sizes[].
• Optional seller_preference: "preferred" | "accepted" | "discouraged": soft routing hint when a product carries multiple format_options

Where to declare a format:

Size flexibility (image / html5 / display_tag): exactly one of three modes — width+height (fixed), sizes: [{w,h}] (multi-size, mirrors OpenRTB banner.format[]), or min_width/max_width/min_height/max_height (responsive).

Community mirror for unadopted platforms: the AAO publishes adagents.json files for unadopted platforms (Meta, TikTok, etc.) at https://creative.adcontextprotocol.org/translated/<platform>/adagents.json. When the request asks "what formats does meta.com support?" the SDK fetches the platform's hosted file first, falls back to the AAO mirror, and surfaces which tier produced the result via the response's source field.

Conversion tracking is NOT a creative-format concern. Pixel-firing, conversion events, and attribution belong on sync_event_sources / event_log (campaign-scoped). Don't stuff pixel_id into platform_extensions on a format declaration.

See docs/creative/canonical-formats.mdx for the full vocabulary, narrowing rules, error-code surface, and worked examples (Meta Reels, IAB display, host-read podcast, generative DSP).

---

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"
  }
}