@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/signal-marketplace/index.yaml

@@ -0,0 +1,424 @@
+id: signal_marketplace
+version: "1.0.0"
+title: "Marketplace signal agent"
+protocol: signals
+category: signal_marketplace
+summary: "Signal agent that resells third-party data provider signals with verifiable provider-published provenance."
+track: signals
+required_tools:
+  - get_signals
+requires_scenarios:
+  - signal_marketplace/governance_denied
+
+narrative: |
+  You operate a signal marketplace — an intermediary that aggregates audience data from
+  multiple third-party providers and makes it available to buyers through a single interface.
+  Think LiveRamp Data Marketplace, Oracle Data Cloud, or Lotame.
+
+  Your agent searches across signal definitions published by data providers in their
+  adagents.json files. Buyers discover signals through natural language queries, verify
+  provenance by checking the data provider's published definitions directly, and
+  activate signals on DSPs or sales agents for campaign targeting.
+
+  The key property of marketplace signals: provenance is independently verifiable. Each
+  signal traces back to a data_provider_domain whose adagents.json lists your agent as
+  authorized. Buyers can (and should) verify this before spending.
+
+  This storyboard walks through discovery, verification, and both activation patterns —
+  activating directly on a DSP (buyer manages targeting) and activating on a sales agent
+  (SA handles downstream coordination).
+
+  Pricing is hard-required for signal marketplaces. Signals are rate-carded goods by
+  definition — the value exchange is paying for access to audience data. Unlike creative
+  ad servers (where billing can be handled via out-of-band enterprise contracts), a signal
+  marketplace without pricing_options is either non-commercial or misconfigured; buyers
+  cannot activate without a pricing_option_id to anchor billing.
+
+agent:
+  interaction_model: marketplace_catalog
+  capabilities: []
+  examples:
+    - "LiveRamp Data Marketplace"
+    - "Oracle Data Cloud"
+    - "Lotame"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The buyer has a campaign brief with targeting objectives. The test kit provides
+    sample signal definitions, pricing options, and destination configurations that
+    match the training agent's signal providers.
+  test_kit: "test-kits/nova-motors.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports signals before discovering or activating audience data.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring signals in supported_protocols, confirming the agent serves audience signals.
+        sample_request:
+          context:
+            correlation_id: "signal_marketplace--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: discovery
+    title: "Signal discovery"
+    narrative: |
+      The buyer describes what they need in natural language. Your agent searches
+      across all authorized data provider signal definitions and returns matching signals with
+      pricing, coverage estimates, and value types.
+
+      This is where marketplace agents earn their keep — the buyer doesn't need to
+      know which providers exist or what taxonomies they use. One query, many sources.
+
+    steps:
+      - id: search_by_spec
+        title: "Discover signals from a campaign brief"
+        narrative: |
+          The buyer's platform translates a campaign brief into a get_signals call.
+          Your agent searches definitions from every authorized data provider and returns
+          what matches — automotive intent from one provider, geo data from another,
+          retail purchase history from a third.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: signals_flow
+        stateful: false
+        expected: |
+          Return matching signals from multiple data providers. Each signal must include:
+          - signal_agent_segment_id for activation
+          - legacy signal_id with source, data_provider_domain, and id
+          - name, description, and value_type (binary, categorical, or numeric)
+          - coverage_forecast when detailed availability is disclosed; deprecated coverage_percentage may be present as a legacy scalar fallback
+          - pricing_options with at least one pricing model
+          - signal_type: "marketplace"
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "In-market EV buyers with high purchase propensity, near auto dealerships"
+
+          context:
+            correlation_id: "signal_marketplace--search_by_spec"
+
+        context_outputs:
+          - name: first_signal_id
+            path: "signals[0].signal_id"
+          - name: first_signal_agent_segment_id
+            path: "signals[0].signal_agent_segment_id"
+          - name: first_signal_pricing_option_id
+            path: "signals[0].pricing_options[0].pricing_option_id"
+          - name: second_signal_id
+            path: "signals[1].signal_id"
+        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].signal_id.data_provider_domain"
+            description: "Each signal traces to a data provider domain"
+          - check: field_present
+            path: "signals[0].pricing_options"
+            description: "Each signal has pricing options"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--search_by_spec"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "signals[0].signal_id.source"
+            description: "Legacy Signal ID includes source discriminator"
+          - check: field_present
+            path: "signals[0].signal_id.data_provider_domain"
+            description: "Signal ID includes data_provider_domain for provenance"
+      - id: search_by_ids
+        title: "Look up specific signals by ID"
+        narrative: |
+          The buyer already knows which signals they want — discovered in the prior
+          step. They pass signal_ids directly instead of a natural language query.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return the exact signals requested, with full metadata and pricing.
+          If a signal_id doesn't exist, omit it from results — don't error.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_ids:
+            - "$context.first_signal_id"
+
+          context:
+            correlation_id: "signal_marketplace--search_by_ids"
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+          - check: field_present
+            path: "signals"
+            description: "Response contains a signals array"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--search_by_ids"
+            description: "Context correlation_id returned unchanged"
+  - id: verification
+    title: "Provider verification"
+    narrative: |
+      Before activating third-party data, the buyer verifies provenance. They fetch
+      the data provider's adagents.json directly and confirm the signal exists and
+      your agent is authorized. This independent check is outside the AdCP protocol —
+      but your agent must return the metadata that makes it possible.
+
+      This phase tests that your get_signals responses include verifiable provenance
+      data: the legacy signal_id.source value is "catalog" and
+      signal_id.data_provider_domain points to a real domain whose adagents.json the
+      buyer can fetch independently.
+
+    steps:
+      - id: verify_provenance_metadata
+        title: "Confirm signals carry verifiable provenance"
+        narrative: |
+          The buyer looks up a specific signal by ID (discovered earlier) and checks
+          that the response includes the metadata needed for independent verification —
+          the legacy source value is "catalog" and data_provider_domain points to a fetchable adagents.json.
+          The actual HTTP fetch of adagents.json is the buyer's responsibility, but
+          your agent must provide the domain to fetch from.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/data-providers"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return the requested signal with verifiable provenance metadata:
+          - legacy signal_id.source is "catalog"
+          - signal_id.data_provider_domain matches a real domain
+          The buyer will independently fetch that domain's adagents.json to confirm
+          your agent is listed in authorized_agents.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_ids:
+            - "$context.first_signal_id"
+
+          context:
+            correlation_id: "signal_marketplace--verify_provenance_metadata"
+        validations:
+          - check: field_value
+            path: "signals[0].signal_id.source"
+            value: "catalog"
+            description: "Legacy signal source is 'catalog' (verifiable via adagents.json)"
+          - check: field_present
+            path: "signals[0].signal_id.data_provider_domain"
+            description: "Data provider domain is present for independent verification"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--verify_provenance_metadata"
+            description: "Context correlation_id returned unchanged"
+  - id: platform_activation
+    title: "Activate on a DSP"
+    narrative: |
+      The buyer activates a signal directly on a DSP platform. The signal agent pushes
+      segment data to the platform, and the buyer gets back a segment_id they can
+      reference when configuring campaign targeting.
+
+      Use platform destinations when the buyer is managing DSP campaigns directly —
+      not through a sales agent.
+
+    steps:
+      - id: activate_on_platform
+        title: "Activate signal on a DSP"
+        narrative: |
+          The buyer selects a signal and a DSP destination. The signal agent pushes
+          the segment to the platform. This is typically asynchronous — the initial
+          response shows is_live: false with an estimated duration, and the buyer
+          polls for completion.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "platform" matching the requested destination
+          - is_live: false initially (async activation)
+          - estimated_activation_duration_minutes
+          After polling, the deployment should show:
+          - is_live: true
+          - activation_key with type: "segment_id" and a platform-native segment ID
+          - deployed_at timestamp
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "$context.first_signal_agent_segment_id"
+          pricing_option_id: "$context.first_signal_pricing_option_id"
+          destinations:
+            - type: "platform"
+              platform: "pinnacle-dsp"
+              account: "agency-123-pd"
+          idempotency_key: "$generate:uuid_v4#signal_marketplace_activate_platform"
+          context:
+            correlation_id: "signal_marketplace--activate_on_platform"
+          ext:
+            test_platform:
+              test_run: true
+        validations:
+          - check: response_schema
+            description: "Response matches activate-signal-response.json schema"
+          - check: field_present
+            path: "deployments[0].type"
+            description: "Deployment includes type"
+          - check: field_value
+            path: "deployments[0].type"
+            value: "platform"
+            description: "Deployment type is 'platform'"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--activate_on_platform"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "deployments[0].activation_key"
+            description: "Deployment includes activation_key for targeting"
+          # Anti-façade: a real activation calls the DSP's segment-deployment
+          # endpoint with the captured signal_agent_segment_id. An adapter
+          # returning a fabricated activation_key without touching the DSP
+          # fails this check. The since: search_by_spec window scopes the
+          # assertion to traffic caused after this storyboard captured the
+          # signal IDs, ignoring earlier discovery traffic.
+          - check: upstream_traffic
+            description: "activate_on_platform caused upstream traffic to a DSP carrying the signal_agent_segment_id"
+            min_count: 1
+            endpoint_pattern: "POST *"
+            since: search_by_spec
+            identifier_paths:
+              - "signal_agent_segment_id"
+  - id: agent_activation
+    title: "Activate on a sales agent"
+    narrative: |
+      The buyer activates a signal on a sales agent instead of a DSP. This is the
+      right pattern when the buyer is purchasing media through the SA — the SA handles
+      its own DSP coordination.
+
+      The buyer doesn't need to know which DSP the SA uses. The activation key confirms
+      the signal is live on the SA, and the SA applies targeting when fulfilling media
+      buys through create_media_buy.
+
+    steps:
+      - id: activate_on_agent
+        title: "Activate signal on a sales agent"
+        narrative: |
+          The buyer activates a signal with the sales agent's URL as the destination.
+          Agent activations are typically synchronous — the SA records the activation
+          immediately and returns a key_value activation key.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "agent" matching the requested destination
+          - agent_url matching the SA's URL
+          - is_live: true (sync activation)
+          - activation_key with type: "key_value"
+          - deployed_at timestamp
+
+          The SA records the activation internally. When the buyer later calls
+          create_media_buy through this SA, signal-based targeting is already
+          in place.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "$context.first_signal_agent_segment_id"
+          pricing_option_id: "$context.first_signal_pricing_option_id"
+          destinations:
+            - type: "agent"
+              agent_url: "https://wonderstruck.salesagents.example"
+          idempotency_key: "$generate:uuid_v4#signal_marketplace_activate_agent"
+          context:
+            correlation_id: "signal_marketplace--activate_on_agent"
+          ext:
+            test_platform:
+              test_run: true
+        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"
+            value: "agent"
+            description: "Deployment type is 'agent'"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_marketplace--activate_on_agent"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/specialisms/signal-marketplace/scenarios/governance_denied.yaml

