Non-normative. These are sandbox tenants of the public test agent, built for testing buyer and storefront agents over the life of a buy. The
sandbox_clock controller scenario is proposed in #9025 and is served only by these two tenants for now. Their behaviour is a simulation, not a model of any real ad server.Connect
Authenticate with the same bearer tokens as the rest of the test agent; see the quickstart. Each tenant speaks the media buy protocol as it is, with no new tasks:
get_productsreturns each product with aforecastfor the flight infilters.start_dateandfilters.end_date(30 days from now when omitted).filters.countriesnarrows the forecast.filters.delivery_typeandfilters.channelsfilter the products.create_media_buybooks each package:- Guaranteed packages take
impressionsas their goal. Without it, the goal is what the budget buys at the fixed price. - The takeover and the sponsorships take every impression of what they cover.
- Auction packages bid
bid_price, first-price, above the floor. targeting_overlay.geo_countries(US,CA) narrows a package.
- Guaranteed packages take
update_media_buypauses, resumes and cancels a buy or a package, and changes a package’sbudget,impressionsorbid_price, or the buy’send_time.get_media_buysandget_media_buy_deliveryreport what was booked and what was delivered. They includeby_package,daily_breakdownandpacing_indexfor guaranteed packages.
Move the clock
Every time-dependent behaviour of these tenants reads your sandbox clock. Until you move it, it reads the wall clock. Move it withcomply_test_controller:
getreturnssimulated.simulated_now, andpinned: falsewhile the clock still reads the wall clock.advance_timetakes eitherto(an RFC 3339 instant) orby(an ISO 8601 duration in weeks, days, hours, minutes or seconds). It returns the newsimulated_nowanddays_crossed, the number of UTC days the clock moved across. The tenant you call runs those days at once; the other runs them on your next call to it, with the same results.- The clock only moves forward. An earlier instant is refused with
INVALID_TRANSITION. reset_stateon either inventory tenant unpins the clock and discards your buys on both. Areset_stateelsewhere that unpins the clock, such as/sales/mcp’s, also leaves your inventory buys behind: a market that has run days the clock has not reached starts fresh.- You have one clock per credential. It is the same clock that
reporting_subscription_probeadvance_timemoves on/sales/mcp, so moving it on either tenant moves it for both.
sandbox_clock and reset_state in list_scenarios and in compliance_testing.scenarios.
What happens each simulated day
When the clock passes the end of a day, that day runs:- Bookings start. A buy confirmed by the end of day N serves from day N+1, or from its flight start if that is later.
- Actual traffic arrives. It differs from the forecast by seeded noise and by the season’s scripted events.
- Guarantees are served first. The takeover and the sponsorships take their share. Impression goals are then served by the high-water mark method. Each package’s daily target is its remaining goal divided by its remaining days. The package with the least usable supply goes first, and each takes the same share of every impression it can use, never more than its target. A package that falls short spreads the shortfall over its remaining days.
- The auction takes what is left. The highest bid above the floor wins until each package’s daily budget is spent.
- Installments run. Each one runs, is postponed or is cancelled, as the season says. One that runs builds its audience over its channel’s curve: newsletter opens over 3 days, podcast listens over 30, video views over 6 weeks.
The season
The simulation is deterministic: the same calls at the same simulated times always give the same results. The season runs from 2026-11-01 to 2028-10-30 and includes these scripted events:
A content product lists the installments scheduled in the requested flight, with each one’s
status as known at your sandbox time: scheduled, then published, postponed (with the new scheduled_at) or cancelled once its date passes. A sponsorship package buys every installment of its product scheduled in its flight.
A month in five calls
On/inventory-adserver/mcp:
- Pin the clock before the flight:
sandbox_clockadvance_timeto2026-12-31T12:00:00Z. create_media_buyfor 2027-01-01 to 2027-01-31 with one package onsports_hero_guaranteed(pricing_option_idsports_hero_guaranteed_cpm,impressions180000).create_media_buyfor the same flight with one package onpreroll_auction(preroll_auction_cpm,bid_price10). Two buys keep each one’sdaily_breakdownseparate.sandbox_clockadvance_timebyP31D.get_media_buy_deliveryfor both buys.
get_products gave for the same flight.
The engine behind these tenants lives in server/src/training-agent/inventory-sim/engine/ and has no dependencies on the rest of the test agent, so it can move into @adcp/sdk if that proves useful.