@adcp/client 4.21.0 → 4.22.1

package/storyboards/si_session.yaml

@@ -0,0 +1,384 @@
+id: si_session
+version: "1.0.0"
+title: "Sponsored intelligence session"
+category: si_session
+summary: "SI agent that serves offerings, manages conversational sessions, and handles purchase handoffs."
+track: si
+required_tools:
+  - si_initiate_session
+
+narrative: |
+  You run a sponsored intelligence platform — an AI-powered conversational commerce agent
+  that monetizes through product recommendations and purchase handoffs. A caller connects
+  to check offering availability, initiate a conversation session, exchange messages, and
+  optionally hand off to a transaction flow.
+
+  The caller starts by querying whether an offering is available. If it is, they initiate
+  a session, send messages to explore products, and eventually terminate the session. When
+  the user expresses purchase intent, the termination includes a handoff_transaction reason
+  and the response may contain an acp_handoff structure with checkout details.
+
+  This storyboard walks through the full SI lifecycle: availability, session management,
+  and transaction handoff.
+
+agent:
+  interaction_model: si_platform
+  capabilities:
+    - sponsored_intelligence
+    - conversational
+  examples:
+    - "AI shopping assistants"
+    - "Conversational commerce platforms"
+    - "Product recommendation engines"
+
+caller:
+  role: buyer_agent
+  example: "AI assistant caller"
+
+prerequisites:
+  description: |
+    The caller needs an offering ID and identity credentials. The test uses
+    default values (e2e-test-offering, e2e-test-principal) suitable for
+    validating the SI protocol flow.
+
+phases:
+  - id: availability
+    title: "Offering availability"
+    narrative: |
+      The caller checks whether a specific SI offering is available before initiating
+      a session. The agent returns availability status, an optional offering token for
+      session initiation, and metadata about the offering's capabilities.
+
+      This phase also validates that the agent handles invalid offering IDs gracefully,
+      returning unavailable rather than erroring.
+
+    steps:
+      - id: get_offering
+        title: "Check SI offering availability"
+        requires_tool: si_get_offering
+        narrative: |
+          The caller queries a specific offering by ID. The agent checks inventory and
+          returns whether the offering is available, along with an offering_token the
+          caller uses in subsequent session initiation.
+        task: si_get_offering
+        stateful: false
+        expected: |
+          Return the offering status:
+          - available: true or false
+          - offering_token: opaque token for session initiation (when available)
+          - title and description of the offering
+          - capabilities: what modalities this offering supports
+          - unavailable_reason: explanation when not available
+
+        sample_request:
+          offering_id: "e2e-test-offering"
+          context: "Checking SI offering availability"
+          identity:
+            principal: "e2e-test-principal"
+            device_id: "e2e-test-device"
+
+        validations:
+          - check: field_present
+            path: "available"
+            description: "Response includes availability status"
+
+        context_outputs:
+          - path: "offering_token"
+            key: "offering_token"
+
+      - id: get_offering_invalid
+        title: "Check invalid offering availability"
+        requires_tool: si_get_offering
+        narrative: |
+          The caller queries a nonexistent offering ID. The agent should return
+          available: false with an unavailable_reason, or reject the request with
+          an error. Either response is acceptable.
+        task: si_get_offering
+        stateful: false
+        expected: |
+          Return available: false for the invalid offering, or return an error.
+          The agent must not return available: true for an unknown offering ID.
+
+        sample_request:
+          offering_id: "INVALID_OFFERING_ID_DOES_NOT_EXIST_12345"
+          context: "Checking unavailable offering"
+          identity:
+            principal: "e2e-test-principal"
+
+        validations:
+          - check: field_value
+            path: "available"
+            value: false
+            description: "Invalid offering is reported as unavailable"
+
+  - id: session_lifecycle
+    title: "Session lifecycle"
+    narrative: |
+      The caller initiates a conversational session, exchanges messages, and
+      terminates the session. This tests the core SI protocol flow: create a
+      session, send messages within it, and cleanly shut it down.
+
+      After termination, the caller verifies the session is no longer active
+      by attempting to send a message to the terminated session.
+
+    steps:
+      - id: initiate_session
+        title: "Initiate SI session"
+        narrative: |
+          The caller starts a new conversational session with an offering. The agent
+          provisions the session and returns a session_id, an initial response message,
+          and negotiated capabilities describing what the session supports.
+        task: si_initiate_session
+        stateful: true
+        expected: |
+          Return the session with:
+          - session_id: unique identifier for this session
+          - response: initial message and optional ui_elements
+          - negotiated_capabilities: what modalities were agreed upon
+
+        sample_request:
+          offering_id: "e2e-test-offering"
+          offering_token: "$context.offering_token"
+          identity:
+            principal: "e2e-test-principal"
+            device_id: "e2e-test-device"
+          context: "Initiating conversation about products"
+          placement: "e2e-test-placement"
+          supported_capabilities:
+            modalities:
+              conversational: true
+              rich_media: true
+
+        context_inputs:
+          - key: "offering_token"
+            inject_at: "offering_token"
+
+        validations:
+          - check: field_present
+            path: "session_id"
+            description: "Response includes a session_id"
+
+        context_outputs:
+          - path: "session_id"
+            key: "session_id"
+
+      - id: send_message_1
+        title: "Send message: product inquiry"
+        requires_tool: si_send_message
+        narrative: |
+          The caller sends a product inquiry message within the active session.
+          The agent responds with product information and optional UI elements
+          such as product cards or carousels.
+        task: si_send_message
+        stateful: true
+        expected: |
+          Return the message response:
+          - session_id: matches the active session
+          - session_status: active
+          - response: message text and optional ui_elements
+
+        sample_request:
+          session_id: "$context.session_id"
+          message: "What products do you have available?"
+          metadata:
+            test_iteration: 1
+
+        context_inputs:
+          - key: "session_id"
+            inject_at: "session_id"
+
+        validations:
+          - check: field_present
+            path: "session_id"
+            description: "Response includes the session_id"
+
+      - id: send_message_2
+        title: "Send message: product details"
+        requires_tool: si_send_message
+        narrative: |
+          The caller asks a follow-up question about a specific product.
+          The agent should maintain conversational context from the previous
+          message and respond with more detailed information.
+        task: si_send_message
+        stateful: true
+        expected: |
+          Return a contextual response continuing the conversation:
+          - session_status: active
+          - response: detailed product information
+
+        sample_request:
+          session_id: "$context.session_id"
+          message: "Can you tell me more about your best seller?"
+          metadata:
+            test_iteration: 2
+
+        context_inputs:
+          - key: "session_id"
+            inject_at: "session_id"
+
+        validations:
+          - check: field_present
+            path: "session_id"
+            description: "Response includes the session_id"
+
+      - id: terminate_session
+        title: "Terminate SI session"
+        requires_tool: si_terminate_session
+        narrative: |
+          The caller ends the session with a user_exit reason. The agent
+          confirms termination and cleans up session state.
+        task: si_terminate_session
+        stateful: true
+        expected: |
+          Confirm session termination:
+          - session_id: matches the terminated session
+          - terminated: true
+
+        sample_request:
+          session_id: "$context.session_id"
+          reason: "user_exit"
+          termination_context:
+            summary: "Session completed successfully"
+
+        context_inputs:
+          - key: "session_id"
+            inject_at: "session_id"
+
+        validations:
+          - check: field_present
+            path: "terminated"
+            description: "Response confirms termination"
+
+      - id: send_to_terminated
+        title: "Send message to terminated session (error expected)"
+        requires_tool: si_send_message
+        expect_error: true
+        narrative: |
+          The caller attempts to send a message to the terminated session.
+          The agent should reject the message or return a terminated session
+          status. This validates that session cleanup is enforced.
+        task: si_send_message
+        stateful: true
+        expected: |
+          Reject the message or return session_status of "terminated" or "complete".
+          The agent must not accept new messages on a terminated session.
+
+        sample_request:
+          session_id: "$context.session_id"
+          message: "This should fail"
+
+        context_inputs:
+          - key: "session_id"
+            inject_at: "session_id"
+
+        validations: []
+
+  - id: handoff
+    title: "Transaction handoff"
+    narrative: |
+      The caller initiates a session, sends a purchase-intent message, and then
+      terminates with reason handoff_transaction. The agent may include an
+      acp_handoff structure in the termination response containing checkout URLs,
+      tokens, and transaction metadata.
+
+      This tests the commerce integration path where conversational AI transitions
+      to a purchase flow.
+
+    steps:
+      - id: initiate_handoff_session
+        title: "Initiate SI session (handoff flow)"
+        narrative: |
+          The caller starts a new session specifically for testing the handoff flow.
+          This is a separate session from the lifecycle phase.
+        task: si_initiate_session
+        stateful: true
+        expected: |
+          Return a new session with a session_id for the handoff test.
+
+        sample_request:
+          offering_id: "e2e-test-offering"
+          offering_token: "$context.offering_token"
+          identity:
+            principal: "e2e-test-principal"
+            device_id: "e2e-test-device"
+          context: "Initiating session for handoff test"
+          placement: "e2e-test-placement"
+          supported_capabilities:
+            modalities:
+              conversational: true
+
+        context_inputs:
+          - key: "offering_token"
+            inject_at: "offering_token"
+
+        validations:
+          - check: field_present
+            path: "session_id"
+            description: "Response includes a session_id"
+
+        context_outputs:
+          - path: "session_id"
+            key: "handoff_session_id"
+
+      - id: send_purchase_intent
+        title: "Send purchase intent message"
+        requires_tool: si_send_message
+        narrative: |
+          The caller sends a message expressing purchase intent. This primes the
+          agent for a transaction handoff in the next step.
+        task: si_send_message
+        stateful: true
+        expected: |
+          Accept the purchase intent message. The agent may begin preparing
+          transaction details in anticipation of a handoff.
+
+        sample_request:
+          session_id: "$context.handoff_session_id"
+          message: "I'd like to purchase this product. Can you set up a transaction?"
+
+        context_inputs:
+          - key: "handoff_session_id"
+            inject_at: "session_id"
+
+        validations:
+          - check: field_present
+            path: "session_id"
+            description: "Response includes the session_id"
+
+      - id: terminate_with_handoff
+        title: "Terminate with handoff_transaction"
+        requires_tool: si_terminate_session
+        narrative: |
+          The caller terminates the session with reason handoff_transaction and
+          includes transaction intent metadata. The agent confirms termination and
+          may return an acp_handoff structure with checkout details.
+        task: si_terminate_session
+        stateful: true
+        expected: |
+          Confirm termination and optionally return an acp_handoff object:
+          - terminated: true
+          - acp_handoff (optional):
+            - checkout_url: URL for the purchase flow
+            - checkout_token: opaque token for the transaction
+            - payload: additional transaction data
+            - expires_at: when the handoff expires
+
+          If the agent does not support transaction handoff, terminated: true
+          without acp_handoff is acceptable.
+
+        sample_request:
+          session_id: "$context.handoff_session_id"
+          reason: "handoff_transaction"
+          termination_context:
+            summary: "Terminating for handoff validation"
+            transaction_intent:
+              intent: "purchase"
+
+        context_inputs:
+          - key: "handoff_session_id"
+            inject_at: "session_id"
+
+        validations:
+          - check: field_present
+            path: "terminated"
+            description: "Response confirms termination"

