Prebid Sales Agent - Mock Adapter

• Overview
• When to Use
• Configuration
  • Connection Configuration
  • Product Configuration
  • Admin UI Setup
• Supported Channels
• Test Headers
  • Example: Simulating a Campaign Lifecycle
• Delivery Simulation
  • How Simulation Works
  • Simulation Modes
• Strategy System
  • Simulation Scenarios
  • Strategy Multipliers
• Using with the uvx adcp CLI
• Using in Automated Tests
  • Test Isolation with Session IDs
  • Forcing Errors in Tests
  • Dry Run Mode
• Transitioning to Production
• Further Reading

Overview

The Mock Adapter is a fully functional in-memory ad server adapter included with the Prebid Sales Agent for testing, development, and demonstration purposes. It implements the complete AdServerAdapter interface without requiring any external ad server, making it the fastest way to explore and validate Sales Agent functionality.

The adapter is identified by adapter_name: "mock" and is implemented at src/adapters/mock_ad_server.py.

When to Use

The Mock Adapter is appropriate for:

• Development — Build and test AI buying agent integrations without a live ad server
• Testing — Run unit tests, integration tests, and end-to-end tests in CI/CD pipelines
• Demos — Demonstrate Sales Agent capabilities to stakeholders without configuring a real ad server
• Evaluation — Evaluate the Sales Agent before committing to a production ad server integration
• Training — Familiarize teams with the Sales Agent’s tool interface and media buy workflow

Configuration

Connection Configuration

The MockConnectionConfig accepts a single setting:

Product Configuration

The MockProductConfig controls how the mock adapter simulates delivery for products:

Admin UI Setup

1. Navigate to Settings > Ad Server in the Admin UI.
2. Select Mock from the adapter type dropdown.
3. Optionally configure dry_run in the JSONB config field:

{
  "dry_run": false
}

Supported Channels

The Mock Adapter supports all major channels for comprehensive testing:

Test Headers

The Mock Adapter responds to special HTTP headers that control simulation behavior. Pass these headers in your API, MCP, or A2A requests to exercise specific scenarios.

Example: Simulating a Campaign Lifecycle

# Create a media buy
uvx adcp http://localhost:8000/mcp/ --auth test-token create_media_buy \
  --product-id prod-001 --budget 10000

# Jump to mid-flight and check delivery
uvx adcp http://localhost:8000/mcp/ --auth test-token get_media_buy_delivery \
  --media-buy-id mb-001 \
  --header "X-Jump-To-Event: mid_flight"

# Force a timeout error to test error handling
uvx adcp http://localhost:8000/mcp/ --auth test-token get_media_buy_delivery \
  --media-buy-id mb-001 \
  --header "X-Force-Error: timeout"

Delivery Simulation

The Mock Adapter includes a delivery simulator that produces realistic mock delivery data over time. Rather than returning static values, delivery metrics progress naturally based on the product configuration and campaign parameters.

How Simulation Works

1. When a media buy is created, the simulator initializes delivery state based on the MockProductConfig (daily impressions, fill rate, CTR, viewability).
2. As time progresses (real or simulated via X-Mock-Time), the simulator calculates accumulated impressions, clicks, and spend.
3. Delivery metrics reflect realistic pacing — campaigns ramp up, hit steady state, and wind down.
4. The _simulate_time_progression() method advances the internal clock and updates metrics accordingly.

Simulation Modes

The adapter provides two methods for controlling simulation state:

• _is_simulation() — Returns true when the adapter is running in simulation mode (the default). In simulation mode, delivery data is generated algorithmically.
• set_simulation_time() — Programmatically set the simulation clock, equivalent to passing the X-Mock-Time header.

Strategy System

The Mock Adapter supports a strategy system that applies multipliers to simulated delivery metrics, enabling testing of different performance scenarios.

Simulation Scenarios

Set the scenario field in MockProductConfig or use the _get_simulation_scenario() method to activate predefined scenarios:

• High performance — Above-average CTR, viewability, and fill rate
• Slow start — Campaign ramps up gradually before reaching target delivery
• Underdelivery — Campaign falls behind pacing goals
• Overdelivery — Campaign exceeds expected delivery

Strategy Multipliers

The _apply_strategy_multipliers() method adjusts base delivery metrics according to the active strategy context. This allows testing how AI buying agents respond to different campaign performance patterns.

Using with the uvx adcp CLI

The uvx adcp CLI tool is the fastest way to interact with the Mock Adapter during development:

# Discover available tools
uvx adcp http://localhost:8000/mcp/ --auth test-token list_tools

# Browse products
uvx adcp http://localhost:8000/mcp/ --auth test-token get_products

# Create a media buy
uvx adcp http://localhost:8000/mcp/ --auth test-token create_media_buy \
  --product-id prod-001 --budget 5000 --start-date 2025-02-01 --end-date 2025-02-28

# Check delivery with auto-advance
uvx adcp http://localhost:8000/mcp/ --auth test-token get_media_buy_delivery \
  --media-buy-id mb-001 \
  --header "X-Auto-Advance: true"

Using in Automated Tests

The Mock Adapter is designed for use in automated test suites. The Sales Agent’s test infrastructure uses it extensively.

Test Isolation with Session IDs

Use the X-Test-Session-ID header to isolate test state between parallel test executions:

import httpx

async def test_media_buy_creation():
    headers = {
        "x-adcp-auth": "test-token",
        "X-Test-Session-ID": "test-run-abc123"
    }
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/v1/media-buys",
            json={"product_id": "prod-001", "budget": 5000},
            headers=headers
        )
        assert response.status_code == 201

Forcing Errors in Tests

Use X-Force-Error to test error handling paths:

async def test_timeout_recovery():
    headers = {
        "x-adcp-auth": "test-token",
        "X-Force-Error": "timeout"
    }
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "http://localhost:8000/api/v1/media-buys/mb-001/delivery",
            headers=headers
        )
        assert response.status_code == 504

Dry Run Mode

Enable dry run mode to validate request payloads without creating any state:

async def test_media_buy_validation():
    headers = {
        "x-adcp-auth": "test-token",
        "X-Dry-Run": "true"
    }
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/v1/media-buys",
            json={"product_id": "prod-001", "budget": -100},
            headers=headers
        )
        # Validation error returned without creating anything
        assert response.status_code == 422

Transitioning to Production

When you are ready to move from the Mock Adapter to a production ad server, the transition is straightforward:

1. Choose a production adapter — Select from Google Ad Manager, Kevel, Triton Digital, Broadstreet, or a custom adapter.
2. Configure credentials — Set up the required environment variables and authentication for your chosen adapter.
3. Update the Admin UI — Navigate to Settings > Ad Server and change the adapter type from Mock to your production adapter. Enter the adapter-specific configuration.
4. Reconfigure products — Review and update product configurations to reference real inventory in your ad server.
5. Test with dry run — Many production adapters support a dry run or sandbox mode. Use this to validate the integration before going live.
6. Switch over — Once validated, disable dry run mode. New media buys will be created in your production ad server.

Further Reading

• Quick Start — Get running with Docker and the Mock Adapter
• Architecture & Protocols — Adapter pattern overview
• Google Ad Manager Integration — Production GAM integration
• Building a Custom Adapter — Create your own adapter