feat: creative library protocol — list_creatives, sync_creatives, library retrieval, platform mapping

[bokelley]

Summary

• Move list_creatives and sync_creatives from media-buy to creative protocol — all creative library operations now live in one protocol. Any agent hosting a creative library implements the creative protocol for both reads and writes.
• Extend build_creative with library retrieval mode — creative_id + target_format_id + optional macro_values returns a manifest with ad-serving tags as assets. Supports both creative-level tags (Flashtalking, Celtra) and placement-level tags (CM360 via media_buy_id/package_id).
• Add creative agent interaction models — supports_generation, supports_transformation, has_creative_library capability flags in get_adcp_capabilities so buyers can determine how to interact with a creative agent.
• New creative-variable.json schema for DCO variable definitions with type support (text, image, video, color, etc.)
• Platform mapping guide for implementers wrapping existing ad servers (Flashtalking, CM360, Celtra)
• Universal macro handling — callers always use universal macro names; creative agent translates to platform syntax

Test plan

• All 323 tests pass (npm test)
• OpenAPI spec up to date
• TypeScript typecheck passes
• No broken links (Mintlify validation)
• Schema examples validate against their schemas
• No stale media-buy/sync-creatives or media-buy/list-creatives references in source files
• Redirects in place for moved doc pages
• Expert reviews: code reviewer, ad tech protocol expert, docs expert

🤖 Generated with Claude Code

[bokelley]

Spec feedback from proxy agent analysis

Analyzed Flashtalking (full OpenAPI spec), Celtra (alpha REST API), CM360 (Google REST v5), and Innovid (limited public docs) against this PR to assess what works for building proxy agents.

1. Rename library_id → concept_id

Across platforms, the browsable creative grouping is not the top-level workspace:

Platform	Workspace (= accounts protocol)	Browsable grouping (= this field)
Flashtalking	CreativeLibrary (advertiser, brand, mediaBuyer)	Concept (theme across sizes)
Celtra	Account	Campaign folder
CM360	Advertiser	CreativeGroup

The workspace/account is already handled by the accounts protocol (sync_accounts/list_accounts). What buyers browse is the creative concept — an industry-standard term for a cohesive creative idea across sizes/formats.

Changes: Rename library_id → concept_id, library_name → concept_name, library_ids → concept_ids in filters, "library" → "concept" in fields enum. Keep has_creative_library capability name as-is (describes the feature).

2. Add media_buy_id + package_id to build_creative

Most creative agents (Flashtalking, Celtra, Innovid) generate tags at the creative level — no trafficking context needed. But CM360 generates tags at the placement level. When the creative agent is also the ad server, it needs to know which placement the tag is for.

"media_buy_id": {
  "type": "string",
  "description": "Media buy or placement identifier for tag generation. When the creative agent is also the ad server, this provides the trafficking context needed to generate placement-specific tags (e.g., CM360 placement ID). Not needed when tags are generated at the creative level (most creative platforms)."
},
"package_id": {
  "type": "string",
  "description": "Package or line item within the media buy. Used with media_buy_id when the creative agent needs line-item-level context for tag generation."
}

Both are optional strings. Only CM360-style platforms (where creative + trafficking coexist) need them today.

3. Do NOT add html to variable_type — richloads are formats, not variables

Flashtalking's "Richload" variables look like HTML slots, but they're actually asset references (assetId in VersionVariable). Passing raw HTML between agents would be platform-specific.

• Variable types should stay semantic and agent-producible: text, image, video, audio, url, number, boolean, color
• Richload/HTML5 packages are creative formats, not variable values → formal format spec (separate work)
• FT richload variable slots map to image or video in AdCP (asset references) or aren't exposed as variables

Platform readiness for proxy agents

