build-decisioning-platform

name	build-decisioning-platform
description	Build an AdCP sales agent (publisher / SSP / retail-media network). Implement 5 functions, throw 8 typed errors, run it. Framework handles idempotency, HITL, signing, multi-tenant, schema validation.

Build a sales agent

Implement 6 functions. The framework does the rest.

What you're building

A DecisioningPlatform for the sales-non-guaranteed (or sales-guaranteed) specialism. Buyers call your AdCP server to discover products, create media buys, push creatives, update buys, and pull delivery reports. You translate those calls to your platform (GAM, FreeWheel, Kevel, your own ad server, whatever).

Imports cheat sheet

For 95% of sales agents, these are the only @adcp/sdk/server imports you need:

import {
  // Server entry + persistence
  createAdcpServerFromPlatform,
  getAllAdcpMigrations,
  serve,
  // Wire-shape helpers (eliminate 30+ lines of boilerplate per Product)
  buildProduct,
  buildPackage,
  buildPricingOption,
  DEFAULT_REPORTING_CAPABILITIES, // required field; override per-product
  // Typed errors — pick from this catalog instead of `throw new AdcpError(...)`
  PackageNotFoundError,
  MediaBuyNotFoundError,
  ProductNotFoundError,
  BudgetTooLowError,
  BackwardsTimeRangeError,
  InvalidStateError,
  RateLimitedError,
  UnsupportedFeatureError,
  // Types
  type DecisioningPlatform,
  type SalesPlatform,
} from '@adcp/sdk/server';

For other agent shapes:

• Creative agent (template / generative): swap SalesPlatform for CreativeBuilderPlatform
• Signals agent: swap for SignalsPlatform
• Brand-rights agent: swap for BrandRightsPlatform
• Multi-tenant host: add createTenantRegistry

The full export list is in @adcp/sdk/server. Surfaces marked @deprecated will strikethrough in your IDE. Trust the strikethrough — pick from the typed-error catalog above instead.

When you need...

• HITL flows (operator approval, async creative review) → advanced/HITL.md
• Multi-tenant hosting → advanced/MULTI-TENANT.md
• OAuth / OIDC authentication → advanced/OAUTH.md
• Sandbox / test-mode routing → advanced/SANDBOX.md
• Compliance test scenarios (comply_test_controller) → advanced/COMPLIANCE.md
• Campaign governance specialism → advanced/GOVERNANCE.md
• Brand rights specialism → advanced/BRAND-RIGHTS.md
• Replay TTL / idempotency principal tuning → advanced/IDEMPOTENCY.md
• State machine transitions (pending_creatives → active) → advanced/STATE-MACHINE.md
• Postgres operations / sizing / indices / cleanup → ../../docs/guides/POSTGRES.md
• Edge cases / full reference → advanced/REFERENCE.md

The 6 functions

import {
  createAdcpServerFromPlatform,
  createCtxMetadataStore,
  memoryCtxMetadataStore,
  DEFAULT_REPORTING_CAPABILITIES,
  PackageNotFoundError,
  MediaBuyNotFoundError,
  ProductNotFoundError,
  BudgetTooLowError,
  BackwardsTimeRangeError,
  InvalidStateError,
  type DecisioningPlatform,
  type SalesPlatform,
} from '@adcp/sdk/server';

class MyPlatform implements DecisioningPlatform {
  capabilities = {
    adcp_version: '3.0.0',
    specialisms: ['sales-non-guaranteed'] as const,
    pricingModels: ['cpm'] as const,
    channels: ['display', 'video'] as const, // strict literal-union — TS catches typos
    formats: [{ format_id: 'display_300x250' }],
    idempotency: { replay_ttl_seconds: 86400 },
  };

  accounts = {
    resolution: 'derived' as const, // single tenant; framework returns the same Account every call
    resolve: async () => ({ id: 'pub_main', operator: 'mypub', ctx_metadata: {} }),
    upsert: async () => ({ ok: true, items: [] }),
    list: async () => ({ items: [], nextCursor: null }),
  };