@@ -0,0 +1,210 @@
+id: signal_marketplace/governance_denied
+version: "1.0.0"
+title: "Signal agent rejects activation when governance denies"
+category: signal_marketplace
+summary: "Verifies that a signal agent propagates GOVERNANCE_DENIED when the buyer's governance plan denies activation."
+track: signals
+required_tools:
+  - sync_governance
+  - get_signals
+  - activate_signal
+
+narrative: |
+  Signal activation is a spending event: activating a third-party segment costs per-user
+  or per-activation fees that must be authorized against the buyer's governance plan. The
+  signal agent must consult the registered governance agent before activation and deny
+  the request when governance returns denied.
+
+  This scenario sets up a strict $100 plan, registers that governance with the signal
+  agent via sync_governance, then attempts to activate a signal whose pricing exceeds
+  the plan. The signal agent must return GOVERNANCE_DENIED with findings propagated
+  from the governance agent.
+
+  By default, the governance agent is the training agent at test-agent.adcontextprotocol.org.
+  Override by supplying a different `governance_agent_url` in the run's initial context
+  (e.g., via `--context` on `adcp storyboard run` once the CLI supports it).
+
+context:
+  governance_agent_url: "https://test-agent.adcontextprotocol.org"
+
+agent:
+  interaction_model: marketplace_catalog
+  capabilities:
+    - governance_aware
+  examples:
+    - "Any signal agent that honors governance before activation"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    A governance agent that supports sync_plans and check_governance, and a signal
+    agent that supports sync_governance + activate_signal.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: governance_plan_setup
+    title: "Set up strict governance plan"
+    narrative: |
+      Create a governance plan with a $100 budget — enough to block even a single
+      activation at typical CPM-for-segment pricing.
+
+    steps:
+      - id: sync_plans
+        title: "Create strict governance plan"
+        task: sync_plans
+        schema_ref: "governance/sync-plans-request.json"
+        response_schema_ref: "governance/sync-plans-response.json"
+        doc_ref: "/governance/campaign/tasks/sync_plans"
+        stateful: true
+        expected: |
+          The governance agent acknowledges the plan.
+        sample_request:
+          plans:
+            - plan_id: "comply-signal-gov-denied"
+              brand:
+                domain: "acmeoutdoor.example"
+              objectives: "Restricted plan — signals activation test"
+              budget:
+                total: 100
+                currency: "USD"
+                reallocation_threshold: 50
+              flight:
+                start: "2026-04-01T00:00:00Z"
+                end: "2026-06-30T23:59:59Z"
+              countries: ["US"]
+          idempotency_key: "$generate:uuid_v4#signal_marketplace_governance_denied_governance_plan_setup_sync_plans"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: signal_agent_setup
+    title: "Register account and governance with the signal agent"
+    steps:
+      - id: sync_accounts
+        title: "Establish account with signal agent"
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        stateful: true
+        expected: |
+          Signal agent returns the account with account_id active.
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              payment_terms: "net_30"
+          idempotency_key: "$generate:uuid_v4#signal_marketplace_governance_denied_signal_agent_setup_sync_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "Account has a platform-assigned ID"
+
+      - id: sync_governance
+        title: "Register governance agent with signal agent"
+        task: sync_governance
+        schema_ref: "account/sync-governance-request.json"
+        response_schema_ref: "account/sync-governance-response.json"
+        doc_ref: "/accounts/tasks/sync_governance"
+        stateful: true
+        expected: |
+          Signal agent acknowledges governance registration.
+        sample_request:
+          accounts:
+            - account:
+                brand:
+                  domain: "acmeoutdoor.example"
+                operator: "pinnacle-agency.example"
+              governance_agents:
+                - url: "$context.governance_agent_url"
+                  authentication:
+                    schemes: ["Bearer"]
+                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+          idempotency_key: "$generate:uuid_v4#signal_marketplace_governance_denied_signal_agent_setup_sync_governance"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-governance-response.json schema"
+
+  - id: activation_denied
+    title: "Attempt activation — governance denies"
+    steps:
+      - id: get_signals_list
+        title: "Discover a signal to activate"
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/task-reference/get_signals"
+        comply_scenario: signal_discovery
+        stateful: false
+        expected: |
+          Return at least one signal with a signal_agent_segment_id and pricing.
+        sample_request:
+          signal_spec: "outdoor enthusiasts, age 25-54, US"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        context_outputs:
+          - path: "signals[0].signal_agent_segment_id"
+            key: "signal_agent_segment_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+          - check: field_present
+            path: "signals[0].signal_agent_segment_id"
+            description: "Signal has an activation identifier"
+
+      - id: activate_signal_denied
+        title: "activate_signal — governance denies"
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/task-reference/activate_signal"
+        comply_scenario: signal_activation
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Signal agent rejects with:
+          - code: GOVERNANCE_DENIED
+          - findings propagated from the governance agent
+
+        sample_request:
+          signal_agent_segment_id: "$context.signal_agent_segment_id"
+          destinations:
+            - type: "platform"
+              platform: "the-trade-desk"
+              account: "acmeoutdoor-ttd-seat"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "$generate:uuid_v4#signal-gov-denied"
+
+          context:
+            correlation_id: "signal_marketplace--governance_denied--activate"
+        sample_response:
+          status: "failed"
+          errors:
+            - code: "GOVERNANCE_DENIED"
+              message: "Signal activation requires governance approval. Call check_governance first — a governance plan is registered for this account."
+              details:
+                findings:
+                  - category_id: "budget_authority"
+                    severity: "critical"
+                    explanation: "Signal activation requires governance approval. Call check_governance first — a governance plan is registered for this account."
+                plan_id: "comply-signal-gov-denied"
+        validations:
+          - check: error_code
+            value: "GOVERNANCE_DENIED"
+            description: "Error code is GOVERNANCE_DENIED"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"