Platform	list_creatives	build_creative (library retrieval)	DCO variables	Build now?
Flashtalking	GET /creative-libraries/{id}/creatives	s3publish at version level	GET /creatives/{id}/variables (Text, Image, Video, Audio)	Yes
Celtra	Gap — no list endpoint for created creatives	GET /tags with universal macros	Template object properties	Yes, with caveats
CM360	creatives.list (excellent filtering)	Needs media_buy_id (placement-level tags)	dynamicFeeds (lossy mapping)	Yes, after spec tweak
Innovid	No public API	No public API	No public API	Blocked — need API partnership

[bokelley]

Follow-up: sync_creatives on creative protocol + buyer_ref as the creative handle

After further analysis of the end-to-end workflow across Flashtalking, Celtra, and CM360, we think sync_creatives belongs on the creative protocol too — not just media-buy. Here's the reasoning.

The full workflow

1. sync_creatives → creative agent (FT/CM360/Celtra)
   "Here are my assets. Host them for ad serving."
   Each creative_manifest carries buyer_ref, concept_id, assets.

2. list_creatives ← creative agent
   "What's in my library?" Filter by concept_ids, formats, variables.

3. build_creative → creative agent
   creative_id: "abcd"  ← same buyer_ref from step 1
   target_format_id, macro_values
   "Give me a tag for this creative with universal macros resolved."

4. sync_creatives → sales agent (DV360/TTD/Snap)
   "Here are the tagged creatives for this media buy."
   Now carries the tag output from step 3.

5. create_media_buy → sales agent
   "Traffic it."

Why this works

sync_creatives is "push creatives to an agent." The receiving agent's role determines what happens:

• Creative agent receives it → ingests assets, organizes by concept_id, makes them available for list_creatives and build_creative
• Sales agent receives it → associates creatives with media buys/packages for trafficking

The schema is the same creative manifest in both cases. No new task needed — just add sync_creatives to the creative protocol task list.

buyer_ref is the stable handle

The buyer sends sync_creatives with buyer_ref: "abcd" on the creative manifest. Later, build_creative(creative_id: "abcd") resolves that same ref. The creative agent maintains the mapping to its internal ID. list_creatives returns both the platform's creative_id and the buyer_ref if one was provided during sync.

This matches how buyer_ref already works in the media-buy protocol — it's the buyer's stable identifier for anything they've synced.

Concepts are just grouping labels

No separate concept CRUD needed. When the buyer sends sync_creatives with concept_id: "holiday_2026" on a creative, the creative agent files it accordingly — auto-creating the concept if it doesn't exist. list_creatives with concept_ids filter handles discovery. Concepts map to platform-specific groupings:

Platform	concept_id maps to	Auto-created on sync?
Flashtalking	conceptId	Yes — FT creates concepts when creatives are assigned
Celtra	campaignFolderId	Yes — POST /campaigns
CM360	creativeGroupId	Implicit from creative metadata

What changes in this PR

1. Add sync_creatives to creative protocol task list in docs.json, specification.mdx, and the task reference
2. Schema reuse — the existing sync-creatives-request.json / sync-creatives-response.json work as-is. The creative manifest already carries buyer_ref, format_id, and assets. Adding concept_id to the manifest (or using ext) handles the grouping.
3. Document the buyer_ref → creative_id resolution in build_creative docs — when creative_id matches a previously synced buyer_ref, the agent resolves it from its library.

Platform mapping for sync_creatives → creative agent

Platform	Asset ingestion	Creative creation	Concept assignment
Flashtalking	POST /images/upload, POST /videos/upload	POST /creative-libraries/{id}/creatives	POST /concepts/with-assets
Celtra	POST /assets (base64)	POST /creatives (from template)	POST /campaigns
CM360	creativeAssets.insert (multipart)	creatives.insert	Creative group metadata

[simonsafhalterceltra]

Celtra | Gap — no list endpoint for created creatives
We recently made our build_creative async since it can take some time to produce creatives.
As a consequence we added a new task get_build_creative_result where the input is a task_id returned from build_creative. We could rename this to list_creatives if that fits the purpose?

[bokelley]

@simonsafhalterceltra Great question — you don't need a separate get_build_creative_result task. AdCP handles this at the transport layer.