  sales: SalesPlatform = {
    // 1. Catalog lookup. Brief in, products out.
    getProducts: async (req, ctx) => {
      const products = await this.platform.searchInventory(req.brief, req.promoted_offering);
      return {
        cache_scope: 'account',
        products: products.map(p => ({
          product_id: p.id,
          name: p.name,
          format_ids: p.formatIds.map(id => ({ id })),
          delivery_type: 'non_guaranteed',
          reporting_capabilities: DEFAULT_REPORTING_CAPABILITIES, // required — see ReportingCapabilities type for all fields
          pricing_options: [
            { pricing_option_id: `${p.id}-cpm`, model: 'cpm', floor: { amount: p.floor, currency: 'USD' } },
          ],
          ctx_metadata: { gam: { ad_unit_ids: p.adUnitIds } }, // stashed; framework round-trips
        })),
      };
    },

    // 2. Create a buy. Sync path; HITL is `ctx.handoffToTask` (see advanced/HITL.md).
    //    SDK auto-hydrates each pkg.product with the resolved Product (incl. ctx_metadata)
    //    from the prior getProducts call — no separate lookup needed.
    //
    //    CONTRACT — `pkg.product` is `undefined` when SDK has no record of that product_id.
    //    That's NOT authoritative "doesn't exist" — the SDK store is a cache, and your
    //    publisher's DB might still have it. Decision tree when undefined:
    //      - Have your own product DB → look up there; throw `ProductNotFoundError(pkg.product_id)`
    //        only if YOUR DB also returns nothing.
    //      - Pure-SDK store (no own DB) → throw `ProductNotFoundError(pkg.product_id)` immediately.
    //      - Either way: never let `undefined` flow downstream silently.
    createMediaBuy: async (req, ctx) => {
      if (new Date(req.start_time) >= new Date(req.end_time)) throw new BackwardsTimeRangeError();
      if (req.total_budget?.amount < 1000) throw new BudgetTooLowError({ floor: 1000, currency: 'USD' });

      const lineItems = [];
      for (const pkg of req.packages) {
        if (!pkg.product) throw new ProductNotFoundError(pkg.product_id);
        // pkg.product is the full Product from getProducts, with adapter-internal config attached:
        const adUnits = pkg.product.ctx_metadata?.gam?.ad_unit_ids ?? [];
        const formats = pkg.product.format_ids;
        lineItems.push(await this.platform.createLineItem(pkg, { adUnits, formats }));
      }
      const order = await this.platform.createOrder(req, lineItems);

      // Stash your platform's IDs so subsequent updateMediaBuy can hydrate them too.
      return {
        media_buy_id: order.id,
        status: 'pending_creatives', // creative state machine — see advanced/STATE-MACHINE.md
        ctx_metadata: { gam_order_id: order.gamOrderId }, // SDK persists; subsequent updateMediaBuy gets req.ctx_metadata.gam_order_id
        packages: order.lineItems.map(li => ({
          package_id: li.id,
          status: 'pending_creatives',
          buyer_ref: li.buyerRef,
          ctx_metadata: { gam_line_item_id: li.gamLineItemId },
        })),
      };
    },

    // 3. Update a buy. SDK auto-hydrates the resolved MediaBuy (and its packages,
    //    each with ctx_metadata) at req.mediaBuy when present in the store from a
    //    prior createMediaBuy / getMediaBuys call. Falls back gracefully if absent
    //    (publisher uses their own DB).
    //    (6.2 will pre-read state + decompose into atomic verbs; track adcp-client#1071.)
    updateMediaBuy: async (mediaBuyId, patch, ctx) => {
      const orderMeta = await ctx.ctxMetadata?.mediaBuy(mediaBuyId);
      if (!orderMeta) throw new MediaBuyNotFoundError(mediaBuyId);

      for (const pkg of patch.packages ?? []) {
        const pkgMeta = await ctx.ctxMetadata?.package(pkg.package_id);
        if (!pkgMeta) throw new PackageNotFoundError(pkg.package_id);
        await this.platform.updateLineItem(pkgMeta.gam_line_item_id, pkg);
      }
      const order = await this.platform.getOrder(orderMeta.gam_order_id);
      return this.toMediaBuy(order);
    },

    // 4. Push creatives. Returns one row per creative with action + status.
    syncCreatives: async (creatives, ctx) => {
      const out = [];
      for (const c of creatives) {
        const native = await this.platform.upsertCreative(c);
        await ctx.ctxMetadata?.set('creative', c.creative_id, { gam_creative_id: native.id });
        out.push({ creative_id: c.creative_id, action: 'created', status: 'approved' });
      }
      return out;
    },

    // 5. List buys this account owns. REQUIRED — non-negotiable. Every seller
    //    needs to support reading back what they created. SDK auto-stores
    //    returned buys for hydration on subsequent updateMediaBuy calls.
    //
    //    WRITE-ONLY ADOPTERS (proposal-mode push-channel sellers, retail-media
    //    flows that deliver via webhook): return `{ media_buys: [] }`. Never
    //    lie — empty array is truthful "no buys to enumerate via this surface."
    //    Buyers asking for a list get an empty answer. Don't omit the method
    //    or stub-throw; just return empty.
    getMediaBuys: async (req, ctx) => {
      const buys = await this.platform.listOrders({ accountId: ctx.account.id, status: req.status });
      return {
        media_buys: buys.map(buy => ({
          media_buy_id: buy.id,
          status: this.statusMappers.mediaBuy(buy.nativeStatus),
          buyer_ref: buy.buyerRef,
          total_budget: { amount: buy.budgetAmount, currency: buy.currency }, // REQUIRED on the wire shape
          start_time: buy.startTime,
          end_time: buy.endTime,
          packages: buy.lineItems.map(li => ({
            package_id: li.id,
            status: this.statusMappers.mediaBuy(li.nativeStatus),
            buyer_ref: li.buyerRef,
            ctx_metadata: { gam_line_item_id: li.gamLineItemId }, // round-trip publisher state
          })),
          ctx_metadata: { gam_order_id: buy.gamOrderId },
        })),
      };
    },

    // 6. Delivery report.
    getMediaBuyDelivery: async (filter, ctx) => ({ deliveries: await this.platform.fetchReports(filter) }),
  };

