@adcp/client 4.20.0 → 4.22.0

package/storyboards/signal_owned.yaml

@@ -0,0 +1,211 @@
+id: signal_owned
+version: "1.0.0"
+title: "Owned signal agent"
+category: signal_owned
+summary: "Signal agent serving first-party or proprietary audience data without external catalog verification."
+platform_types:
+  - retail_media
+  - social_platform
+  - pmax_platform
+
+track: signals
+required_tools:
+  - get_signals
+narrative: |
+  You operate a first-party data platform — a retailer CDP, publisher contextual data
+  provider, or proprietary audience platform. Your signals are agent-native: they come
+  from your own data, not from third-party catalogs.
+
+  Buyers trust your agent directly. There's no external adagents.json to verify against —
+  provenance is the agent itself. This simplifies the flow: discovery and activation,
+  without the verification step that marketplace agents require.
+
+  Owned signal agents often have richer signal types. A retailer might expose purchase
+  frequency as a numeric signal (0-30 visits/month) or loyalty tier as categorical
+  (platinum/gold/silver/bronze). A publisher might expose content category, subscriber
+  tenure, or engagement scores.
+
+  This storyboard walks through discovery and both activation patterns.
+
+agent:
+  interaction_model: owned_signals
+  capabilities: []
+  examples:
+    - "Retailer CDPs (e.g., loyalty and purchase data)"
+    - "Publisher contextual platforms (e.g., content category, subscriber data)"
+    - "First-party audience platforms (e.g., CRM-derived segments)"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The buyer has a campaign brief with targeting objectives. The test kit provides
+    sample owned signal definitions with various value types (binary, categorical,
+    numeric) and pricing models.
+  test_kit: "test-kits/nova-motors.yaml"
+
+phases:
+  - id: discovery
+    title: "Signal discovery"
+    narrative: |
+      The buyer describes targeting objectives and your agent returns matching signals
+      from your proprietary data. Unlike marketplace agents, these signals have
+      signal_type "owned" — provenance is the agent itself.
+
+      Owned signals often include richer value types. A retailer can expose loyalty
+      tiers as categorical signals and purchase frequency as numeric signals, giving
+      buyers more precise targeting than binary include/exclude.
+
+    steps:
+      - id: search_owned_signals
+        title: "Discover owned signals"
+        narrative: |
+          The buyer searches for audience segments using a natural language description.
+          Your agent returns signals from your proprietary data — loyalty tiers, purchase
+          history, engagement scores, contextual categories.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        stateful: false
+        expected: |
+          Return matching signals from your proprietary data. Each signal must include:
+          - signal_agent_segment_id for activation
+          - signal_id with source: "agent_native"
+          - name, description, and value_type
+          - coverage_percentage
+          - pricing_options
+          - signal_type: "owned"
+
+          For categorical signals, include the allowed_values.
+          For numeric signals, include the range (min/max).
+
+        sample_request:
+          signal_spec: "High-value customers likely to purchase electronics, with loyalty program data"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+          - check: field_present
+            path: "signals[0].signal_agent_segment_id"
+            description: "Each signal has a signal_agent_segment_id"
+          - check: field_present
+            path: "signals[0].pricing_options"
+            description: "Each signal has pricing options"
+
+      - id: filter_by_criteria
+        title: "Filter signals by criteria"
+        narrative: |
+          The buyer narrows the search using filters — maximum CPM, specific signal
+          types, or coverage thresholds. This tests that your agent handles filter
+          parameters correctly and returns only matching signals.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        stateful: false
+        expected: |
+          Return only signals matching the filter criteria. If no signals match,
+          return an empty signals array — not an error.
+
+        sample_request:
+          signal_spec: "Purchase behavior signals"
+          filters:
+            max_cpm: 5.00
+
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+          - check: field_present
+            path: "signals"
+            description: "Response contains a signals array"
+
+  - id: platform_activation
+    title: "Activate on a DSP"
+    narrative: |
+      The buyer activates a signal directly on a DSP. Your agent pushes the segment
+      to the platform and returns a segment_id the buyer uses for campaign targeting.
+
+      Use platform destinations when the buyer manages DSP campaigns directly.
+
+    steps:
+      - id: activate_on_platform
+        title: "Activate owned signal on a DSP"
+        narrative: |
+          The buyer selects a signal and activates it on a DSP. For owned signals,
+          this means your platform pushes first-party segment data to the DSP. The
+          buyer gets back a segment_id for targeting.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "platform"
+          - is_live status (may be async)
+          - activation_key with type: "segment_id" when live
+          - estimated_activation_duration_minutes if not immediately live
+
+        sample_request:
+          signal_agent_segment_id: "prism_high_ltv"
+          pricing_option_id: "po_prism_flat_monthly"
+          destinations:
+            - type: "platform"
+              platform: "the-trade-desk"
+              account: "agency-123-ttd"
+
+        validations:
+          - check: response_schema
+            description: "Response matches activate-signal-response.json schema"
+          - check: field_present
+            path: "deployments[0].type"
+            description: "Deployment includes type"
+
+  - id: agent_activation
+    title: "Activate on a sales agent"
+    narrative: |
+      The buyer activates a signal on a sales agent. The SA records the activation
+      and handles downstream DSP coordination — the buyer doesn't need to know which
+      platform the SA uses.
+
+      This is the right pattern when buying media through a sales agent.
+
+    steps:
+      - id: activate_on_agent
+        title: "Activate owned signal on a sales agent"
+        narrative: |
+          The buyer activates a signal with the SA's URL as the destination. The
+          activation is typically synchronous. The SA records it internally and
+          applies the targeting when the buyer later calls create_media_buy.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "agent"
+          - agent_url matching the SA
+          - is_live: true (sync activation)
+          - activation_key with type: "key_value"
+          - deployed_at timestamp
+
+        sample_request:
+          signal_agent_segment_id: "prism_cart_abandoner"
+          pricing_option_id: "po_prism_abandoner_cpm"
+          destinations:
+            - type: "agent"
+              agent_url: "https://wonderstruck.salesagents.example"
+
+        validations:
+          - check: response_schema
+            description: "Response matches activate-signal-response.json schema"
+          - check: field_present
+            path: "deployments[0].activation_key"
+            description: "Deployment includes activation key"
+          - check: field_value
+            path: "deployments[0].type"
+            description: "Deployment type is 'agent'"