@adcp/client 4.22.0 → 4.23.0

package/storyboards/campaign_governance_delivery.yaml

@@ -0,0 +1,231 @@
+id: campaign_governance_delivery
+version: "1.0.0"
+title: "Campaign governance — delivery monitoring with drift detection"
+category: campaign_governance_delivery
+summary: "Governance agent monitors delivery, detects budget drift past thresholds, and triggers re-evaluation."
+track: campaign_governance
+required_tools:
+  - check_governance
+
+narrative: |
+  After a media buy is confirmed with governance approval, the governance agent monitors
+  delivery. When spend drifts past a reallocation threshold — for example, one line item
+  is overspending while another is underspending — the governance agent triggers a delivery
+  phase re-evaluation.
+
+  This storyboard covers the delivery monitoring governance flow: initial approval,
+  delivery metrics showing drift, governance re-check triggered by drift, and either
+  re-approval with adjusted conditions or a pause recommendation.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher platform with governance and delivery reporting"
+    - "Retail media network with pacing data"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, a governance agent URL,
+    and an active media buy with delivery data. The governance plan defines a
+    reallocation threshold that triggers re-evaluation.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: plan_registration
+    title: "Register governance plan with delivery monitoring"
+    narrative: |
+      The buyer registers a governance plan that includes delivery monitoring thresholds.
+      When spend drift exceeds the reallocation threshold, the governance agent triggers
+      a delivery-phase re-evaluation.
+
+    steps:
+      - id: sync_plans
+        title: "Register a governance plan with reallocation threshold"
+        narrative: |
+          The buyer's governance agent registers a plan with full spending authority and
+          a 20% reallocation threshold. If any line item's spend drifts more than 20%
+          from the planned budget allocation, the governance agent re-evaluates.
+        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"
+        comply_scenario: campaign_governance_delivery
+        stateful: true
+        expected: |
+          Acknowledge the governance plan:
+          - plan_id: identifier for this governance plan
+          - authority_level: agent_full
+          - reallocation_threshold: 0.20 (20% drift triggers re-evaluation)
+
+        sample_request:
+          plans:
+            - plan_name: "Acme Outdoor delivery governance"
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+              authority_level: "agent_full"
+              reallocation_threshold: 0.20
+              conditions:
+                - "Re-evaluate governance if any line item drifts >20% from plan"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: initial_approval
+    title: "Initial governance check — approved"
+    narrative: |
+      The buyer proposes a media buy within authority. The governance agent approves
+      the buy with the delivery monitoring conditions active.
+
+    steps:
+      - id: check_governance_approved
+        title: "Pre-buy governance check (approved)"
+        narrative: |
+          The buyer calls check_governance with a media buy within authority. The governance
+          agent approves and notes that delivery monitoring is active with the 20% drift
+          threshold.
+        task: check_governance
+        schema_ref: "governance/check-governance-request.json"
+        response_schema_ref: "governance/check-governance-response.json"
+        doc_ref: "/governance/campaign/tasks/check_governance"
+        comply_scenario: campaign_governance_delivery
+        stateful: true
+        expected: |
+          Return an approved governance decision:
+          - decision: approved
+          - governance_context: token for the media buy
+          - monitoring: delivery phase governance is active
+
+        sample_request:
+          plan_id: "gov_acme_delivery"
+          binding:
+            type: "media_buy"
+            account:
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+            total_budget: 40000
+            packages:
+              - product_id: "sports_ctv_q2"
+                budget: 20000
+              - product_id: "outdoor_video_q2"
+                budget: 20000
+
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "decision"
+            description: "Response contains a governance decision"
+
+  - id: delivery_monitoring
+    title: "Delivery metrics show budget drift"
+    narrative: |
+      The campaign is running. The buyer checks delivery and finds that one line item
+      is overspending while the other is underspending. The CTV line item has consumed
+      70% of its budget at the halfway point while the video line item is at 30%.
+
+    steps:
+      - id: get_delivery
+        title: "Check delivery metrics"
+        narrative: |
+          The buyer requests delivery data and finds budget drift. One line item is
+          significantly overpacing while the other is underpacing.
+        task: get_media_buy_delivery
+        schema_ref: "media-buy/get-media-buy-delivery-request.json"
+        response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
+        comply_scenario: campaign_governance_delivery
+        stateful: true
+        expected: |
+          Return delivery metrics showing drift:
+          - Per-package delivery with impressions, spend, and pacing
+          - One package overpacing (>60% spend at 50% flight)
+          - One package underpacing (<40% spend at 50% flight)
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          media_buy_ids:
+            - "mb_acme_q2_2026"
+          include_package_daily_breakdown: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"
+          - check: field_present
+            path: "media_buys"
+            description: "Response contains media buy delivery data"
+
+  - id: drift_recheck
+    title: "Governance re-check — drift detected"
+    narrative: |
+      The buyer's governance agent detects that budget drift has exceeded the 20%
+      reallocation threshold. It triggers a delivery-phase governance check with the
+      current delivery data as evidence. The governance agent re-evaluates and returns
+      a decision — either re-approved with updated conditions or a recommendation to
+      pause and rebalance.
+
+    steps:
+      - id: check_governance_drift
+        title: "Delivery-phase governance re-check (drift exceeded)"
+        narrative: |
+          The buyer calls check_governance with governance_phase: delivery and attaches
+          the current delivery metrics as evidence. The governance agent evaluates the
+          drift against the reallocation threshold and returns a decision.
+        task: check_governance
+        schema_ref: "governance/check-governance-request.json"
+        response_schema_ref: "governance/check-governance-response.json"
+        doc_ref: "/governance/campaign/tasks/check_governance"
+        comply_scenario: campaign_governance_delivery
+        stateful: true
+        expected: |
+          Return a governance decision about the delivery drift:
+          - decision: approved (with rebalancing conditions) or denied (pause recommended)
+          - findings: should-severity findings noting the drift amounts
+            - severity: should
+            - code: BUDGET_DRIFT_EXCEEDED
+            - message: explains which line items drifted and by how much
+          - conditions: if approved, conditions for rebalancing (e.g., "Reallocate $5K from CTV to video")
+
+        sample_request:
+          plan_id: "gov_acme_delivery"
+          governance_phase: "delivery"
+          governance_context: "gov_ctx_acme_delivery_approved"
+          binding:
+            type: "media_buy"
+            account:
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+            media_buy_id: "mb_acme_q2_2026"
+            delivery_evidence:
+              packages:
+                - product_id: "sports_ctv_q2"
+                  budget: 20000
+                  spend_to_date: 14000
+                  flight_progress: 0.50
+                - product_id: "outdoor_video_q2"
+                  budget: 20000
+                  spend_to_date: 6000
+                  flight_progress: 0.50
+
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "decision"
+            description: "Response contains a governance decision"
+          - check: field_present
+            path: "findings"
+            description: "Response contains findings about the drift"

