adcontextprotocol/adcp/adcp-media-buy

AdCP Media Buy Protocol

This skill enables you to execute the AdCP Media Buy Protocol with sales agents. Use the standard MCP tools (get_products, create_media_buy, sync_creatives, etc.) 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

3.2 targeting-aware discovery: These fields are available only when the

seller serves AdCP 3.2+ and the installed SDK exposes the 3.2 schema. Check

get_adcp_capabilities.adcp.supported_versions, pin the selected release in

adcp_version, and validate the echoed served release before sending them.

A missing release-precision declaration, a 3.1-or-earlier result, or a

major-only declaration is not evidence of support: omit the 3.2 fields and use

legacy targeting filters or explicit brief prose. Do not probe by sending

unknown fields because a legacy open schema may accept and ignore them. The public

training agent serves this flow at adcp_version: "3.2".

The Media Buy Protocol provides these common standardized tasks:

Typical Workflow

1. Discover products: use list_products, or request_proposals with a brief
2. Verify the offer: inspect formats, pricing, forecast, overlay_support, and any targeting_resolution
3. Negotiate and hold: revise a draft as needed, then finalize it without changing terms
4. Accept or decline: call accept_proposal for the held snapshot or decline_proposals when the buyer stops pursuing it
5. Upload creatives: use sync_creatives to add creative assets
6. Monitor delivery: use get_media_buy_delivery to track performance

Canonical formats (AdCP 3.2)

Products carry format_options[]: a list of ProductFormatDeclaration entries describing the creative shapes the product accepts. Each declaration carries:

• format_kind — one of the 15 canonicals: image, html5, display_tag, image_carousel, video_hosted, video_vast, audio_hosted, audio_vast, audio_daast, sponsored_placement, native_in_feed, responsive_creative, agent_placement, seller_rendered_stateful_display, or coordinated_placements; use custom only with format_shape and format_schema
• params — per-canonical parameters narrowing the format (dimensions, durations, codecs, char limits, CTA enums)
• Optional format_option_id — disambiguates product options and identifies publisher-catalog declarations when paired with publisher_domain
• Optional v1_format_ref: [{agent_url, id}] — array linking this v2 declaration to one or more v1 named formats (for dual emission during the v1↔v2 migration). Multi-size declarations should carry one ref per size
• Optional seller_preference: "preferred" | "accepted" | "discouraged" — soft routing hint when a multi-format product has several options at the same price

Multi-format products. A flexible publisher slot is one product with N format_options entries — e.g., Pinnacle Media's homepage accepts image OR html5 OR display_tag at multiple sizes via three format_options, one per type. Buyer picks the creative type they ship.

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

Discovering publisher catalogs. Call GET https://agenticadvertising.org/api/registry/publisher?domain=<publisher_domain> for publisher-origin → AgenticAdvertising.org community-catalog → fail-closed resolution and provenance. Add &include=placements for provenance-labeled placement summaries with resolved canonical format options. The lookup's top-level formats[] remains a lossy display summary; fetch the returned raw registry or hosting URL when you need custom schema fields or other omitted declaration fields. Do not infer publisher authority from a seller's product catalog. Seller-specific deliverability comes from that seller's Product.format_options[].

Conversion tracking lives elsewhere. Pixel-firing, conversion events, and attribution belong on sync_event_sources / event_log (campaign-scoped), NOT on creative format declarations. Sending pixel_id in platform_extensions on a format is a category error.

Error codes specific to canonical formats. FORMAT_PROJECTION_FAILED, FORMAT_DECLARATION_DIVERGENT, FORMAT_DECLARATION_V1_AMBIGUOUS, FORMAT_CAPABILITY_UNRESOLVED, FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE — all non-fatal advisories surfaced via the response errors[] array. See static/schemas/source/enums/error-code.json for full recovery semantics.

See docs/creative/canonical-formats.mdx for the full vocabulary, narrowing rules, and worked examples.

Task Reference

get_products

Discover buyable product configurations. Choose each request surface by what it means:

• brief: goals, context, semantic audience intent, preferences, and

requirements without a structured representation.

• filters: hard offer filters such as metadata, dates, budget, availability,

commercial fit, and reporting support. They decide which products may be returned and apply in brief, wholesale, and refine.

• targeting_overlay: exact delivery constraints known now. Use this for

