@adcp/client 4.22.1 → 4.24.0

package/skills/build-signals-agent/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: build-signals-agent
+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.
+---
+
+# Build a Signals Agent
+
+## 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.
+
+## 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`
+
+## 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:
+- `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
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['signals'],
+})
+```
+
+**`get_signals`** — `GetSignalsRequestSchema.shape`
+
+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`.
+
+```
+taskToolResponse({
+  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`** — `ActivateSignalRequestSchema.shape`
+
+Look up by `signal_agent_segment_id`. Validate `pricing_option_id`. Return deployments matching the requested destinations.
+
+```
+taskToolResponse({
+  deployments: [{
+    // Match the destination type from the request:
+    type: 'platform',              // for platform destinations
+    platform: string,              // echo from request destination
+    account: string | null,        // echo from request
+    is_live: true,                 // signal is now active
+    activation_key: {
+      type: 'segment_id',
+      segment_id: string,          // platform-specific segment ID
+    },
+  }],
+  // OR for agent destinations:
+  deployments: [{
+    type: 'agent',
+    agent_url: string,
+    is_live: true,
+    activation_key: {
+      type: 'key_value',
+      key: string,
+      value: string,
+    },
+  }],
+  sandbox: true,
+})
+```
+
+## SDK Quick Reference
+
+| SDK piece | Usage |
+|-----------|-------|
+| `serve(createAgent)` | Start HTTP server on `:3001/mcp` |
+| `createTaskCapableServer(name, version, { taskStore })` | Create MCP server with task support |
+| `server.tool(name, Schema.shape, handler)` | Register tool — `.shape` unwraps Zod |
+| `capabilitiesResponse(data)` | Build `get_adcp_capabilities` response |
+| `taskToolResponse(data, summary)` | Build tool response |
+| `adcpError(code, { message })` | Structured error (`SIGNAL_NOT_FOUND`, `INVALID_DESTINATION`) |
+| `GetSignalsRequestSchema.shape` | Zod schema for get_signals input |
+| `ActivateSignalRequestSchema.shape` | Zod schema for activate_signal input |
+| `type Signal = GetSignalsResponse['signals'][number]` | Type for a single signal object |
+
+Import everything from `@adcp/client`. Types from `@adcp/client` with `import type`.
+
+## Implementation
+
+1. Single `.ts` file — all tools in one file
+2. Always register `get_adcp_capabilities` as the **first** tool with empty `{}` schema
+3. Use `Schema.shape` (not `Schema`) when registering tools
+4. Set `sandbox: true` for mock/demo data
+5. Use `ServeContext` pattern: `function createAgent({ taskStore }: ServeContext)`
+
+The skill contains everything you need. Do not read additional docs before writing code.
+
+## Validation
+
+**After writing the agent, validate it. Fix failures. Repeat.**
+
+**Full validation** (if you can bind ports):
+```bash
+npx tsx agent.ts &
+npx @adcp/client storyboard run http://localhost:3001/mcp signal_owned --json       # for owned data
+npx @adcp/client storyboard run http://localhost:3001/mcp signal_marketplace --json  # for marketplace
+```
+
+**Sandbox validation** (if ports are blocked):
+```bash
+npx tsc --noEmit agent.ts
+```
+
+**Keep iterating until all steps pass.**
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Pass `Schema` instead of `Schema.shape` | MCP SDK needs unwrapped Zod fields |
+| Skip `get_adcp_capabilities` | Must be the first tool registered |
+| 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 |
+
+## 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/llms.txt` — full protocol reference

package/storyboards/audience_sync.yaml

@@ -1,8 +1,8 @@
 id: audience_sync
 version: "1.0.0"
 title: "Audience sync"
-category: audiences
-summary: "Tests sync_audiences: account discovery, audience creation with hashed identifiers, and audience deletion."
+category: audience_sync
+summary: "Full audience lifecycle: account discovery, audience creation with hashed identifiers, and audience deletion."
 track: audiences
 required_tools:
   - sync_audiences
@@ -10,6 +10,7 @@ platform_types:
   - display_ad_server
   - social_platform
   - retail_media
+  - audio_platform
   - dsp
   - pmax_platform
 
@@ -53,20 +54,14 @@ phases:
       - id: discover_account
         title: "Discover or create account"
         narrative: |
-          List existing accounts to find one suitable for audience sync. If no accounts
-          exist, sync_accounts creates one. The account_id is captured for use in
+          List existing accounts to find one suitable for audience sync. The account
+          must already exist and be active. The account_id is captured for use in
           subsequent audience operations.
         task: list_accounts
         schema_ref: "account/list-accounts-request.json"
         response_schema_ref: "account/list-accounts-response.json"
         doc_ref: "/accounts/tasks/list_accounts"
-        comply_scenario: account_setup
         stateful: false
-        context_outputs:
-          - name: account_id
-            path: "accounts[0].account_id"
-          - name: account_ref
-            path: "accounts[0]"
         expected: |
           Return at least one account with:
           - account_id: platform-assigned identifier
@@ -98,14 +93,11 @@ phases:
           already exist on the platform for this account. This is a read-only
           discovery call.
         task: sync_audiences
-        schema_ref: "audience/sync-audiences-request.json"
-        response_schema_ref: "audience/sync-audiences-response.json"
-        doc_ref: "/audiences/tasks/sync_audiences"
-        comply_scenario: audience_sync
+        schema_ref: "media-buy/sync-audiences-request.json"
+        response_schema_ref: "media-buy/sync-audiences-response.json"
+        doc_ref: "/media-buy/task-reference/sync_audiences"
+        comply_scenario: sync_audiences
         stateful: false
-        context_outputs:
-          - name: existing_audience_count
-            path: "audiences.length"
         expected: |
           Return existing audiences for the account (may be empty).
           Each audience should have an audience_id and status.
@@ -127,14 +119,11 @@ phases:
           matches identifiers against their user graph and returns the audience with
           action: created, match counts, and match rate.
         task: sync_audiences
-        schema_ref: "audience/sync-audiences-request.json"
-        response_schema_ref: "audience/sync-audiences-response.json"
-        doc_ref: "/audiences/tasks/sync_audiences"
-        comply_scenario: audience_sync
+        schema_ref: "media-buy/sync-audiences-request.json"
+        response_schema_ref: "media-buy/sync-audiences-response.json"
+        doc_ref: "/media-buy/task-reference/sync_audiences"
+        comply_scenario: sync_audiences
         stateful: true
-        context_outputs:
-          - name: test_audience_id
-            path: "audiences[0].audience_id"
         expected: |
           Accept the audience and return:
           - audience_id: matches the submitted ID
@@ -151,7 +140,7 @@ phases:
             operator: "pinnacle-agency.com"
           audiences:
             - audience_id: "adcp-test-audience-001"
-              name: "AdCP E2E Test Audience"
+              name: "AdCP test audience"
               add:
                 - hashed_email: "a000000000000000000000000000000000000000000000000000000000000000"
                 - hashed_phone: "b000000000000000000000000000000000000000000000000000000000000000"
@@ -172,10 +161,10 @@ phases:
           Clean up by deleting the test audience. The seller should acknowledge the
           deletion with action: deleted.
         task: sync_audiences
-        schema_ref: "audience/sync-audiences-request.json"
-        response_schema_ref: "audience/sync-audiences-response.json"
-        doc_ref: "/audiences/tasks/sync_audiences"
-        comply_scenario: audience_sync
+        schema_ref: "media-buy/sync-audiences-request.json"
+        response_schema_ref: "media-buy/sync-audiences-response.json"
+        doc_ref: "/media-buy/task-reference/sync_audiences"
+        comply_scenario: sync_audiences
         stateful: true
         expected: |
           Delete the test audience and return:

package/storyboards/behavioral_analysis.yaml

@@ -1,8 +1,8 @@
 id: behavioral_analysis
 version: "1.0.0"
 title: "Behavioral analysis"
-category: products
-summary: "Validates product discovery behavior, response consistency, and pricing edge cases."
+category: behavioral_analysis
+summary: "Validates product discovery behavior: brief filtering, response consistency, and pricing edge cases."
 track: products
 required_tools:
   - get_products
@@ -13,7 +13,6 @@ platform_types:
   - retail_media
   - search_platform
   - audio_platform
-  - linear_tv_platform
   - dsp
   - pmax_platform
   - ai_ad_network
@@ -54,7 +53,7 @@ prerequisites:
 
 phases:
   - id: behavior_analysis
-    title: "Behavior analysis"
+    title: "Brief filtering behavior"
     narrative: |
       Tests whether the agent filters products based on the brief content. Two different
       briefs are sent — one narrow (podcast audio only) and one broad (all products across
@@ -73,18 +72,13 @@ phases:
         doc_ref: "/media-buy/task-reference/get_products"
         comply_scenario: behavior_analysis
         stateful: false
-        context_outputs:
-          - name: narrow_product_ids
-            path: "products[*].product_id"
-          - name: narrow_product_count
-            path: "products.length"
         expected: |
-          Return products matching the narrow brief. The result set should be scoped
-          to audio/podcast inventory if the agent performs brief filtering.
+          Return products matching the narrow brief. If the agent interprets briefs,
+          this should return fewer products than a broad request.
 
         sample_request:
           buying_mode: "brief"
-          brief: "Looking specifically for podcast audio advertising only"
+          brief: "Podcast audio advertising only — 30-second pre-roll spots"
           brand:
             domain: "acmeoutdoor.com"
 
@@ -98,9 +92,9 @@ phases:
       - id: get_products_broad
         title: "Get products with broad brief"
         narrative: |
-          Send a broad brief requesting all products across all channels. Compare the
-          result count against the narrow brief to determine whether the agent filters
-          by brief content.
+          Send a broad brief requesting all available products. Compare the result count
+          with the narrow brief — if the agent filters by brief, the broad request should
+          return more products.
         task: get_products
         schema_ref: "media-buy/get-products-request.json"
         response_schema_ref: "media-buy/get-products-response.json"
@@ -108,69 +102,56 @@ phases:
         comply_scenario: behavior_analysis
         stateful: false
         expected: |
-          Return all available products. If the agent performs brief filtering, this
-          response should contain more products than the narrow brief response.
+          Return all available products. The product count should be greater than or
+          equal to the narrow brief response.
 
         sample_request:
           buying_mode: "brief"
-          brief: "Show all products across all channels and formats"
+          brief: "Show me everything — all channels, all formats, all inventory"
           brand:
             domain: "acmeoutdoor.com"
 
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains a products array"
-          - check: compare_context
-            description: "Broad brief returns >= narrow brief product count"
-            context_ref: narrow_product_count
-            comparison: ">="
 
   - id: response_consistency
     title: "Response consistency"
     narrative: |
-      Calls get_products twice with the identical brief and brand. The agent should
-      return the same product IDs both times. Non-deterministic responses indicate
-      randomness in product selection or caching issues.
+      Tests whether the agent returns deterministic results for identical inputs.
+      The same brief is sent twice — the response should contain the same product IDs
+      in both cases.
 
     steps:
       - id: get_products_first
-        title: "First call with fixed brief"
+        title: "First request with identical brief"
         narrative: |
-          Send a specific brief and capture the returned product IDs for comparison.
+          Send a brief and capture the product IDs returned.
         task: get_products
         schema_ref: "media-buy/get-products-request.json"
         response_schema_ref: "media-buy/get-products-response.json"
         doc_ref: "/media-buy/task-reference/get_products"
         comply_scenario: response_consistency
         stateful: false
-        context_outputs:
-          - name: first_call_product_ids
-            path: "products[*].product_id"
         expected: |
-          Return products matching the brief. Product IDs are captured for comparison
-          with a second identical call.
+          Return products matching the brief. Product IDs will be compared with a
+          subsequent identical request.
 
         sample_request:
           buying_mode: "brief"
-          brief: "Premium video inventory on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          brief: "Premium video inventory on sports publishers. Adults 25-54."
           brand:
             domain: "acmeoutdoor.com"
 
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products[0].product_id"
-            description: "At least one product returned with a product_id"
 
       - id: get_products_second
-        title: "Second call with identical brief"
+        title: "Second request with identical brief"
         narrative: |
-          Repeat the exact same request. The returned product IDs should match
-          those from the first call.
+          Send the exact same brief again. The returned product IDs should match the
+          first response.
         task: get_products
         schema_ref: "media-buy/get-products-request.json"
         response_schema_ref: "media-buy/get-products-response.json"
@@ -178,37 +159,31 @@ phases:
         comply_scenario: response_consistency
         stateful: false
         expected: |
-          Return the same product IDs as the first call. Consistent responses
-          for identical inputs are expected.
+          Return the same product IDs as the first request. Deterministic responses
+          are expected for identical inputs.
 
         sample_request:
           buying_mode: "brief"
-          brief: "Premium video inventory on sports and outdoor lifestyle publishers. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          brief: "Premium video inventory on sports publishers. Adults 25-54."
           brand:
             domain: "acmeoutdoor.com"
 
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
-          - check: match_context
-            description: "Product IDs match the first call"
-            context_ref: first_call_product_ids
-            path: "products[*].product_id"
 
   - id: pricing_edge_cases
-    title: "Pricing edge cases"
+    title: "Pricing structure validation"
     narrative: |
-      Validates the structure of pricing_options on returned products. Each product
-      should declare a delivery_type (guaranteed or non_guaranteed) and well-formed
-      pricing options with recognized fields.
+      Validates that products declare well-formed pricing_options with recognized
+      delivery_type values and complete pricing structures.
 
     steps:
       - id: get_products_pricing
-        title: "Fetch products for pricing analysis"
+        title: "Validate pricing structures"
         narrative: |
-          Request all products with pricing details. Validate that each product has
-          a valid delivery_type and that pricing_options contain recognized fields
-          (fixed_price, floor_price, price_guidance, min_spend_per_package).
+          Send a brief and inspect the pricing structures on returned products.
+          Every product must have a recognized delivery_type and valid pricing_options.
         task: get_products
         schema_ref: "media-buy/get-products-request.json"
         response_schema_ref: "media-buy/get-products-response.json"
@@ -216,29 +191,22 @@ phases:
         comply_scenario: pricing_edge_cases
         stateful: false
         expected: |
-          Return products with well-formed pricing structures:
-          - Each product has a delivery_type: guaranteed or non_guaranteed
-          - Each pricing_option has a pricing_option_id
-          - Pricing fields are valid (no negative values, recognized pricing models)
+          Products with valid pricing structures:
+          - delivery_type: "guaranteed" or "non_guaranteed"
+          - pricing_options with pricing_option_id and pricing_model
 
         sample_request:
           buying_mode: "brief"
-          brief: "Show all products with pricing details"
+          brief: "All available products with detailed pricing"
           brand:
             domain: "acmeoutdoor.com"
 
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
-          - check: field_present
-            path: "products"
-            description: "Response contains products array"
           - check: field_present
             path: "products[0].delivery_type"
-            description: "Each product declares guaranteed or non_guaranteed delivery"
-          - check: field_value
-            path: "products[*].delivery_type"
-            allowed_values:
-              - "guaranteed"
-              - "non_guaranteed"
-            description: "delivery_type is a recognized value"
+            description: "Products declare delivery_type"
+          - check: field_present
+            path: "products[0].pricing_options"
+            description: "Products include pricing_options"