git:20260503.79c2835 to git:20260503.91c1ff8

- description: Use when building an AdCP signals agent, creating an audience data server, or standing up a data provider agent that serves targeting segments to buyers.

- ## Overview

-

- A signals agent serves audience segments to buyers for campaign targeting. Two tools: `get_signals` (discovery) and `activate_signal` (push to DSPs or sales agents). The business model — marketplace vs owned data — shapes every implementation decision. Determine that first.

-

- > **Common shape gotchas:** `signal_ids[]` in `get_signals` is `signal_id[]` (provenance objects with `source`/`data_provider_domain`/`id`), not bare strings. `activate_signal` returns deployments with `ActivationKey` `oneOf` — for `type: 'key_value'` the `key` and `value` fields sit at the TOP level of `activation_key`, NOT nested under a `key_value` sub-field. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for the patterns adopters consistently get wrong on first pass.

-

- ## When to Use

-

- - User wants to build an agent that serves audience/targeting data

- - User mentions signals, segments, audiences, data provider, or CDP in the context of AdCP

- - User references `get_signals`, `activate_signal`, or the signals protocol

-

- **Not this skill:**

-

- - Selling ad inventory (products, packages, media buys) → `skills/build-seller-agent/`

- - Rendering creatives from briefs → that's a creative agent

- - Building a client that _calls_ a signals agent → see `docs/getting-started.md`

-

- **Often claimed alongside:** [`sales-social`](../build-seller-agent/SKILL.md) (walled-garden audience push), [`sales-non-guaranteed`](../build-seller-agent/SKILL.md) (DSP data marketplace as a side surface), [`audience-sync`](../build-seller-agent/SKILL.md) (identity-provider owned-graph activation). See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).

-

- ## Specialisms This Skill Covers

-

- | Specialism | Status | Delta | See |

- | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |

- | `signal-marketplace` | stable | `signal_id.source: 'catalog'` + resolvable `data_provider_domain`; span ≥2 providers in demos; platform activations are **async** (`is_live: false` → poll to live) | [§ signal-marketplace](#specialism-signal-marketplace) |

- | `signal-owned` | stable | `signal_id.source: 'agent'` + your `agent_url`; `value_type` constraints (`allowed_values` for categorical, `min`/`max` for numeric); `deployed_at` on deployments | [§ signal-owned](#specialism-signal-owned) |

-

- ## Protocol-Wide Requirements

-

- Full treatment lives in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requirements and §Composing. Minimum viable pointers for a signals agent:

-

- - **`idempotency_key`** on every mutating request (`activate_signal`, and any future mutating signals tools). Pass `createIdempotencyStore` to `createAdcpServerFromPlatform(platform, { idempotency })`.

- - **Authentication** via `serve({ authenticate })` with `verifyApiKey`/`verifyBearer` from `@adcp/sdk/server`. Unauthenticated agents fail the universal `security_baseline` storyboard.

- - **Signature-header transparency**: accept requests with `Signature-Input`/`Signature` headers even if you don't claim `signed-requests`.

-

- ## Before Writing Code

-

- Determine these four things. Ask the user — don't guess.

-

- ### 1. Marketplace or Owned?

-

- These are fundamentally different businesses.

-

- **Marketplace** — aggregates third-party data providers (LiveRamp, Oracle Data Cloud, Lotame). Each signal traces to a `data_provider_domain` that buyers can verify via `adagents.json`. `signal_type: "marketplace"`, `signal_id.source: "catalog"`.

-

- **Owned** — first-party data (retailer CDP, publisher contextual, CRM). Buyers trust your agent directly. `signal_type: "owned"` or `"custom"`, `signal_id.source: "agent"`.

-

- ### 2. What Segments?

-

- Get specifics: names, definitions, what each represents. Push for 3-5 segments with variety. Each needs:

-

- - Clear behavioral/demographic definition

- - Realistic `coverage_percentage` (typically 5-30%)

- - Value type: `binary` (in/out), `categorical` (tier levels — define the categories), or `numeric` (score range — define min/max)

-

- ### 3. Pricing

-

- At least one pricing option per signal. Signals use `VendorPricingOption` (field: `model`), distinct from product `PricingOption` (field: `pricing_model`).

-

- - `cpm` — `{ pricing_option_id: "po_cpm", model: "cpm", cpm: 2.50, currency: "USD" }`

- - `percent_of_media` — `{ pricing_option_id: "po_pom", model: "percent_of_media", percent: 15, currency: "USD" }`

- - `flat_fee` — `{ pricing_option_id: "po_flat", model: "flat_fee", amount: 5000, period: "monthly", currency: "USD" }`

-

- ### 4. Activation Destinations

-

- If implementing `activate_signal`:

-

- - **Platform** (DSP): `type: "platform"`, returns `activation_key: { type: "segment_id", segment_id: "..." }`

- - **Agent** (sales agent): `type: "agent"`, returns `activation_key: { type: "key_value", key: "...", value: "..." }`

-

- ## Tools and Required Response Shapes

-

- > **Before writing any handler's return statement, fetch [`docs/llms.txt`](../../docs/llms.txt) and grep for `#### \`<tool_name>\``(e.g.`#### \`get_signals\``) to read the exact required + optional field list.** The schema-derived contract lives there; this skill covers patterns, gotchas, and domain-specific examples. Strict response validation is on by default in dev — it will tell you the exact field path if you drift, so write the obvious thing and trust the contract.

- >

- > **Cross-cutting pitfalls matrix runs keep catching:**

- >

- > - **Declare `capabilities.specialisms: ['signal-marketplace'] as const` (or `'signal-owned'`) on the `DecisioningPlatform` you pass to `createAdcpServerFromPlatform`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.

-

- **`get_adcp_capabilities`** — auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform`. Do not register manually.

-

- **`get_signals`** — handled by `signals.getSignals`

-

- Two discovery modes — support both:

-

- 1. `signal_spec` — natural language. Match against segment names and descriptions.

- 2. `signal_ids` — exact lookup by `{ source, data_provider_domain, id }` or `{ source, agent_url, id }`.

-

- Plus filtering via `filters.catalog_types`, `filters.max_cpm`, `filters.min_coverage_percentage`, and `max_results`.

-

- ```

- getSignalsResponse({

- signals: [{

- signal_agent_segment_id: string, // required - key for activate_signal

- name: string, // required

- description: string, // required

- signal_type: 'marketplace' | 'owned' | 'custom', // required

- data_provider: string, // required - your company name

- coverage_percentage: number, // required - 0 to 100

- deployments: [], // required - empty array (not live until activated)

- pricing_options: [{ // required - at least one

- pricing_option_id: string, // required

- model: 'cpm', // required - discriminator

- cpm: number, // required for cpm model

- currency: 'USD', // required

- }],

- // signal_id is critical — shape depends on marketplace vs owned:

- signal_id: {

- source: 'catalog', // marketplace

- data_provider_domain: string, // marketplace — domain for provenance verification

- id: string, // unique segment ID

- },

- // OR for owned:

- signal_id: {

- source: 'agent', // owned

- agent_url: string, // your agent URL

- id: string,

- },

- value_type: 'binary' | 'categorical' | 'numeric', // optional but recommended

- }],

- sandbox: true, // for mock data

- })

- ```

-

- **`activate_signal`** — handled by `signals.activateSignal`

-

- Look up by `signal_agent_segment_id`. Validate `pricing_option_id`. Return deployments matching the requested destinations. **Platform activation is async; agent activation is sync** — different shape per destination type, driven by the compliance contract:

-

- ```

- activateSignalResponse({

- deployments: [

- // Platform (DSP) — ASYNC. First response returns is_live:false plus

- // an ETA AND the planned activation_key. Buyer re-sends activate_signal

- // to poll until is_live:true; final response adds deployed_at.

- {

- type: 'platform',

- platform: string,

- account: string | null, // echo from request

- is_live: false, // flips true on completion

- estimated_activation_duration_minutes: number, // present while activating

- activation_key: { type: 'segment_id', segment_id: string }, // committed up front

- deployed_at: string, // ISO; present when is_live:true

- },

- // Agent (sales-agent) — SYNC. First response is the final response.

- {

- type: 'agent',

- agent_url: string,

- is_live: true,

- activation_key: { type: 'key_value', key: string, value: string },

- deployed_at: string, // ISO timestamp

- },

- ],

- sandbox: true,

- })

- ```

-

- ### Context and Ext Passthrough

-

- The framework auto-echoes the request's `context` into every response — **do not set `context` yourself in your handler return values.** It's injected post-handler only when the field isn't already present.

-

- **Crucial:** `context` is schema-typed as an object. If your handler hand-sets a string or narrative description, validation fails with `/context: must be object` and the framework does not overwrite. Leave the field out entirely; the framework handles it.

-

- Some schemas also define an `ext` field for vendor-namespaced extensions. If your request schema includes `ext`, accept it without error. Tools with explicit `ext` support: `activate_signal`.

-

- ## SDK Quick Reference

-

- | SDK piece | Usage |

- | ----------------------------------------------------- | ------------------------------------------------------------------------------ |

- | `createAdcpServerFromPlatform(platform, opts)` | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-capabilities |

- | `createAdcpServer(config)` *(legacy)* | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5` |

- | `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp` |

- | `signals: { getSignals, activateSignal }` | Domain group — register handlers by name |

- | `ctx.store.put(collection, id, data)` | Persist state (activations, segment cache) across requests |

- | `ctx.store.get(collection, id)` | Retrieve persisted state |

- | `getSignalsResponse(data)` | Auto-applied response builder (don't call manually) |

- | `activateSignalResponse(data)` | Auto-applied response builder (don't call manually) |

- | `adcpError(code, { message })` | Structured error (`SIGNAL_NOT_FOUND`, `INVALID_DESTINATION`) |

- | `createIdempotencyStore({ backend, ttlSeconds })` | Required on every mutating tool — pass via `createAdcpServerFromPlatform(platform, { idempotency })` |

- | `memoryBackend()` / `pgBackend(pool)` | Idempotency backends (from `@adcp/sdk/server`) |

- | `type Signal = GetSignalsResponse['signals'][number]` | Type for a single signal object |

-

- Import: `import { createAdcpServerFromPlatform, serve, adcpError } from '@adcp/sdk/server';`

- Server-only: `import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';`

- Types: `import type { GetSignalsResponse } from '@adcp/sdk';`

-

- ## Setup

-

- ```bash

- npm init -y

- npm install @adcp/sdk

- npm install -D typescript @types/node

- ```

-

- Minimal `tsconfig.json`:

-

- ```json

- {

- "compilerOptions": {

- "target": "ES2022",

- "module": "Node16",

- "moduleResolution": "Node16",

- "strict": true,

- "skipLibCheck": true,

- "outDir": "dist"

- }

- }

- ```

-

- `skipLibCheck: true` avoids false-positive errors from transitive `.d.ts` files (e.g., `@opentelemetry/api`).

-

- ## Implementation

-

- 1. Single `.ts` file — all tools in one file

- 2. Use `createAdcpServerFromPlatform` with `signals: SignalsPlatform` on a typed `DecisioningPlatform` class — `get_adcp_capabilities` is auto-generated

- 3. Handlers return raw data objects — response builders (`getSignalsResponse`, `activateSignalResponse`) are auto-applied

- 4. Use `ctx.store` for persisting signal activations across requests (InMemoryStateStore by default)

- 5. Set `sandbox: true` for mock/demo data

- 6. Context passthrough is handled by the framework — no need to manually echo `args.context`

-

- ```typescript

- import {

- createAdcpServerFromPlatform,

- serve,

- AdcpError,

- createIdempotencyStore,

- memoryBackend,

- type DecisioningPlatform,

- type SignalsPlatform,

- type AccountStore,

- } from '@adcp/sdk/server';

- import type { GetSignalsResponse } from '@adcp/sdk';

-

- // Type the catalog explicitly. Each entry MUST include `signal_agent_segment_id`

- // — it's the key buyers pass to `activate_signal` and the field the framework

- // uses to auto-store the signal for hydration on the activate call. If you

- // omit it, `tsc` flags every entry; the response validator rejects the

- // `get_signals` reply at runtime in dev/test (strict mode default).

- type Signal = GetSignalsResponse['signals'][number];

- const signals: Signal[] = [

- /* your signal objects — `signal_agent_segment_id` is required on each */

- ];

-

- // Publisher-internal storage for activations. Persist to your real DB in

- // production; this Map is for the worked example. Note: a module-level Map

- // is fine for single-tenant agents but leaks across tenants in a

- // multi-tenant deployment — partition by `account.id` if you front many.

- const activations = new Map<string, { destinations: unknown[]; activated_at: string }>();

-

- // Idempotency — required for v3 compliance. `activate_signal` is mutating;

- // `get_signals` is read-only and exempt from key validation.

- const idempotency = createIdempotencyStore({

- backend: memoryBackend(), // pgBackend(pool) for production

- ttlSeconds: 86400, // 24 hours (spec bounds: 1h–7d)

- });

-

- class MySignals implements DecisioningPlatform {

- capabilities = {

- specialisms: ['signal-marketplace'] as const,

- config: {},

- };

-

- // Single-tenant agent: AccountStore.resolve returns the same synthetic

- // account every request. `upsert` and `list` are optional — omit them on

- // stateless platforms (the framework returns `UNSUPPORTED_FEATURE` to

- // buyers calling `sync_accounts` / `list_accounts`).

- accounts: AccountStore = {

- resolve: async () => ({

- id: 'sg_acc_1',

- operator: 'me',

- ctx_metadata: {},

- }),

- };

-

- signals: SignalsPlatform = {

- getSignals: async params => {

- let results = signals;

- if (params.signal_spec) {

- const query = params.signal_spec.toLowerCase();

- results = results.filter(

- s => s.name.toLowerCase().includes(query) || s.description.toLowerCase().includes(query)

- );

- }

- if (params.signal_ids) {

- results = results.filter(s => params.signal_ids!.some(id => id.id === s.signal_id.id));

- }

- return { signals: results, sandbox: true };

- },

-

- activateSignal: async params => {

- const signal = signals.find(s => s.signal_agent_segment_id === params.signal_agent_segment_id);

- // Throw `AdcpError` for buyer-fixable rejection. The framework

- // catches the throw, projects to the spec's error envelope, and

- // returns it to the buyer. Returning `adcpError(...)` from the

- // success arm doesn't typecheck — `activateSignal` is declared

- // `Promise<ActivateSignalSuccess>`, error is the throw path.

- if (!signal) {

- throw new AdcpError('SIGNAL_NOT_FOUND', {

- recovery: 'correctable',

- message: `Unknown segment: ${params.signal_agent_segment_id}`,

- });

- }

- // Persist activation. Single-tenant: module-level Map is fine.

- // Multi-tenant: partition by ctx.account.id (passed as 2nd arg).

- activations.set(params.signal_agent_segment_id, {

- destinations: params.destinations,

- activated_at: new Date().toISOString(),

- });

- // Platform (DSP) activation is ASYNC per spec — return `is_live: false`

- // with `estimated_activation_duration_minutes`. The buyer polls

- // (a subsequent `activate_signal` with the same destinations, or a

- // provider-specific status tool) until `is_live: true`.

- //

- // Agent (sales-agent) activation is SYNC — return `is_live: true` with

- // `activation_key.type: 'key_value'` and a `deployed_at` timestamp.

- //

- // Both shapes include `activation_key` so the buyer knows how to

- // reference the segment when building media buys through the DSP or SA.

- const deployments = params.destinations.map(dest => {

- if (dest.type === 'platform') {

- return {

- type: 'platform' as const,

- platform: dest.platform,

- is_live: false,

- estimated_activation_duration_minutes: 30,

- // Return activation_key even while is_live is false — the

- // buyer needs to know the planned segment_id now so it can

- // reference it in downstream media buys. `is_live` just

- // flags whether the DSP has confirmed provisioning;

- // `activation_key` is the agent's commitment.

- activation_key: {

- type: 'segment_id' as const,

- segment_id: `${dest.platform}_${signal.signal_id.id}`,

- },

- };

- }

- return {

- type: 'agent' as const,

- agent_url: dest.agent_url,

- is_live: true,

- activation_key: { type: 'key_value' as const, key: 'audience', value: signal.signal_id.id },

- deployed_at: new Date().toISOString(),

- };

- });

- return { deployments, sandbox: true };

- },

- };

- }

- const platform = new MySignals();

- serve(() =>

- createAdcpServerFromPlatform(platform, {

- name: 'My Signals Agent',

- version: '1.0.0',

- idempotency,

- // Principal scoping for idempotency. MUST never return undefined.

- resolveSessionKey: () => 'default-principal',

- })

- );

- ```

- ## Idempotency

- AdCP v3 requires an `idempotency_key` on every mutating request — for signals agents that's `activate_signal` only (`get_signals` is read-only and exempt). Idempotency is already wired in the Implementation example above. The framework then handles:

- - Missing/malformed key → `INVALID_REQUEST` (spec pattern `^[A-Za-z0-9_.:-]{16,255}$`)

- - JCS-canonicalized payload hashing with same-key-different-payload → `IDEMPOTENCY_CONFLICT` (no payload leaked in the error body)

- - Past-TTL replay → `IDEMPOTENCY_EXPIRED` (±60s clock-skew tolerance)

- - Cache hits replay the cached envelope with `replayed: true` injected

- - `adcp.idempotency.replay_ttl_seconds` auto-declared on `get_adcp_capabilities`

- - Only successful responses cache — a failed activation re-executes on retry

- - Atomic claim so concurrent retries with a fresh key don't all race to activate

- Scoping is per-principal via `resolveSessionKey` (override with `resolveIdempotencyPrincipal` for custom scoping). `ttlSeconds` must be 3600–604800 — out of range throws at construction. If you register mutating handlers without wiring `idempotency`, the framework logs an error at server-creation time.

- **Critical: probe the pool at boot (pgBackend).** `pg.Pool` is lazy — `new Pool({ connectionString })` does not validate the URL. A bad `DATABASE_URL` lets the server start, advertise `IdempotencySupported`, and then silently fail every `activate_signal` call. Wire `readinessCheck` on `serve()` so the server never accepts traffic with a broken pool:

- ```ts

- const store = createIdempotencyStore({ backend: pgBackend(pool), ttlSeconds: 86400 });

- pool.on('error', err => console.error('pg pool error', err)); // prevent crash on idle-client errors

- serve(createAgent, {

- readinessCheck: () => store.probe(), // throws with a descriptive error if pool/table is broken

- });

- ```

- ## Protecting your agent

- **An AdCP agent that accepts unauthenticated requests is non-compliant** (see `security_baseline` in the universal storyboard bundle). Ask the operator: "API key, OAuth, or both?" — then wire one of these into `serve()`.

- ```typescript

- import { serve } from '@adcp/sdk';

- import { verifyApiKey, verifyBearer, anyOf } from '@adcp/sdk/server';

- // API key — simplest, good for B2B integrations

- serve(createAgent, {

- authenticate: verifyApiKey({

- verify: async token => {

- const row = await db.api_keys.findUnique({ where: { token } });

- return row ? { principal: row.account_id } : null;

- },

- }),

- });

- // OAuth — best when buyers authenticate as themselves

- const AGENT_URL = 'https://my-agent.example.com/mcp';

- serve(createAgent, {

- publicUrl: AGENT_URL, // canonical RFC 8707 audience — also served as `resource` in protected-resource metadata

- authenticate: verifyBearer({

- jwksUri: 'https://auth.example.com/.well-known/jwks.json',

- issuer: 'https://auth.example.com',

- audience: AGENT_URL, // MUST equal publicUrl

- }),

- protectedResource: { authorization_servers: ['https://auth.example.com'] },

- });

- // Both

- serve(createAgent, {

- publicUrl: AGENT_URL,

- authenticate: anyOf(verifyApiKey({ verify: lookupKey }), verifyBearer({ jwksUri, issuer, audience: AGENT_URL })),

- protectedResource: { authorization_servers: [issuer] },

- });

- ```

- The framework produces RFC 6750-compliant `WWW-Authenticate: Bearer` 401s on failure, and serves `/.well-known/oauth-protected-resource<mountPath>` with `publicUrl` as the `resource` field so buyers get tokens bound to the right audience. The default JWT allowlist is asymmetric-only (RS*/ES*/PS\*/EdDSA) to prevent algorithm-confusion attacks.

- ## Validate Locally

- **Full validation checklist:** [docs/guides/VALIDATE-YOUR-AGENT.md](../../docs/guides/VALIDATE-YOUR-AGENT.md). Signals-specific commands:

- # Boot

- npx tsx agent.ts &

-

- # Happy path — the specialism you're claiming

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp signal_owned --auth $TOKEN # owned data

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp signal_marketplace --auth $TOKEN # marketplace

-

- # Marketplace governance sub-scenario (if you claim signal_marketplace)

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp signal_marketplace/governance_denied --auth $TOKEN

-

- # Cross-cutting obligations

- npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \

- --storyboards security_baseline,idempotency,schema_validation,error_compliance --auth $TOKEN

-

- # Rejection-surface fuzz

- npx @adcp/sdk@latest fuzz http://localhost:3001/mcp --tools get_signals --auth-token $TOKEN

- ```

-

- Common failure decoder:

-

- - `value_type` mismatch → `binary` vs. `continuous` — pick one; continuous signals return `value`, binary signals return membership

- - Missing `deployments` on signal → required even if empty `[]`

- - `activate_signal` returns sync success on a marketplace signal → marketplace activations are async; commit to an `activation_key` up-front and return `submitted`

- - Missing `coverage_percentage` or `pricing_options` → required on every signal

-

- **Keep iterating until all steps pass.** Can't bind ports? `npm run compliance:skill-matrix -- --filter signals` runs an isolated end-to-end test.

-

- ## Common Mistakes

-

- | Mistake | Fix |

- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |

- | Using `createTaskCapableServer` + `server.tool()` | Use `createAdcpServerFromPlatform` with `signals: SignalsPlatform` on a typed `DecisioningPlatform` class |

- | Calling `createAdcpServer` directly in new code | Reach for `createAdcpServerFromPlatform`; `createAdcpServer` lives at `@adcp/sdk/server/legacy/v5` for mid-migration / escape-hatch only |

- | Using module-level Maps for state | Use `ctx.store.put/get` — framework provides `InMemoryStateStore` by default |

- | Manually registering `get_adcp_capabilities` | Auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform` |

- | Calling response builders manually | Handlers return raw data — `getSignalsResponse`/`activateSignalResponse` are auto-applied |

- | Missing `signal_agent_segment_id` on signals | Buyers can't activate without it |

- | Wrong `signal_id` shape | Marketplace: `{ source: "catalog", data_provider_domain, id }`. Owned: `{ source: "agent", agent_url, id }` |

- | Missing `data_provider` field | Required on every signal — your company/brand name |

- | Empty `pricing_options` array | Must have at least one pricing option per signal |

- | `is_live: true` in get_signals deployments | Signals aren't live until `activate_signal` — use empty `deployments: []` |

- | Activation doesn't match destination type | If request has `type: "platform"`, deployment must be `type: "platform"` |

- | `sandbox: false` on mock data | Buyers may treat mock data as real |

-

- ## Specialism Details

-

- ### <a name="specialism-signal-marketplace"></a>signal-marketplace

-

- **Async platform activation.** Unlike agent activations (`type: 'agent'`), platform activations (`type: 'platform'`) are not instant — the segment takes minutes-to-hours to propagate to the DSP. Return `is_live: false` with an estimate, then the buyer polls `activate_signal` again until `is_live: true`.

-

- ```typescript

- activateSignal: async (params, ctx) => {

- const signal = signals.find((s) => s.signal_agent_segment_id === params.signal_agent_segment_id);

- if (!signal) return adcpError('SIGNAL_NOT_FOUND', { message: `Unknown segment` });

-

- const deployments = await Promise.all(params.destinations.map(async (dest) => {

- if (dest.type === 'platform') {

- // Async — check whether this destination has already been propagated

- const existing = await ctx.store.get('deployments', `${params.signal_agent_segment_id}:${dest.platform}`);

- if (existing?.is_live) return existing;

- if (!existing) {

- const pending = {

- type: 'platform' as const,

- platform: dest.platform,

- account: dest.account ?? null,

- is_live: false,

- estimated_activation_duration_minutes: 45,

- // Commit the activation_key up front so the buyer can trust it across the poll window:

- activation_key: {

- type: 'segment_id' as const,

- segment_id: `${dest.platform}_${signal.signal_id.id}`,

- },

- };

- await ctx.store.put('deployments', `${params.signal_agent_segment_id}:${dest.platform}`, pending);

- return pending;

- }

- return existing; // still propagating

- }

- // Agent activations are instant

- return {

- type: 'agent' as const,

- agent_url: dest.agent_url,

- is_live: true,

- deployed_at: new Date().toISOString(),

- activation_key: { type: 'key_value' as const, key: 'audience', value: signal.signal_id.id },

- };

- }));

- return { deployments, sandbox: true };

- },

- ```

-

- Use `forceDeploymentStatus` in your `TestControllerStore` (if you implement compliance_testing) to flip pending deployments to live for deterministic tests.

-

- **Provenance.** `data_provider_domain` must be resolvable — buyers fetch `https://{domain}/adagents.json` out-of-band to verify the provider. Use real domains even in demos, not `example.com`. For a marketplace demo, seed ≥2 different `data_provider_domain` values so the multi-provider nature is visible.

-

- ### <a name="specialism-signal-owned"></a>signal-owned

-

- **Value types** drive targeting semantics. The storyboard validates these fields:

-

- ```typescript

- // Binary — in/out of the segment

- { value_type: 'binary' as const }

-

- // Categorical — enumerated tier/level

- {

- value_type: 'categorical' as const,

- allowed_values: ['bronze', 'silver', 'gold', 'platinum'], // required for categorical

- }

- // Numeric — continuous score or count

- {

- value_type: 'numeric' as const,

- min: 0,

- max: 100,

- units: 'purchase_frequency_last_90d', // optional but recommended

- }

- `signal_type: 'custom'` is for first-party signals that don't fit the `owned` conceptual model (e.g. contextual signals derived from page content rather than user identity). Use `owned` by default; pick `custom` only when the user data model differs materially.

-

- Platform activations are async (same pattern as marketplace). Agent activations include `deployed_at`:

- ```typescript

- {

- type: 'agent' as const,

- agent_url: dest.agent_url,

- is_live: true,

- deployed_at: new Date().toISOString(),

- activation_key: { type: 'key_value' as const, key: 'audience', value: signal.signal_id.id },

- }

- ```

- ## Reference

- - `examples/signals-agent.ts` — complete runnable example

- - `storyboards/signal_marketplace.yaml` — buyer call sequences for marketplace agent

- - `storyboards/signal_owned.yaml` — call sequences for owned data agent

- - `docs/guides/BUILD-AN-AGENT.md` — SDK patterns

- - `docs/TYPE-SUMMARY.md` — curated type signatures

- - `docs/llms.txt` — full protocol reference