// Execute AdCP Media Buy Protocol operations with sales agents - discover advertising products, create and manage campaigns, sync creatives, and track delivery. Use when users want to buy advertising, create media buys, interact with ad sales agents, or test advertising APIs.
Execute AdCP Creative Protocol operations with creative agents - build creatives from briefs or existing assets, preview renderings, and discover format specifications. Use when users want to generate or transform ad creatives, preview how ads will look, or understand creative format requirements.
Wire-level invariants for any AdCP buyer call — idempotency_key replay semantics, account `oneOf` variants, async `status:'submitted'`+`task_id` polling, error recovery from `adcp_error.issues[]`. Load before any per-protocol task skill (adcp-media-buy, adcp-creative, adcp-signals, adcp-governance, adcp-si, adcp-brand) when calling an AdCP agent as a buyer.
Execute AdCP Brand Protocol operations with brand agents - get brand identity data, search for licensable rights, acquire rights for campaigns, and manage existing grants. Use when users want to look up brand identities, find talent or IP for licensing, or manage rights grants.
Execute AdCP Governance Protocol operations with governance agents - manage property lists, collection lists, content standards, and campaign governance (plans, checks, outcomes, audit trail). Use when users want to create include/exclude lists, set up brand safety rules, validate content delivery, register campaign plans, validate actions against policy, or produce internal/shareable audit trails.
Execute AdCP Sponsored Intelligence (SI) Protocol operations with brand agents - start conversational sessions, send messages, preview offerings, and manage session lifecycle. Use when users want to have conversations with brand agents, explore product offerings, or manage sponsored interactions.
Execute AdCP Signals Protocol operations with signal agents - discover audience signals using natural language and activate them on DSPs or sales agents. Use when users want to find targeting data, activate audience segments, or work with signal providers.
| name | adcp-media-buy |
| description | Execute AdCP Media Buy Protocol operations with sales agents - discover advertising products, create and manage campaigns, sync creatives, and track delivery. Use when users want to buy advertising, create media buys, interact with ad sales agents, or test advertising APIs. |
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,
oneOfvariants, asyncstatus:'submitted'polling, error recovery fromadcp_error.issues[]— live inskills/call-adcp-agent/SKILL.md. This skill covers per-task semantics only.
The Media Buy Protocol provides 11 standardized tasks for managing advertising campaigns:
| Task | Purpose | Response Time |
|---|---|---|
get_products | Discover inventory using natural language | ~60s |
get_adcp_capabilities | See agent capabilities, supported protocols, and publisher properties | ~1s |
list_creative_formats | View creative specifications | ~1s |
create_media_buy | Create campaigns | Minutes-Days |
update_media_buy | Modify campaigns | Minutes-Days |
get_media_buys | Retrieve campaign state and status | ~1-5s |
sync_creatives | Upload creative assets | Minutes-Days |
sync_catalogs | Sync product feeds and catalogs | Minutes-Days |
list_creatives | Query creative library | ~1s |
get_media_buy_delivery | Get performance data | ~60s |
provide_performance_feedback | Share outcomes with publishers | ~1-5s |
get_products with a natural language brieflist_creative_formats to understand creative requirementscreate_media_buy with selected products and budgetsync_creatives to add creative assetsget_media_buy_delivery to track performanceProducts carry format_options[]: a list of ProductFormatDeclaration entries describing the creative shapes the product accepts. Each declaration carries:
format_kind — canonical type (image / html5 / display_tag / video_hosted / video_vast / audio_hosted / audio_daast / image_carousel / responsive_creative / sponsored_placement / agent_placement / custom)params — per-canonical parameters narrowing the format (dimensions, durations, codecs, char limits, CTA enums)capability_id — disambiguates when a product carries multiple declarations of the same format_kind, and lets a placement reference a publisher-catalog declaration by ID rather than inliningv1_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 sizeseller_preference: "preferred" | "accepted" | "discouraged" — soft routing hint when a multi-format product has several options at the same priceMulti-format products. A flexible publisher slot is one product with N format_options entries — e.g., NYTimes 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. list_creative_formats(publisher_domain="meta.com") returns the publisher's authoritative format list by reading <publisher_domain>/.well-known/adagents.json formats[], falling back to the AAO community mirror at https://creative.adcontextprotocol.org/translated/<platform>/adagents.json, then to agent-derived from own products. Response carries source: "publisher" | "aao_mirror" | "agent_derived" so buyers know which tier produced the list.
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.
Discover advertising products using natural language briefs.
Request:
{
"buying_mode": "brief",
"brief": "Looking for premium video inventory for a tech brand targeting developers",
"brand": {
"domain": "example.com"
},
"filters": {
"channels": ["video", "ctv"],
"budget_range": { "min": 5000, "max": 50000 }
}
}
Key fields:
buying_mode (string): Required discriminator - "brief" or "wholesale"brief (string): Natural language description of campaign requirementsbrand (object): Brand identity - { "domain": "acmecorp.com" }filters (object, optional): Filter by channels, budget, delivery_typeResponse contains:
products: Array of matching products with product_id, name, description, pricing_optionsformat_ids (supported creative formats) and targeting (available targeting)View supported creative specifications.
Request:
{
"asset_types": ["video", "image"]
}
Key fields:
asset_types (array, optional): Filter by asset types (image, video, audio, text, html, vast, etc.)name_search (string, optional): Case-insensitive partial match on name or descriptionResponse contains:
formats: Array of format specifications with dimensions, requirements, and asset schemasCreate an advertising campaign from selected products.
Request:
{
"brand": {
"domain": "acme.com"
},
"packages": [
{
"product_id": "premium_video_30s",
"pricing_option_id": "cpm-standard",
"budget": 10000
}
],
"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 responsepricing_option_id: From product's pricing_optionsbudget: Amount in dollarsbid_price: Required for auction pricingtargeting_overlay: Additional targeting constraintscreative_ids or creatives: Creative assignmentsstart_time (string, required): "asap" or an ISO 8601 datetime (e.g., "2024-06-01T00:00:00Z")end_time (string, required): ISO 8601 datetimeResponse contains:
media_buy_id: The created campaign identifierstatus: Current lifecycle state — pending_creatives (no creatives assigned yet), pending_start (waiting for flight date), or active (serving immediately)packages: Created packages with their IDsModify an existing campaign.
Request:
{
"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 updateupdates (object): Changes to apply - budget_change, end_time, status, targeting, etc.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:
{
"account": {
"account_id": "acct_123"
},
"catalogs": [
{
"catalog_id": "winter-collection",
"name": "Winter 2025 Collection",
"type": "product",
"items": [
{ "id": "sku-001", "name": "Wool Coat", "price": 299.99, "currency": "USD" }
]
}
]
}
Key fields:
account (object, required): Account that owns the catalogs — { account_id }catalogs (array, optional): Catalog objects to sync. Omit for discovery mode.
type (string, required): offering, product, inventory, store, promotion, hotel, flight, job, vehicle, real_estate, education, destination, appitems (array): Inline catalog data (mutually exclusive with url)url (string): External feed URL (mutually exclusive with items)feed_format (string): google_merchant_center, facebook_catalog, shopify, linkedin_jobs, customdelete_missing (boolean, optional): Remove catalogs not in this sync (use with caution)dry_run (boolean, optional): Preview changes without applyingUpload and manage creative assets.
Request:
{
"creatives": [
{
"creative_id": "hero_video_30s",
"name": "Brand Hero Video",
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "video_standard_30s"
},
"assets": {
"video": {
"url": "https://cdn.example.com/hero.mp4",
"width": 1920,
"height": 1080,
"duration_ms": 30000
}
}
}
],
"assignments": {
"hero_video_30s": ["pkg_001", "pkg_002"]
}
}
Key fields:
creatives (array, required): Creative assets to sync
creative_id: Your unique identifierformat_id: Object with agent_url and id from format specificationsassets: Asset content (video, image, html, etc.)assignments (object, optional): Map creative_id to package IDsdry_run (boolean): Preview changes without applyingdelete_missing (boolean): Archive creatives not in this syncQuery the creative library with filtering.
Request:
{
"filters": {
"status": ["active"]
},
"limit": 20
}
Retrieve media buy state: status, valid_actions, creative approvals, pending formats, and optional delivery snapshots or revision history.
Request:
{
"media_buy_ids": ["mb_abc123"],
"include_snapshot": true,
"include_history": 5
}
Key fields:
media_buy_ids (array, optional): Specific media buy IDs to retrieveaccount (object, optional): Filter to a specific accountstatus_filter (string or array, optional): Filter by status — pending_creatives, pending_start, active, paused, completed, rejected, canceled. Defaults to ["active"] when no IDs provided.include_snapshot (boolean, optional): Include near-real-time delivery snapshots per packageinclude_history (integer, optional): Include the last N revision history entries per media buyResponse contains:
media_buys: Array with media_buy_id, status, valid_actions, packages, creative approval statesnapshot per package (impressions, spend, pacing)history entries (revision, timestamp, actor, action, summary)Share performance outcomes with publishers to enable data-driven optimization.
Request:
{
"media_buy_id": "mb_abc123",
"measurement_period": {
"start": "2025-01-01T00:00:00Z",
"end": "2025-01-31T23:59:59Z"
},
"performance_index": 1.2,
"metric_type": "conversion_rate",
"feedback_source": "buyer_attribution"
}
Key fields:
media_buy_id (string, required): Publisher's media buy identifiermeasurement_period (object, required): Time period with start and end (ISO 8601)performance_index (number, required): Normalized score — 0.0 = no value, 1.0 = expected, >1.0 = above expectedpackage_id (string, optional): Specific package for package-level feedbackcreative_id (string, optional): Specific creative for creative-level feedbackmetric_type (string, optional): overall_performance, conversion_rate, brand_lift, click_through_rate, completion_rate, viewability, brand_safety, cost_efficiencyfeedback_source (string, optional): buyer_attribution, third_party_measurement, platform_analytics, verification_partnerRetrieve performance metrics for a campaign.
Request:
{
"media_buy_id": "mb_abc123",
"granularity": "daily",
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
}
Response contains:
delivery: Aggregated metrics (impressions, spend, clicks, etc.)by_package: Breakdown by packagetimeseries: Data points over time if granularity specifiedBrand context is provided by domain reference:
{
"brand": {
"domain": "acmecorp.com"
}
}
The agent resolves the domain to retrieve the brand's identity (name, colors, guidelines, etc.) from its brand.json file.
Creative format identifiers are structured objects:
{
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
}
}
The agent_url specifies which creative agent defines the format. Use https://creative.adcontextprotocol.org for standard IAB formats.
Products include pricing_options array. Each option has:
pricing_option_id: Use this in create_media_buypricing_model: "cpm", "cpm-auction", "flat-fee", etc.price: Base price (for fixed pricing)floor: Minimum bid (for auction)For auction pricing, include bid_price in your package.
Operations like create_media_buy and sync_creatives may require human approval. The response includes:
status: "pending" - Operation awaiting approvaltask_id - For tracking async progressPoll or use webhooks to check completion status.
Common error patterns:
Error responses include:
{
"errors": [
{
"code": "VALIDATION_ERROR",
"message": "budget must be greater than 0",
"field": "packages[0].budget"
}
]
}
Use sandbox mode for testing without real transactions. Sandbox is account-level — once a request references a sandbox account, the entire request is treated as sandbox with no real platform calls or spend.
Check whether the agent supports sandbox via get_adcp_capabilities:
{
"account": {
"sandbox": true
}
}
To enter sandbox mode, set sandbox: true on the account reference:
{
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
}
}
Some sync tasks (sync_creatives, sync_catalogs) also support a dry_run parameter that previews changes without applying them. This is orthogonal to sandbox — you can use dry_run in both sandbox and production accounts.
See Sandbox mode for full details.