package/storyboards/signal_marketplace.yaml

@@ -0,0 +1,283 @@
+id: signal_marketplace
+version: "1.0.0"
+title: "Marketplace signal agent"
+category: signal_marketplace
+summary: "Signal agent that resells third-party data provider signals with verifiable catalog provenance."
+platform_types:
+  - pmax_platform
+  - ai_ad_network
+  - ai_platform
+
+track: signals
+required_tools:
+  - get_signals
+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 catalogs published by data providers in their adagents.json
+  files. Buyers discover signals through natural language queries, verify provenance by
+  checking the data provider's catalog 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).
+
+agent:
+  interaction_model: marketplace_catalog
+  capabilities:
+    - catalog_signals
+  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: discovery
+    title: "Signal discovery"
+    narrative: |
+      The buyer describes what they need in natural language. Your agent searches
+      across all authorized data provider catalogs 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 catalogs 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"
+        stateful: false
+        expected: |
+          Return matching signals from multiple data providers. Each signal must include:
+          - signal_agent_segment_id for activation
+          - signal_id with source, data_provider_domain, and id
+          - name, description, and value_type (binary, categorical, or numeric)
+          - coverage_percentage (audience reach estimate)
+          - pricing_options with at least one pricing model
+          - signal_type: "marketplace"
+
+        sample_request:
+          signal_spec: "In-market EV buyers with high purchase propensity, near auto dealerships"
+
+        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: "signals[0].coverage_percentage"
+            description: "Each signal has a coverage estimate"
+
+      - id: search_by_ids
+        title: "Look up specific signals by ID"
+        narrative: |
+          The buyer already knows which signals they want — maybe from a previous
+          campaign or a provider's documentation. 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"
+        stateful: false
+        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:
+          signal_ids:
+            - source: "catalog"
+              data_provider_domain: "tridentauto.example"
+              id: "likely_ev_buyers"
+            - source: "catalog"
+              data_provider_domain: "meridiangeo.example"
+              id: "competitor_visitors"
+
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+          - check: field_present
+            path: "signals"
+            description: "Response contains a signals array"
+
+  - id: verification
+    title: "Catalog 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: signal_id.source 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 and checks that the response
+          includes the metadata needed for independent verification — source 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"
+        stateful: false
+        expected: |
+          Return the requested signal with verifiable provenance metadata:
+          - 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:
+          signal_ids:
+            - source: "catalog"
+              data_provider_domain: "shopgrid.example"
+              id: "new_to_brand"
+
+        validations:
+          - check: field_value
+            path: "signals[0].signal_id.source"
+            description: "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"
+
+  - 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"
+        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:
+          signal_agent_segment_id: "trident_likely_ev_buyers"
+          pricing_option_id: "po_trident_ev_cpm"
+          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"
+          - check: field_value
+            path: "deployments[0].type"
+            description: "Deployment type is 'platform'"
+
+  - 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"
+        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:
+          signal_agent_segment_id: "shopgrid_new_to_brand"
+          pricing_option_id: "po_shopgrid_retail_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'"