adcp-media-buy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能可让你与销售代理商执行AdCP Media Buy Protocol操作。使用已连接代理商提供的标准MCP工具（

get_products

、

create_media_buy

、

sync_creatives

等）。

Overview

概述

The Media Buy Protocol provides 8 standardized tasks for managing advertising campaigns:

Task	Purpose	Response Time
`get_products`	Discover inventory using natural language	~60s
`list_authorized_properties`	See publisher properties	~1s
`list_creative_formats`	View creative specifications	~1s
`create_media_buy`	Create campaigns	Minutes-Days
`update_media_buy`	Modify campaigns	Minutes-Days
`sync_creatives`	Upload creative assets	Minutes-Days
`list_creatives`	Query creative library	~1s
`get_media_buy_delivery`	Get performance data	~60s

Media Buy Protocol提供8项标准化任务用于管理广告活动：

任务	用途	响应时间
`get_products`	通过自然语言发现广告库存	~60s
`list_authorized_properties`	查看出版商可售资源	~1s
`list_creative_formats`	查看创意素材规格	~1s
`create_media_buy`	创建广告活动	数分钟至数天
`update_media_buy`	修改广告活动	数分钟至数天
`sync_creatives`	上传创意素材资源	数分钟至数天
`list_creatives`	查询创意素材库	~1s
`get_media_buy_delivery`	获取投放效果数据	~60s

Typical Workflow

典型工作流程

Discover products:
```
get_products
```
with a natural language brief
Review formats:
```
list_creative_formats
```
to understand creative requirements
Create campaign:
```
create_media_buy
```
with selected products and budget
Upload creatives:
```
sync_creatives
```
to add creative assets
Monitor delivery:
```
get_media_buy_delivery
```
to track performance

发现产品：使用自然语言描述调用
```
get_products
```
查看格式：调用
```
list_creative_formats
```
了解创意素材要求
创建活动：结合选定产品和预算调用
```
create_media_buy
```
上传创意素材：调用
```
sync_creatives
```
添加创意素材资源
监控投放：调用
```
get_media_buy_delivery
```
追踪投放效果

Task Reference

任务参考

get_products

Discover advertising products using natural language briefs.

Request:

json

{
  "brief": "Looking for premium video inventory for a tech brand targeting developers",
  "brand_manifest": {
    "url": "https://example.com"
  },
  "filters": {
    "channels": ["video", "ctv"],
    "budget_range": { "min": 5000, "max": 50000 }
  }
}

Key fields:

```
brief
```
(string): Natural language description of campaign requirements
```
brand_manifest
```
(object): Brand context - can be
```
{ "url": "https://..." }
```
or inline manifest
```
filters
```
(object, optional): Filter by channels, budget, delivery_type, format_types

Response contains:

products

: Array of matching products with

product_id

name

description

pricing_options

Each product includes
```
format_ids
```
(supported creative formats) and
```
targeting
```
(available targeting)

通过自然语言描述发现广告产品。

请求：

json

{
  "brief": "Looking for premium video inventory for a tech brand targeting developers",
  "brand_manifest": {
    "url": "https://example.com"
  },
  "filters": {
    "channels": ["video", "ctv"],
    "budget_range": { "min": 5000, "max": 50000 }
  }
}

关键字段：

```
brief
```
（字符串）：广告活动需求的自然语言描述
```
brand_manifest
```
（对象）：品牌上下文信息 - 可以是
```
{ "url": "https://..." }
```
或内联清单
```
filters
```
（对象，可选）：按渠道、预算、投放类型、格式类型筛选

响应包含：

products

：匹配产品数组，包含

product_id

、

name

、

description

、

pricing_options

每个产品包含
```
format_ids
```
（支持的创意素材格式）和
```
targeting
```
（可用定向选项）

list_authorized_properties

Get the list of publisher properties this agent can sell.

Request:

json

{}

No parameters required.

Response contains:

```
publisher_domains
```
: Array of domain strings the agent is authorized to sell

获取该代理商可销售的出版商资源列表。

请求：

json

{}

无需参数。

响应包含：

```
publisher_domains
```
：代理商有权销售的域名字符串数组

list_creative_formats

View supported creative specifications.

Request:

json

