​

S1: Media buy mastery

​

Specialisms this track prepares you to validate

​

What you’ll demonstrate

• Execute the full media buy lifecycle including proposals and forecasting
• Explain why every mutating media-buy request is cryptographically signed (RFC 9421): the signature is what lets the seller authenticate the buyer and detect tampering. No amount of lifecycle logic matters if you can’t trust who sent the request.
• Walk the buyer-identity resolution chain: signature → JWKS → agent entry → brand.json. Explain why iss claims and client-supplied headers are never treated as identity, and what each link in the chain defends against.
• Apply idempotency_key correctly across the lifecycle: fresh UUID v4 per logical buy, same key + same payload on network retry (returns replayed: true), new key when the agent re-plans with a different payload, and the handling of IDEMPOTENCY_CONFLICT and IDEMPOTENCY_EXPIRED. Explain why this is what makes agent retries safe for real money.
• Trace the state machine: create_media_buy returns pending_creatives or pending_start; sync_creatives clears pending_creatives; the seller MUST transition pending_start → active at flight start and webhook the orchestrator. Seller-initiated rejected is only valid from the pending states.
• Reason about which actions are valid in which states (cancel, sync_creatives from pending states; pause/resume/update_media_buy from active), and handle NOT_CANCELLABLE and concurrency conflicts via revision
• Select a pricing_option_id from a product’s pricing_options[] array — CPM, vCPM, CPP, CPA, flat rate, time — and explain why different pricing models carry different parameters
• Negotiate measurement_terms and performance_standards on guaranteed buys: propose overrides on create_media_buy, interpret seller acceptance (echoed back), adjustments, or TERMS_REJECTED. Recover by aligning to the seller’s supported vendors or accepting product defaults.
• Know that update_media_buy requires account (not just media_buy_id) so billing routes to the right relationship; omitting it is a protocol error
• Tie broadcast buys to agency billing by attaching agency_estimate_number at the buy or package level (package-level overrides buy-level when flights or stations differ)
• Interpret broadcast delivery reports: get_media_buy_delivery returns measurement window data (live, c3, c7) that progresses over days after broadcast — the C7 window’s DVR accumulation doesn’t close until seven days post-air, and vendor processing adds further delay before final data is available; incomplete data during this period is by design, not underdelivery
• Use get_media_buys to check status, valid_actions, and creative approvals before acting
• Interpret seller indicators as current relationship-scoped state: explain why creative fatigue belongs to one package–creative assignment, why the same creative may be fatigued on one seller but not another, and why provider methodology belongs in ext
• Handle pricing negotiation, budget allocation, and multi-agent orchestration
• Use refinement and package requests for complex buying scenarios
• Monitor and optimize campaign delivery using protocol tools
• Explain the measurement-agent loop: make the orchestrator a buyer-controlled gateway for the fixed get_media_buy_delivery and provide_performance_feedback tasks, authenticate provider output, and fan normalized assertions out to sellers without granting providers seller access
• Reason about failure modes, conflict resolution, and edge cases

​

Prerequisite reading

​

Core transaction tasks

​

Supporting concepts

​

Connecting to the test agent

export ADCP_AUTH_TOKEN="1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"

​

Lab exercises

1. Product discovery and evaluation — Query multiple sandbox agents, compare products, evaluate pricing
2. Pricing option selection — From the same product’s pricing_options[] array, select a CPM option and a CPP option. Explain what each option’s parameters mean and why the minimum spend differs.
3. Proposal and forecasting — Request proposals, analyze delivery forecasts (spend curves and availability)
4. Terms negotiation — On a guaranteed product, propose measurement_terms with a different vendor than the seller’s default, and performance_standards with a tighter viewability threshold. Observe seller acceptance, adjustment, or TERMS_REJECTED. Recover by aligning to the seller’s supported vendors.
5. Campaign commitment and optimization — Commit a direct offer with buy_products, assign creatives through sync_creatives, monitor through get_media_buys, and apply an in-envelope change with control_media_buy. Submit compact performance feedback with a named baseline, interpreting accepted, applied, and not_applied without overstating causality. Explain how the 3.x create_media_buy and update_media_buy facades map to the canonical operations, and verify that the update facade requires account.
6. Proposal negotiation and lifecycle walkthrough — Following the proposal negotiation implementation guide, act as Sam at Pinnacle Agency against StreamHaus. Use request_proposals, inspect proposal_refinement.supported_dimensions, and construct a refinement the seller can actually evaluate. Try a USD budget ceiling, a product include/omit decision, a targeting change, and multiple alternatives only when advertised; interpret partial and unable as structured counteroffers rather than generic failures. On an ask-only seller, observe the pre-mutation UNSUPPORTED_FEATURE, remove or translate the typed field, and retry. Finalize the chosen immutable proposal, call accept_proposal, and trace the resulting buy through pending_creatives → sync_creatives → pending_start → active.
7. Lifecycle management and recovery — Use revision for concurrency, follow available_actions to control_media_buy for operational changes, and route commercial changes through refine_proposals(accepted_proposal_id) plus accept_proposal. Handle REQUOTE_REQUIRED without mutating the accepted snapshot.
8. Broadcast billing and delivery — Create a broadcast buy with a buy-level agency_estimate_number and one package that overrides it with a station-specific estimate number. Verify both appear on delivery reconciliation. Call get_media_buy_delivery and interpret the measurement window fields: explain why c3 data may be incomplete immediately after broadcast and when the c7 window closes.
9. Multi-agent orchestration and execution — Manage campaigns across multiple sellers. Trace a cross-publisher suppression scenario: a viewer sees an ad on publisher A, then visits publisher B within the 2-hour recency window — what does Identity Match return and why? Configure frequency parameters (5/week, 2-hour minimum recency) and predict delivery impact. Explain why Context Match and Identity Match are structurally separated. Then design, conceptually and outside the public sales-agent sandbox, an orchestrator-hosted measurement gateway that exposes get_media_buy_delivery and provide_performance_feedback, grants only those orchestrator tasks, and maps one cross-seller result into seller-local submissions.
10. Warnings, indicators, and invalidations — Analyze a success warning and the later resource snapshot; distinguish buy/package/assignment indicator placement, exact type coverage, assignment approval, and webhook invalidation handling.

