v6 SDK: auto-project creative.supported_formats from creative_agents declarations

[bokelley]

Context

Surfaced during review of #3307 (v2 creative formats RFC).

In v2, sales agents declare creative agents two ways under get_adcp_capabilities.creative:

• creative_agents: [{ agent_url }] — the source-of-truth list
• supported_formats: [...] — the resolved/flattened catalog buyers consume

Today these are independently declared, which means an adopter who adds a format to their creative agent can drift from the supported_formats literal on their sales agent and not realize buyers see stale capabilities.

Proposal

The v6 SDK auto-projects supported_formats by fetching each creative_agents[].agent_url, calling list_creative_formats (or the equivalent v2 capability surface), and unioning. Adopters declare creative_agents once; the SDK derives the catalog.

Manual override stays supported but is discouraged: if a seller wants to narrow what an upstream creative agent advertises (e.g., "I trust Flashtalking but only for hosted html5, not VAST"), they declare creative_agents: [{ agent_url, only_format_kinds?: [...] }] and the union is computed but filtered.

Worked example

The third-party-creative-agent flow added to v2-overview.mdx in #3307 documents the pattern from the buyer side. This issue is about the SDK behavior that makes that flow ergonomic for sellers:

// Seller declares once
const capabilities = {
  creative: {
    creative_agents: [
      { agent_url: "https://flashtalking.adcp" },
      { agent_url: "https://creative.example.adcp" }
    ]
    // supported_formats auto-projected by SDK
  }
}

vs. today:

// Seller declares twice (drift risk)
const capabilities = {
  creative: {
    creative_agents: [...],
    supported_formats: [/* manually mirrored from each creative_agents[].agent_url */]
  }
}

Open questions

• Does the union happen at SDK init / fetch time, or per-request? (Caching strategy.)
• What's the stale-cache TTL when the SDK can't reach a declared creative agent?
• Does the SDK surface the projection via a method that returns the resolved list, or does it just populate the capabilities response?
• For the narrowing use case: is only_format_kinds the right shape, or do we want richer filter expressions (per-canonical narrowing, capability_id allowlists)?

Out of scope for the spec PR

This is SDK-side behavior, not a v2 spec change — creative_agents and supported_formats already exist with the right semantics. The spec just doesn't say "SDKs should auto-project," and adopters today declare both fields independently. Filing here so the SDK work is tracked separately from #3307.

Refs

• RFC #3305 implementation preview — v2 creative formats (full spec, not for merge) #3307 — v2 creative formats preview branch (where this overlap was surfaced)
• RFC: Creative Formats v2 — canonical formats live on products, composition primitives, validate_input #3305 — RFC the v2 work implements

[bokelley]

Closing — premise is wrong on three counts. Recording the correction here so anyone landing on this issue from a search has the right model.

What I got wrong:

1. I described creative_agents[] as a v2 field on get_adcp_capabilities.creative. It isn't — creative_agents[] is a v1 field on list_creative_formats (recursive-discovery hint pointing at OTHER agents the buyer can query for additional formats). It's part of the deprecated v1 surface and goes away in v2.

2. I treated supported_formats as a derived projection of creative_agents. Those fields live on different agents and serve different purposes. creative.supported_formats lives on the creative agent's get_adcp_capabilities response, declaring what that agent can produce. It's not a derivation of any sales-agent field.

3. I called the seller's creative-agent list "the source of truth" for accepted formats. The seller's authoritative declaration of accepted formats is the product catalog (format_options on each product, in v2). Sellers do not maintain a list of "approved creative agents" in v2 — buyers choose creative agents independently through brand-side relationships, AAO registry, or direct knowledge.

The actual v2 model:

• Sales agent → declares accepted formats inline on each product's format_options. That's authoritative.
• Creative agent → declares its producible catalog via creative.supported_formats on its OWN get_adcp_capabilities. Independent of any seller.
• Buyer → reasons about creative-agent ↔ seller-product compatibility client-side ("this creative agent can produce image 300×250 ≤200KB; this seller's product accepts image 300×250 ≤200KB; compatible").

There's no auto-projection problem to solve because there's no derivation relationship between the two surfaces.

The original review concern (#3307 reviewer flagged "two places to declare formats, drift risk") doesn't apply once the architecture is read correctly. Closing with no follow-up.

Worked example in v2-overview.mdx that was built around the same wrong premise has been corrected in 23c8bea30 (commit on the #3307 preview branch).