How async works in AdCP: Any task (including build_creative) can return a working status instead of completed. The caller polls for updates using the context_id from the response — this is built into the MCP and A2A transports. There's no need for a task-specific polling endpoint because the protocol already provides a generic one.

The flow looks like:

1. Caller sends build_creative request
2. Agent returns { "status": "working", "message": "Generating creative...", "context_id": "ctx-abc" }
3. Caller polls context_id for updates (or receives a webhook if push_notification_config was provided)
4. Agent eventually returns { "status": "completed", "creative_manifest": { ... } }

This is documented in the Task Lifecycle and Async Operations guides.

On list_creatives: This serves a different purpose — it's for browsing/querying an existing creative library (filtering by status, format, concept, tags, etc.), not for retrieving the result of a build. If Celtra maintains a library of created creatives that buyers should be able to browse, then list_creatives is the right fit. If creatives are only produced on-demand via build_creative, you wouldn't need list_creatives at all — the async response from build_creative already returns the manifest.

[simonsafhalterceltra]

@simonsafhalterceltra Great question — you don't need a separate get_build_creative_result task. AdCP handles this at the transport layer.

How async works in AdCP: Any task (including build_creative) can return a working status instead of completed. The caller polls for updates using the context_id from the response — this is built into the MCP and A2A transports. There's no need for a task-specific polling endpoint because the protocol already provides a generic one.

The flow looks like:

1. Caller sends build_creative request
2. Agent returns { "status": "working", "message": "Generating creative...", "context_id": "ctx-abc" }
3. Caller polls context_id for updates (or receives a webhook if push_notification_config was provided)
4. Agent eventually returns { "status": "completed", "creative_manifest": { ... } }

This is documented in the Task Lifecycle and Async Operations guides.

On list_creatives: This serves a different purpose — it's for browsing/querying an existing creative library (filtering by status, format, concept, tags, etc.), not for retrieving the result of a build. If Celtra maintains a library of created creatives that buyers should be able to browse, then list_creatives is the right fit. If creatives are only produced on-demand via build_creative, you wouldn't need list_creatives at all — the async response from build_creative already returns the manifest.

Thank you, the first section makes sense.

I have a follow up question about the second part: list_creatives vs list_creative_formats
At Celtra at the moment our Creative Formats are actually templates that users can browse, they are reusable across campaigns so users can replace various components with their own, but also creatives that users can see.

Would in this case list_creative_formats just return the format IDs, and list_creatives the same formats on a public link where the user can browser and see them?

[bokelley]

@simonsafhalterceltra Great question — you don't need a separate get_build_creative_result task. AdCP handles this at the transport layer.
How async works in AdCP: Any task (including build_creative) can return a working status instead of completed. The caller polls for updates using the context_id from the response — this is built into the MCP and A2A transports. There's no need for a task-specific polling endpoint because the protocol already provides a generic one.
The flow looks like:

1. Caller sends build_creative request
2. Agent returns { "status": "working", "message": "Generating creative...", "context_id": "ctx-abc" }
3. Caller polls context_id for updates (or receives a webhook if push_notification_config was provided)
4. Agent eventually returns { "status": "completed", "creative_manifest": { ... } }

This is documented in the Task Lifecycle and Async Operations guides.
On list_creatives: This serves a different purpose — it's for browsing/querying an existing creative library (filtering by status, format, concept, tags, etc.), not for retrieving the result of a build. If Celtra maintains a library of created creatives that buyers should be able to browse, then list_creatives is the right fit. If creatives are only produced on-demand via build_creative, you wouldn't need list_creatives at all — the async response from build_creative already returns the manifest.

Thank you, the first section makes sense.

I have a follow up question about the second part: list_creatives vs list_creative_formats At Celtra at the moment our Creative Formats are actually templates that users can browse, they are reusable across campaigns so users can replace various components with their own, but also creatives that users can see.

Would in this case list_creative_formats just return the format IDs, and list_creatives the same formats on a public link where the user can browser and see them?

Creative formats would be a list of the templates you support and would be public. Creatives are the instantiated templates with the user's assets, so not public.