{
  "format_types": ["video", "display"]
}

Key fields:

```
format_types
```
(array, optional): Filter to specific format categories

Response contains:

```
formats
```
: Array of format specifications with dimensions, requirements, and asset schemas

查看支持的创意素材规格。

请求：

json

{
  "format_types": ["video", "display"]
}

关键字段：

```
format_types
```
（数组，可选）：筛选特定格式类别

响应包含：

```
formats
```
：格式规格数组，包含尺寸、要求和资源架构

create_media_buy

Create an advertising campaign from selected products.

Request:

json

{
  "buyer_ref": "campaign-2024-q1-001",
  "brand_manifest": {
    "url": "https://acme.com",
    "name": "Acme Corporation"
  },
  "packages": [
    {
      "buyer_ref": "pkg-video-001",
      "product_id": "premium_video_30s",
      "pricing_option_id": "cpm-standard",
      "budget": 10000
    }
  ],
  "start_time": {
    "type": "asap"
  },
  "end_time": "2024-03-31T23:59:59Z"
}

Key fields:

```
buyer_ref
```
(string, required): Your unique identifier for this campaign
```
brand_manifest
```
(object, required): Brand identity - URL or inline manifest
```
packages
```
(array, required): Products to purchase, each with:
- ```
buyer_ref
```
  : Your identifier for this package
- ```
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
```
  : Additional targeting constraints
- ```
creative_ids
```
  or
```
creatives
```
  : Creative assignments

start_time

(object, required):

{ "type": "asap" }

{ "type": "scheduled", "datetime": "..." }

```
end_time
```
(string, required): ISO 8601 datetime

Response contains:

```
media_buy_id
```
: The created campaign identifier
```
status
```
: Current state (often
```
pending
```
for async approval)
```
packages
```
: Created packages with their IDs

从选定产品创建广告活动。

请求：

json

{
  "buyer_ref": "campaign-2024-q1-001",
  "brand_manifest": {
    "url": "https://acme.com",
    "name": "Acme Corporation"
  },
  "packages": [
    {
      "buyer_ref": "pkg-video-001",
      "product_id": "premium_video_30s",
      "pricing_option_id": "cpm-standard",
      "budget": 10000
    }
  ],
  "start_time": {
    "type": "asap"
  },
  "end_time": "2024-03-31T23:59:59Z"
}

关键字段：

```
buyer_ref
```
（字符串，必填）：你为该活动设置的唯一标识符
```
brand_manifest
```
（对象，必填）：品牌身份信息 - URL或内联清单
```
packages
```
（数组，必填）：要采购的产品，每个包含：
- ```
buyer_ref
```
  ：你为该套餐设置的标识符
- ```
product_id
```
  ：来自
```
get_products
```
  响应
- ```
pricing_option_id
```
  ：来自产品的
```
pricing_options
```
- ```
budget
```
  ：金额（美元）
- ```
bid_price
```
  ：拍卖定价时必填
- ```
targeting_overlay
```
  ：额外定向限制
- ```
creative_ids
```
  或
```
creatives
```
  ：创意素材分配

start_time

（对象，必填）：

{ "type": "asap" }

或

{ "type": "scheduled", "datetime": "..." }

```
end_time
```
（字符串，必填）：ISO 8601格式的日期时间

响应包含：

```
media_buy_id
```
：已创建活动的标识符
```
status
```
：当前状态（异步审批时通常为
```
pending
```
）
```
packages
```
：已创建套餐及其ID

update_media_buy

Modify an existing campaign.

Request:

json

