> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Test against simulated inventory agents

> Two inventory agents on the public test agent that forecast, book and deliver over simulated time, with a sandbox clock you can move.

> [!NOTE]
>
> **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](https://github.com/adcontextprotocol/adcp/issues/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](https://github.com/adcontextprotocol/adcp/issues/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

| Tenant | URL | Sells |
| - | - | - |
| Ad server | `https://test-agent.adcontextprotocol.org/inventory-adserver/mcp` | Display, pre-roll video and a homepage takeover on two sites, guaranteed and in a first-price auction |
| Content platform | `https://test-agent.adcontextprotocol.org/inventory-content/mcp` | Exclusive sponsorships of a weekly podcast, a weekly newsletter and a fortnightly creator series |

Authenticate with the same bearer tokens as the rest of the test agent; see the [quickstart](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/quickstart.md). Each tenant speaks the media buy protocol as it is, with no new tasks:

* [`get_products`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/get_media_buys) and [`get_media_buy_delivery`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/building/by-layer/L3/comply-test-controller):

```json theme={null}
{ "scenario": "sandbox_clock", "params": { "operation": "get" } }
```

```json theme={null}
{ "scenario": "sandbox_clock", "params": { "operation": "advance_time", "to": "2026-12-31T12:00:00Z" } }
```

```json theme={null}
{ "scenario": "sandbox_clock", "params": { "operation": "advance_time", "by": "P30D" } }
```

* `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:

| Tenant | When | Event |
| - | - | - |
| Ad server | 2027-01-08 to 2027-01-12 | The Summit Sports hero unit serves a quarter of its traffic. A guarantee on `sports_hero_guaranteed` falls behind, then catches up. |
| Ad server | 2027-01-20 to 2027-01-22 | Pinnacle News traffic nearly doubles. |
| Content | 2027-01-18 | The Morning Brief episode `morning_brief_012` is cancelled. Its sponsor receives nothing for it. |
| Content | 2027-01-18 | The Maker Studio video `maker_studio_006` is postponed to 2027-01-23. |

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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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`](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/media-buy/task-reference/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.