  constructor(private platform: MyAdServer) {}
}

That's the agent. Five functions. The framework wires the wire protocol around it (MCP tools, A2A skill manifest, idempotency, schema validation, HITL task envelopes, RFC 9421 webhook signing, multi-tenant routing).

Errors you throw — pick from the import list

import {
  PackageNotFoundError, // wrong package_id on update
  MediaBuyNotFoundError, // wrong media_buy_id
  ProductNotFoundError, // wrong product_id on create
  ProductUnavailableError, // product exists but sold out
  CreativeNotFoundError, // wrong creative_id
  CreativeRejectedError, // brand-safety failed, etc.
  BudgetTooLowError, // under floor (correctable — buyer raises)
  BudgetExhaustedError, // pacing burst hit cap
  IdempotencyConflictError, // same key, different payload
  InvalidRequestError, // generic field-level bad input
  InvalidStateError, // illegal transition (paused → archived violations)
  BackwardsTimeRangeError, // start_time >= end_time
  AuthMissingError, // no Authorization header was presented
  AuthInvalidError, // credentials were presented but rejected
  PermissionDeniedError, // auth present, lacks scope
  RateLimitedError, // throttled (clamps retry_after to [1, 3600])
  UnsupportedFeatureError, // tool unimplemented
  ComplianceUnsatisfiedError, // brand-safety attestation missing
  GovernanceDeniedError, // spending authority revoked
  PolicyViolationError, // categorical content rejection
} from '@adcp/sdk/server';

AuthRequiredError still exists for older code and emits legacy AUTH_REQUIRED; new seller code should use AuthMissingError / AuthInvalidError so buyers can distinguish missing credentials from rejected credentials.

Each class encodes the right code / recovery / field shape. Don't throw generic Error — the framework catches that and maps to SERVICE_UNAVAILABLE, which the buyer can't pattern-match.

Persisting platform state — ctx.ctxMetadata

Your platform has IDs (GAM order_id, line_item_id) that AdCP doesn't model. Stash them once, read them on subsequent calls. The framework round-trips per (account.id, kind, id) and strips from buyer-facing wire payloads.

// Wire a store at server construction:
import { createCtxMetadataStore, memoryCtxMetadataStore, pgCtxMetadataStore, getCtxMetadataMigration } from '@adcp/sdk/server';

await pool.query(getCtxMetadataMigration());                                  // Postgres only
const ctxMetadata = createCtxMetadataStore({ backend: pgCtxMetadataStore(pool) });

// Stash in any handler return:
await ctx.ctxMetadata?.set('product', productId, { gam: { ad_unit_ids: [...] } });

// Read in a later handler:
const meta = await ctx.ctxMetadata?.product(productId);

Memory backend: fine for dev; use Postgres in cluster — silent loss after rolling restart produces "package not found" errors that look like publisher bugs and run for weeks.

Account scoping is automatic. ctx.ctxMetadata binds to ctx.account.id per request. No-account tools (provide_performance_feedback, list_creative_formats) get ctx.ctxMetadata = undefined — branch defensively.

Run it

import { Pool } from 'pg';
import { createAdcpServerFromPlatform, getAllAdcpMigrations, serve } from '@adcp/sdk/server';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await pool.query(getAllAdcpMigrations()); // one DDL call, all 3 tables

const platform = new MyPlatform(myAdServer);
const server = createAdcpServerFromPlatform(platform, {
  name: 'My Sales Agent',
  version: '1.0.0',
  pool, // wires idempotency + ctxMetadata + taskRegistry
});

serve(() => server, { port: process.env.PORT });

That's the whole bootstrap. One pool, one migration, three persistence concerns wired by the framework.

For dev / single-process: omit pool entirely. Framework defaults to in-memory backends. Don't ship that to production — silent state loss after rolling restart produces "package not found" errors that look like publisher bugs and run for weeks.

Operator checklist

Things you set up once at deploy time:

• DATABASE_URL env var pointing at your Postgres instance
• Run getAllAdcpMigrations() once per database (idempotent — safe to re-run)
• OAuth provider config — see advanced/OAUTH.md if buyers authenticate via OIDC
• ADCP_VERSION env (default 3.0.0) if pinning a specific spec version

See also

• advanced/HITL.md — long-running tools (creative review, manual approval). Use ctx.handoffToTask(fn).
• advanced/MULTI-TENANT.md — TenantRegistry for one-process-many-publishers.
• advanced/OAUTH.md — auth providers (OIDC client_credentials, etc.).
• advanced/SANDBOX.md — test-mode routing via AccountReference.sandbox.
• advanced/COMPLIANCE.md — comply_test_controller for storyboard-driven QA.
• advanced/GOVERNANCE.md — campaign-governance specialism.
• advanced/BRAND-RIGHTS.md — brand-rights specialism.
• advanced/IDEMPOTENCY.md — replay TTL / principal resolver tuning.
• advanced/STATE-MACHINE.md — pending_creatives → pending_start → active transitions.
• advanced/REFERENCE.md — full reference (everything above + edge cases + design rationale).