Skip to main content
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.
Most test agents answer each call correctly but hold fixed data. Nothing forecasts from traffic, serves a booking day by day, or delivers differently from what was forecast. The two inventory agents on the test agent do all three, driven by a seeded simulation and a clock you can move. You can test what your agent does over a 30-day flight in a few calls: when a guarantee falls behind, when actual traffic differs from the forecast, or when an episode is cancelled. Both play the inventory role from #8993: they hold the catalogue and avails, execute media buys and report delivery. A storefront agent can book through both, as their buyer, over AdCP.

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_products returns each product with a forecast for the flight in filters.start_date and filters.end_date (30 days from now when omitted). filters.countries narrows the forecast. filters.delivery_type and filters.channels filter the products.
  • create_media_buy books each package:
    • Guaranteed packages take impressions as 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.
  • update_media_buy pauses, resumes and cancels a buy or a package, and changes a package’s budget, impressions or bid_price, or the buy’s end_time.
  • get_media_buys and get_media_buy_delivery report what was booked and what was delivered. They include by_package, daily_breakdown and pacing_index for guaranteed packages.
Everything you book is private to your credential. All the accounts you use with one credential book into the same simulated market on each tenant, so your own buys compete for inventory.

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 with comply_test_controller:
  • get returns simulated.simulated_now, and pinned: false while the clock still reads the wall clock.
  • advance_time takes either to (an RFC 3339 instant) or by (an ISO 8601 duration in weeks, days, hours, minutes or seconds). It returns the new simulated_now and days_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_state on either inventory tenant unpins the clock and discards your buys on both. A reset_state elsewhere 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_probe advance_time moves on /sales/mcp, so moving it on either tenant moves it for both.
Both tenants list 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:
  1. 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.
  2. Actual traffic arrives. It differs from the forecast by seeded noise and by the season’s scripted events.
  3. 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.
  4. The auction takes what is left. The highest bid above the floor wins until each package’s daily budget is spent.
  5. 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.
Delivery is reported once the day has closed and the product’s reporting delay has passed: the next day for the websites, a day later for the podcast and the creator series. A sponsorship package keeps delivering after its flight ends, while its installments’ audience builds.

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:
  1. Pin the clock before the flight: sandbox_clock advance_time to 2026-12-31T12:00:00Z.
  2. create_media_buy for 2027-01-01 to 2027-01-31 with one package on sports_hero_guaranteed (pricing_option_id sports_hero_guaranteed_cpm, impressions 180000).
  3. create_media_buy for the same flight with one package on preroll_auction (preroll_auction_cpm, bid_price 10). Two buys keep each one’s daily_breakdown separate.
  4. sandbox_clock advance_time by P31D.
  5. get_media_buy_delivery for both buys.
In the daily breakdown, the guarantee drops to under half its usual delivery during the outage and delivers above its earlier pace afterwards. The auction package’s delivery differs from the forecast 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.