build-signals-agent

Build a Signals Agent

A signals agent serves audience and contextual targeting segments to buyer agents. The fastest path to a passing agent is to fork the worked adapter and replace its // SWAP: markers with calls to your backend.

Pick your fork target

Specialism	Archetype	Fork this	Mock upstream	Storyboard
signal-marketplace	Multi-provider data marketplace (Oracle Data Cloud, LiveRamp, third-party data)	hello_signals_adapter_marketplace.ts	npx adcp mock-server signal-marketplace	signal_marketplace
signal-owned	First-party / single-provider data (CDP, identity provider, contextual)	Fork the marketplace adapter; see deletion list below	—	signal_owned

Both specialisms share the same tool surface (get_signals, activate_signal, list_accounts); the difference is whether you serve segments from multiple data_provider_domain values or one. A signal-owned adapter is the marketplace adapter with the multi-provider directory simplified to a single seed.

What to delete if you're single-specialism signal-owned

Forking the marketplace adapter for a signal-owned agent? Delete or replace these seams — leaning on stable symbol names rather than line numbers (the adapter evolves; greppable identifiers don't):

• Replace the multi-provider seed (the UpstreamCohort array seeded with multiple data_provider_domain / data_provider_id / data_provider_name triples) with your single-provider catalog. Every cohort gets the same data_provider_domain (your domain) and data_provider_name (your brand).
• Strip the marketplace-discovery code paths in getSignals that filter signals[] by (data_provider_domain, data_provider_id) pairs — single-provider adopters either return everything or filter on signal id alone.
• Set signal_type: 'owned' (not 'marketplace') in the toAdcpSignal projection. See SHAPE-GOTCHAS §7 for the marketplace/owned/custom decision table.
• Drop the marketplace governance sub-scenario in your storyboard run if you don't model multi-provider consent flows — signal_owned storyboard is simpler.

Keep: the accounts / createTenantStore block (single-tenant adapters pass one tenant entry), agentRegistry, the signals SignalsPlatform block (getSignals, activateSignal, listAccounts), platform vs agent activation polling logic, forceDeploymentStatus for compliance-test determinism.

For exact response shapes, error codes, and optional fields, docs/llms.txt is the canonical reference. The fork target stays in sync with the spec because PR #1394's three-gate contract fails CI when it drifts.

When to use this skill

• User wants to serve audience segments, identity data, or contextual targeting to buyers
• User mentions get_signals, activate_signal, or the AdCP signals protocol
• User describes themselves as a CDP, DMP, identity provider, or data marketplace

Not this skill:

• Selling ad inventory → skills/build-seller-agent/
• Audience push (sync to a walled garden) → that's the audience-sync track in skills/build-seller-agent/

Cross-cutting rules

Every signals agent hits the cross-cutting rules in ../cross-cutting.md. The high-traffic ones for signals (deep-linked to the rule):

• idempotency_key on activate_signal
• Authentication — serve({ authenticate }) baseline
• Resolve-then-authorize — byte-equivalent errors on signal_agent_segment_id lookups across tenants
• Webhooks — for async platform-activation completions, use signal_activation.${signal_agent_segment_id}.${platform} as the stable operation_id

Two signals-specific notes on top of those:

Async platform activation

Platform activations (type: 'platform') take minutes-to-hours to propagate to the DSP. Return is_live: false with estimated_activation_duration_minutes on first call; the buyer polls activate_signal again until is_live: true. Commit activation_key up front so the buyer can trust it across the poll window. Agent activations (type: 'agent') are instant — return is_live: true immediately.

forceDeploymentStatus in your TestControllerStore flips pending deployments to live for deterministic compliance tests.

Provenance — data_provider_domain must resolve

Buyers fetch https://{domain}/adagents.json out-of-band to verify the provider. Use real domains even in demos, not example.com. For marketplace adopters, seed ≥2 different data_provider_domain values so the multi-provider nature is visible to the storyboard.

Specialism deltas at a glance

signal-marketplace — multi-provider directory (signals[].data_provider_domain varies), platform-activation polling pattern, marketplace governance sub-scenario in the storyboard exercises consent flows.

signal-owned — single data_provider_domain across all signals. value_type drives targeting semantics: binary (in/out), categorical (with allowed_values: [...]), numeric (with min, max, optional units). For the signal_type value (marketplace/owned/custom) decision, see SHAPE-GOTCHAS §7.

Validate locally

# Run the fork-matrix gate
npm run compliance:fork-matrix -- --test-name-pattern="hello-signals-adapter-marketplace"

# Or validate your forked agent directly against its storyboard
adcp storyboard run http://127.0.0.1:3001/mcp signal_marketplace \
  --bearer "$ADCP_AUTH_TOKEN" --include-bundles --json

The fork-matrix gate is the three-gate contract from docs/guides/EXAMPLE-TEST-CONTRACT.md: tsc strict / storyboard zero-failures / upstream façade.

For deeper validation: docs/guides/VALIDATE-YOUR-AGENT.md.

Migration notes

• 6.6 → 6.7: docs/migration-6.6-to-6.7.md
• 4.x → 5.x: docs/migration-4.x-to-5.x.md