{
  "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.

修改现有广告活动。

请求：

json

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

关键字段：

```
media_buy_id
```
（字符串，必填）：要修改的活动ID
```
updates
```
（对象）：要应用的更改 - 预算调整、结束时间、状态、定向等

sync_creatives

Upload and manage creative assets.

Request:

json

{
  "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 identifier
- ```
format_id
```
  : Object with
```
agent_url
```
  and
```
id
```
  from format specifications
- ```
assets
```
  : Asset content (video, image, html, etc.)
```
assignments
```
(object, optional): Map creative_id to package IDs
```
dry_run
```
(boolean): Preview changes without applying
```
delete_missing
```
(boolean): Archive creatives not in this sync

上传并管理创意素材资源。

请求：

json

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

关键字段：

```
creatives
```
（数组，必填）：要同步的创意素材资源
- ```
creative_id
```
  ：你的唯一标识符
- ```
format_id
```
  ：包含来自格式规格的
```
agent_url
```
  和
```
id
```
  的对象
- ```
assets
```
  ：素材内容（视频、图片、HTML等）
```
assignments
```
（对象，可选）：将creative_id映射到套餐ID
```
dry_run
```
（布尔值）：预览更改而不实际应用
```
delete_missing
```
（布尔值）：归档未在本次同步中包含的创意素材

list_creatives

Query the creative library with filtering.

Request:

json

{
  "filters": {
    "status": ["active"],
    "format_types": ["video"]
  },
  "limit": 20
}

带筛选条件查询创意素材库。

请求：

json

{
  "filters": {
    "status": ["active"],
    "format_types": ["video"]
  },
  "limit": 20
}

get_media_buy_delivery

Retrieve performance metrics for a campaign.

Request:

json

{
  "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 package
```
timeseries
```
: Data points over time if granularity specified

获取广告活动的投放效果指标。

请求：

json

{
  "media_buy_id": "mb_abc123",
  "granularity": "daily",
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

响应包含：

```
delivery
```
：汇总指标（曝光量、花费、点击量等）
```
by_package
```
：按套餐细分的数据
```
timeseries
```
：若指定了粒度，返回随时间变化的数据点

Key Concepts

关键概念

Brand Manifest

品牌清单（Brand Manifest）

Brand context can be provided in two ways:

URL reference (recommended):

json

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

Inline manifest:

json

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

品牌上下文信息可通过两种方式提供：

URL引用（推荐）：

json

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

内联清单：

json

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

Format IDs

格式ID（Format IDs）

Creative format identifiers are structured objects:

json

{
  "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.

创意素材格式标识符为结构化对象：

json

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

agent_url

指定定义该格式的创意代理商。标准IAB格式使用

https://creative.adcontextprotocol.org

。

Pricing Options

定价选项（Pricing Options）

Products include

pricing_options

array. Each option has:

```
pricing_option_id
```
: Use this in
```
create_media_buy
```
```
pricing_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.

产品包含

pricing_options

数组。每个选项包含：

```
pricing_option_id
```
：在
```
create_media_buy
```
中使用
```
pricing_model
```
："cpm"、"cpm-auction"、"flat-fee"等
```
price
```
：基础价格（固定定价时）
```
floor
```
：最低出价（拍卖时）

拍卖定价时，需在套餐中包含

bid_price

。

Asynchronous Operations

异步操作

Operations like

create_media_buy

and

sync_creatives

may require human approval. The response includes:

```
status: "pending"
```
- Operation awaiting approval
```
task_id
```
- For tracking async progress

Poll or use webhooks to check completion status.

create_media_buy

和

sync_creatives

等操作可能需要人工审批。响应包含：

```
status: "pending"
```
- 操作等待审批
```
task_id
```
- 用于追踪异步进度

可通过轮询或webhooks检查完成状态。

Error Handling

错误处理

Common error patterns:

400 Bad Request: Invalid parameters - check required fields
401 Unauthorized: Invalid or missing authentication token
404 Not Found: Invalid product_id, media_buy_id, or creative_id
422 Validation Error: Schema validation failure - check field types

Error responses include:

json

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

常见错误类型：

400 Bad Request：参数无效 - 检查必填字段
401 Unauthorized：身份验证令牌无效或缺失
404 Not Found：product_id、media_buy_id或creative_id无效
422 Validation Error：架构验证失败 - 检查字段类型

错误响应示例：

json

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

Testing Mode

测试模式

For testing without real transactions, agents may support:

```
X-Dry-Run: true
```
header - Preview without side effects
Test products with
```
test: true
```
flag
Sandbox environments

Ask the agent about testing capabilities before creating real campaigns.

为了在不产生真实交易的情况下进行测试，代理商可能支持：

```
X-Dry-Run: true
```
请求头 - 预览操作无实际影响
带有
```
test: true
```
标记的测试产品
沙箱环境

创建真实活动前，可咨询代理商的测试功能。