countries, ages, placements, properties, collections, and other typed targeting so availability, price, and forecast already reflect them.

• required_overlay_support: targeting dimensions whose values will be chosen

independently on packages later. This requests capability, not one product per value.

Prefer a structured field whenever one exists. It uses fewer tokens, is applied by code, and avoids lossy inference. Explicit hard targeting written only in a brief is still binding; when a seller extracts a structured predicate from prose that materially affects eligibility, pricing, or forecasting, require one response-level confirmation in GetProductsResponse.targeting_resolution.brief_targeting.

Request:

{
  "buying_mode": "brief",
  "brief": "Premium video for a developer-tool launch; prioritize engineering and open-source contexts",
  "brand": {
    "domain": "example.com"
  },
  "filters": {
    "channels": ["olv", "ctv"],
    "delivery_type": "guaranteed",
    "pricing_currencies": ["USD"]
  },
  "targeting_overlay": {
    "geo_countries": ["US"],
    "demographics": {
      "age": { "min": 18, "max": 44, "include_unknown": false }
    }
  },
  "required_overlay_support": {
    "geo_metros": { "systems": ["nielsen_dma"] }
  }
}

Key fields:

• buying_mode (string): "brief", "wholesale", or "refine"
• brief (string): Natural-language curation input; hard statements remain requirements
• brand (object): Brand identity - { "domain": "acmecorp.com" }
• filters (object, optional): Hard offer filters that decide which products may be returned
• targeting_overlay (object, optional): Concrete targeting applied during discovery and carried into purchase
• required_overlay_support (object, optional): Dimensions the product must allow packages to select later

Response contains:

• products: Array of matching products with product_id, name, description, pricing_options
• Each product includes canonical format_options[] and targeting capabilities
• overlay_support: binding product-scoped dimensions selectable later
• targeting_resolution.modifications: sparse differences from the requested structured overlay; selecting the product accepts them
• Response targeting_resolution.brief_targeting: the seller's single structured interpretation of hard targeting inferred from prose
• No targeting_resolution means exact acceptance of the structured overlay only; it does not prove how prose was interpreted

Treat product_id as the opaque identity of this configured offer. Keep it within the same discovery/refinement context and purchase it before expires_at; do not assume it is a permanent cross-session ID.

create_media_buy

Create an advertising campaign from selected products.

Request:

{
  "brand": {
    "domain": "acme.com"
  },
  "packages": [
    {
      "product_id": "prod_configured_us_18_44",
      "pricing_option_id": "cpm-standard",
      "budget": 10000,
      "targeting_overlay": {
        "geo_metros": [
          { "system": "nielsen_dma", "values": ["501"] }
        ]
      }
    }
  ],
  "start_time": "asap",
  "end_time": "2024-03-31T23:59:59Z"
}

Key fields:

• brand (object, required): Brand identity - { "domain": "acmecorp.com" }
• packages (array, required): Products to purchase, each with:
• product_id: From get_products response
• pricing_option_id: From product's pricing_options
• budget: Amount in dollars
• bid_price: Required for auction pricing
• targeting_overlay: Package targeting permitted by the selected product's overlay_support; it composes with targeting already bound during discovery and must not silently broaden it
• creative_ids or creatives: Creative assignments
• start_time (string, required): "asap" or an ISO 8601 datetime (e.g., "2024-06-01T00:00:00Z")
• end_time (string, required): ISO 8601 datetime

Response contains:

• media_buy_id: The created campaign identifier
• status: Current lifecycle state — pending_creatives (no creatives assigned yet), pending_start (creatives in place, not yet serving: waiting for the flight date, or for seller confirmation when confirmed_at is null), or active (serving immediately)
• packages: Created packages with their IDs

update_media_buy

Modify an existing campaign.

Request:

{
  "idempotency_key": "update-mb-abc123-2024-04-pause",
  "media_buy_id": "mb_abc123",
  "updates": {
    "budget_change": 5000,
    "end_time": "2024-04-30T23:59:59Z",
    "status": "paused"
  }
}

Key fields:

• media_buy_id (string, required): The campaign to update
• updates (object): Changes to apply - budget_change, end_time, status, targeting, etc.

sync_catalogs

Sync product catalogs, store locations, job postings, and other structured feeds to a seller account. Supports inline items or external feed URLs. When called without catalogs, returns existing catalogs (discovery mode).

Request: