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 () => ({ : , : , : {} }),
    :  () => ({ : , : [] }),
    :  () => ({ : [], :  }),
  };

  :  = {
    
    :  (req, ctx) => {
       products =  ..(req., req.);
       {
        : ,
        : products.( ({
          : p.,
          : p.,
          : p..( ({ id })),
          : ,
          : , 
          : [
            { : , : , : { : p., :  } },
          ],
          : { : { : p. } }, 
        })),
      };
    },

    
    
    
    
    
    
    
    
    
    
    
    :  (req, ctx) => {
       ( (req.) >=  (req.))   ();
       (req.?. < )   ({ : , :  });

       lineItems = [];
       ( pkg  req.) {
         (!pkg.)   (pkg.);
        
         adUnits = pkg..?.?. ?? [];
         formats = pkg..;
        lineItems.( ..(pkg, { adUnits, formats }));
      }
       order =  ..(req, lineItems);

      
       {
        : order.,
        : , 
        : { : order. }, 
        : order..( ({
          : li.,
          : ,
          : li.,
          : { : li. },
        })),
      };
    },

    
    
    
    
    
    :  (mediaBuyId, patch, ctx) => {
       orderMeta =  ctx.?.(mediaBuyId);
       (!orderMeta)   (mediaBuyId);

       ( pkg  patch. ?? []) {
         pkgMeta =  ctx.?.(pkg.);
         (!pkgMeta)   (pkg.);
         ..(pkgMeta., pkg);
      }
       order =  ..(orderMeta.);
       .(order);
    },

    
    :  (creatives, ctx) => {
       out = [];
       ( c  creatives) {
         native =  ..(c);
         ctx.?.(, c., { : native. });
        out.({ : c., : , :  });
      }
       out;
    },

    
    
    
    
    
    
    
    
    
    :  (req, ctx) => {
       buys =  ..({ : ctx.., : req. });
       {
        : buys.( ({
          : buy.,
          : ..(buy.),
          : buy.,
          : { : buy., : buy. }, 
          : buy.,
          : buy.,
          : buy..( ({
            : li.,
            : ..(li.),
            : li.,
            : { : li. }, 
          })),
          : { : buy. },
        })),
      };
    },

    
    :  (filter, ctx) => ({ :  ..(filter) }),
  };

  () {}
}

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
}  ;

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).