New storyboard: validate format_id references on products — prevent invalid agent_url/id combos

[EmmaLouise2018]

Summary

Sales agents return format_ids on products from get_products, each referencing an agent_url and id. There is currently no storyboard that validates these references actually resolve to real formats on the declared creative agent. A sales agent can return a non-existent id, a wrong agent_url, or a stale format that has been removed — and nothing catches it until a buyer agent fails at sync_creatives time.

Proposed storyboard: media_buy_format_id_integrity

A new storyboard step (or addition to media_buy_seller) that:

1. Calls get_products on the sales agent
2. Collects all format_ids arrays across returned products
3. Groups them by agent_url
4. For each unique agent_url, calls list_creative_formats
5. Asserts every referenced id exists in the returned formats list
6. Fails with a clear error naming the specific invalid { agent_url, id } combo

Why this matters

• Invalid format references are silent until sync_creatives fails — which is after the media buy is already committed
• The video_640x480 example above is a real case: the format doesn't exist on the reference creative agent but nothing catches it at product discovery time
• Stale format_ids are a common production issue when creative agents deprecate formats without sellers updating their product catalog

Scope

Two options for where this lives:

Option A: New standalone storyboard media_buy_format_id_integrity that only tests this. Easy to run in isolation.

Option B: Add as a step to the existing media_buy_seller storyboard between get_products and list_creative_formats. Runs automatically for all sellers.

Option B is preferred — this is a baseline correctness check that should run for every seller agent, not opt-in.

Affected files

• storyboards/media_buy_seller.json (add step) OR storyboards/media_buy_format_id_integrity.json (new)
• storyboards/README.md (update index)

Notes

• The storyboard runner may need to authenticate against third-party creative agent URLs — handle gracefully if the creative agent requires auth the runner doesn't have
• Should warn (not fail) if a creative agent URL is unreachable, since the sales agent may reference a buyer-deployed creative agent

[bokelley]

Runner-side issue opened: adcontextprotocol/adcp-client#670 — proposes a new refs_resolve validation primitive that generalizes to any cross-step set integrity check (not just format_ids).

Once that lands and releases, the storyboard-side change here is two-line: add the validation on the list_formats step of media_buy_seller. Closing path:

1. adcp-client#670 — runner implements refs_resolve
2. this repo — document the check in storyboard-schema.yaml + wire it up in media_buy_seller/index.yaml, closes this issue

[bokelley]

Completed end-to-end across both repos:

Spec side (this repo) — #2600 added list_formats_integrity step to media_buy_seller storyboard (product_discovery phase, between get_products_brief and create_buy). Filters list_creative_formats by captured $context.product_format_id and asserts the FormatID round-trips verbatim. Implements Option B (baseline check for every seller agent).

Client side (@adcp/client) — adcontextprotocol/adcp-client#534 added a format_id reconciliation phase in schema_validation that validates structurally-valid format_ids and pricing_option_ids from get_products against list_creative_formats. media_buy_seller uses context_outputs to capture format_ids from get_products and echo them into sync_creatives via $context.product_format_id — the exact roundtrip that broke on Magnite.

Together these catch the video_640x480-style silent-stale-reference case at product-discovery time rather than sync_creatives time.

Cross-agent dispatch (calling the creative agent at format_ids[].agent_url directly rather than via the sales agent under test) remains a runner enhancement — tracked as a runner concern in @adcp/client, not a spec issue.