{
  "creative_id": "acme_summer_video",
  "assignments": {
    "assignment_count": 3,
    "returned_assignment_count": 3,
    "assignments_truncated": false,
    "assigned_packages": [
      {
        "media_buy_id": "mb_a",
        "package_id": "pkg_social",
        "assigned_date": "2026-08-01T00:00:00Z",
        "approval_status": "approved",
        "indicator_types_evaluated": [
          "creative_fatigue",
          "creative_quality_opportunity"
        ],
        "indicators_as_of": "2026-08-04T12:00:00Z",
        "indicators_evaluated_scope": [
          { "publisher_domain": "publisher-a.example" }
        ],
        "indicators": [
          {
            "type": "creative_fatigue",
            "scope": [
              {
                "publisher_domain": "publisher-a.example",
                "placement_id": "feed"
              }
            ]
          }
        ]
      },
      {
        "media_buy_id": "mb_b",
        "package_id": "pkg_social",
        "assigned_date": "2026-08-01T00:00:00Z",
        "approval_status": "approved",
        "indicator_types_evaluated": ["creative_fatigue"],
        "indicators_as_of": "2026-08-04T12:00:00Z",
        "indicators": []
      },
      {
        "media_buy_id": "mb_c",
        "package_id": "pkg_social",
        "assigned_date": "2026-08-01T00:00:00Z",
        "approval_status": "pending_review"
      }
    ]
  }
}

{
  "status": "completed",
  "media_buy_id": "mb_a",
  "revision": 2,
  "warnings": [
    {
      "code": "inventory_shortfall_forecast",
      "message": "The applied pacing control leaves forecast delivery below the requested goal.",
      "affected_resource": {
        "resource_type": "package",
        "media_buy_id": "mb_a",
        "package_id": "pkg_social"
      }
    }
  ]
}

{
  "status": "completed",
  "media_buys": [
    {
      "media_buy_id": "mb_a",
      "status": "active",
      "currency": "USD",
      "total_budget": 10000,
      "confirmed_at": "2026-08-01T00:00:00Z",
      "revision": 2,
      "packages": [
        {
          "package_id": "pkg_social",
          "indicator_types_evaluated": ["inventory_shortfall_forecast"],
          "indicators_as_of": "2026-08-04T12:00:00Z",
          "indicators": [{ "type": "inventory_shortfall_forecast" }]
        }
      ]
    }
  ],
  "pagination": { "has_more": false }
}

{
  "idempotency_key": "whk_01K2INDICATOR4EXAMPLE8Q7M5",
  "notification_id": "indchg_1",
  "notification_type": "indicators.changed",
  "fired_at": "2026-08-04T12:01:00Z",
  "subscriber_id": "optimization-worker",
  "account_id": "acc_1",
  "relationship_kind": "creative_assignment",
  "media_buy_id": "mb_a",
  "package_id": "pkg_social",
  "creative_id": "acme_summer_video",
  "change_kind": "cleared",
  "changed_indicator_types": ["creative_fatigue"],
  "observed_at": "2026-08-04T12:00:00Z"
}

{
  "idempotency_key": "whk_01K2ASSIGNMENT4EXAMPLE9R6",
  "notification_id": "assignchg_1",
  "notification_type": "creative.assignment_changed",
  "fired_at": "2026-08-04T12:01:00Z",
  "subscriber_id": "optimization-worker",
  "account_id": "acc_1",
  "media_buy_id": "mb_a",
  "package_id": "pkg_social",
  "creative_id": "acme_summer_video",
  "change_kind": "approval_changed",
  "observed_at": "2026-08-04T12:00:00Z"
}

​

Assessment

​

Start this module