package/storyboards/campaign_governance_denied.yaml

@@ -0,0 +1,135 @@
+id: campaign_governance_denied
+version: "1.0.0"
+title: "Campaign governance — denied"
+category: campaign_governance_denied
+summary: "Governance agent denies a media buy that exceeds the agent's spending authority. No human escalation — the buy is blocked."
+track: campaign_governance
+required_tools:
+  - sync_plans
+  - check_governance
+
+narrative: |
+  The buyer's governance agent registers a plan with strict spending authority. The buyer
+  then proposes a media buy that exceeds the agent's per-transaction threshold. The
+  governance agent denies the buy outright with a must-severity finding.
+
+  Unlike the escalation storyboard, there is no human override here. The denial is final.
+  The buyer must reduce the buy amount or restructure into smaller transactions that fall
+  within the agent's authority. This tests the hard-stop governance path.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher platform with governance support"
+    - "Retail media network"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, and a governance agent URL.
+    The governance plan must define a per-transaction threshold below the intended buy amount.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: plan_registration
+    title: "Register governance plan"
+    narrative: |
+      The buyer registers a governance plan with strict spending authority. The plan sets
+      an agent_limited authority level with a $10K per-transaction threshold. Any buy above
+      this amount is denied without escalation.
+
+    steps:
+      - id: sync_plans
+        title: "Register a governance plan with strict authority"
+        narrative: |
+          The buyer's governance agent registers a plan with a $10K per-transaction limit
+          and no escalation path. Buys that exceed this threshold are denied outright.
+        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"
+        comply_scenario: campaign_governance_denied
+        stateful: true
+        expected: |
+          Acknowledge the governance plan:
+          - plan_id: identifier for this governance plan
+          - authority_level: agent_limited
+          - per_transaction_threshold: $10K spending limit
+
+        sample_request:
+          plans:
+            - plan_name: "Acme Outdoor strict governance"
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+              authority_level: "agent_limited"
+              per_transaction_threshold: 10000
+              escalation_path: "none"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: governance_check
+    title: "Governance check — denied"
+    narrative: |
+      The buyer proposes a $50K media buy against the $10K threshold. The governance agent
+      evaluates the binding and returns a denied decision with a must-severity finding
+      explaining the spending authority violation. No escalation instructions are provided
+      because the plan has no escalation path.
+
+    steps:
+      - id: check_governance_denied
+        title: "Pre-buy governance check (denied, no escalation)"
+        narrative: |
+          The buyer calls check_governance with a $50K media buy binding. The governance
+          agent denies the buy because the total exceeds the $10K per-transaction authority.
+          The response includes a must-severity finding with the violation details.
+        task: check_governance
+        schema_ref: "governance/check-governance-request.json"
+        response_schema_ref: "governance/check-governance-response.json"
+        doc_ref: "/governance/campaign/tasks/check_governance"
+        comply_scenario: campaign_governance_denied
+        stateful: true
+        expected: |
+          Return a denied governance decision:
+          - decision: denied
+          - findings: array with at least one must-severity finding
+            - severity: must
+            - code: SPENDING_AUTHORITY_EXCEEDED
+            - message: explains the threshold and how much the buy exceeds it
+          - No escalation instructions (plan has no escalation path)
+
+        sample_request:
+          plan_id: "gov_acme_strict"
+          binding:
+            type: "media_buy"
+            account:
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+            total_budget: 50000
+            packages:
+              - product_id: "sports_ctv_q2"
+                budget: 30000
+              - product_id: "outdoor_video_q2"
+                budget: 20000
+
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "decision"
+            description: "Response contains a governance decision"
+          - check: field_value
+            path: "decision"
+            description: "Decision is denied"
+          - check: field_present
+            path: "findings"
+            description: "Response contains findings explaining the denial"

package/storyboards/capability_discovery.yaml

@@ -0,0 +1,106 @@
+id: capability_discovery
+version: "1.0.0"
+title: "Capability discovery"
+category: capability_discovery
+summary: "Buyer calls get_adcp_capabilities to discover what an agent supports before making any buying or creative decisions."
+track: core
+
+narrative: |
+  Before doing anything else, a buyer agent calls get_adcp_capabilities to learn what your
+  platform supports. This is the first call in any new relationship — the buyer needs to know
+  your protocol version, supported domains (media buy, creative, governance, signals, SI),
+  pricing models, targeting capabilities, and creative specs.
+
+  The response shapes every subsequent call. If you declare media_buy support, the buyer knows
+  it can send briefs and create media buys. If you declare creative support, the buyer knows
+  it can sync or build creatives. The buyer uses this to decide which storyboards apply to your
+  agent and what flows to attempt.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any AdCP-compliant agent"
+    - "Publisher platforms"
+    - "Creative ad servers"
+    - "DSPs"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    No prerequisites. This is the very first call a buyer makes to any agent.
+    The test kit provides brand context but it is not required for this storyboard.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: protocol_discovery
+    title: "Protocol and capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to learn what your agent supports. This call
+      takes no required arguments — it is a read-only introspection of the agent's
+      capabilities. The buyer may optionally filter by protocol domain or major version.
+
+    steps:
+      - id: get_capabilities
+        title: "Discover agent capabilities"
+        narrative: |
+          The buyer calls get_adcp_capabilities with no arguments. Your agent returns its
+          full capability declaration: protocol version, supported domains, pricing models,
+          targeting options, creative specs, and any extensions.
+
+          This response is the source of truth for what the buyer can do with your agent.
+          Every field the buyer reads here determines which tasks it will call next.
+        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 your agent's full capability declaration:
+          - adcp.major_versions: which protocol versions you support (e.g., [3])
+          - supported_protocols: which domains are available (media_buy, creative, governance, signals, sponsored_intelligence)
+          - media_buy: pricing models, delivery types, targeting, reporting features
+          - creative: library support, generation, transformation capabilities
+          - governance: property and creative features the governance agent can evaluate
+          - account: auth model, billing support, sandbox mode
+
+        sample_request: {}
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "adcp.major_versions"
+            description: "Agent declares supported protocol versions"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares which protocol domains it supports"
+
+      - id: get_capabilities_filtered
+        title: "Discover capabilities filtered by protocol"
+        narrative: |
+          The buyer calls get_adcp_capabilities again, this time filtering for a specific
+          protocol domain. This is useful when the buyer already knows what it wants and
+          only needs details for one domain (e.g., just media_buy capabilities).
+        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 filtered to the requested protocol domain. The response
+          should include the same structure but only the requested domain details.
+
+        sample_request:
+          protocols:
+            - "media_buy"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"