@adcp/client 4.20.0 → 4.22.0

package/storyboards/media_buy_governance_escalation.yaml

@@ -0,0 +1,467 @@
+id: media_buy_governance_escalation
+version: "1.0.0"
+title: "Governance denial and human escalation"
+category: media_buy_governance_escalation
+summary: "Buyer's governance agent denies a media buy that exceeds spending authority, escalates to a human who approves with conditions."
+platform_types:
+  - dsp
+  - ai_ad_network
+  - generative_dsp
+
+track: campaign_governance
+required_tools:
+  - sync_plans
+narrative: |
+  The buyer's governance agent denies a media buy because it exceeds the agent's spending
+  authority. The governance check escalates to a human reviewer who approves with conditions.
+
+  This storyboard shows the full governance loop: plan registration with spending authority
+  limits, product discovery, pre-buy governance check that gets denied, human escalation
+  that results in conditional approval, media buy creation with the approved governance
+  context, outcome reporting, and a complete audit trail.
+
+  Governance exists to ensure that automated agents operate within defined boundaries. When
+  those boundaries are exceeded, the system escalates to humans rather than blocking
+  entirely. The audit trail provides accountability for every decision in the chain.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher platform integrated with buyer governance"
+    - "SSP that respects governance checks"
+    - "Retail media network with governance support"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, and a governance agent
+    URL. The test kit provides a sample brand (Acme Outdoor) with campaign parameters
+    and a governance configuration with spending authority limits.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: account_setup
+    title: "Account and governance setup"
+    narrative: |
+      The buyer establishes an account and registers their governance agent with the
+      seller. The governance agent will be called before media buys are confirmed to
+      validate spending authority, brand safety, and compliance.
+
+    steps:
+      - id: sync_accounts
+        title: "Establish account relationship"
+        narrative: |
+          The buyer registers their brand and operator with your platform.
+        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: |
+          Return the account with:
+          - account_id: your platform's identifier
+          - action: created or updated
+          - status: active or pending_approval
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+              billing: "operator"
+              payment_terms: "net_30"
+
+        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"
+        narrative: |
+          The buyer tells your platform: "Before you confirm any media buy for this
+          account, call this governance agent to validate it." Your platform stores
+          the governance agent URL and will call it during create_media_buy.
+        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: |
+          Acknowledge the governance agents. Your platform should:
+          - Store the governance agent URLs for the specified accounts
+          - Return confirmation that agents were registered
+          - Use these agents during create_media_buy validation
+
+        sample_request:
+          accounts:
+            - account:
+                brand:
+                  domain: "acmeoutdoor.com"
+                operator: "pinnacle-agency.com"
+              governance_agents:
+                - url: "https://governance.pinnacle-agency.example"
+                  authentication:
+                    schemes: ["Bearer"]
+                    credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+                  categories: ["budget_authority", "brand_policy"]
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-governance-response.json schema"
+
+  - id: register_plan
+    title: "Register governance plan with spending limits"
+    narrative: |
+      The buyer registers a governance plan that defines the agent's spending authority.
+      The plan sets a per-transaction threshold below the intended media buy amount.
+      This ensures the governance check will trigger an escalation when the buy exceeds
+      the agent's authority.
+
+    steps:
+      - id: sync_plans
+        title: "Register a governance plan with agent-limited authority"
+        narrative: |
+          The buyer's governance agent registers a plan with spending authority limits.
+          The authority_level is agent_limited with a per-transaction threshold of $20K.
+          Any media buy above this amount requires human approval.
+        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: |
+          Acknowledge the governance plan:
+          - plan_id: identifier for this governance plan
+          - authority_level: agent_limited
+          - per_transaction_threshold: the spending limit before escalation
+          - escalation_path: how over-limit transactions are handled
+
+        sample_request:
+          plans:
+            - plan_name: "Acme Outdoor Q2 Governance"
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+              authority_level: "agent_limited"
+              per_transaction_threshold: 20000
+              escalation_path: "human_review"
+              conditions:
+                - "Weekly reporting required for buys over $10K"
+                - "No single-seller concentration above 60% of total budget"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: discover_products
+    title: "Product discovery"
+    narrative: |
+      The buyer sends a brief to discover products. The products returned will exceed
+      the governance agent's spending authority when assembled into a media buy.
+
+    steps:
+      - id: get_products_brief
+        title: "Send a brief"
+        narrative: |
+          The buyer describes what they want. Your platform returns products with
+          pricing that, when combined, will exceed the $20K per-transaction threshold
+          set in the governance plan.
+        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"
+        stateful: false
+        expected: |
+          Return products matching the brief with pricing that totals above $20K:
+          - product_id, name, description
+          - delivery_type: guaranteed or non_guaranteed
+          - pricing_models with CPM and budget recommendations
+          - forecast: estimated delivery
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium CTV and video on sports publishers. Q2 flight, $50K budget. Adults 25-54, US."
+          brand:
+            domain: "acmeoutdoor.com"
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+
+  - id: governance_check_denied
+    title: "Governance check — denied"
+    narrative: |
+      Before creating the media buy, the buyer's governance agent runs a pre-buy check.
+      The proposed buy totals $50K, which exceeds the agent's $20K per-transaction
+      authority. The governance agent denies the buy with a must-severity finding and
+      returns escalation instructions for human review.
+
+    steps:
+      - id: check_governance_denied
+        title: "Pre-buy governance check (denied)"
+        narrative: |
+          The buyer calls check_governance with the proposed media buy binding. The
+          governance agent evaluates the buy against the registered plan and finds that
+          the total exceeds the agent's spending authority. The check returns denied
+          with a must-severity finding and instructions for escalating to a human.
+        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"
+        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 agent's authority limit and how much the buy exceeds it
+            - escalation: instructions for human review
+          - governance_context: token/ID the buyer passes to the next check after escalation
+          - plan_id: the governance plan that triggered the denial
+
+        sample_request:
+          plan_id: "gov_acme_q2_2026"
+          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_present
+            path: "findings"
+            description: "Response contains findings explaining the denial"
+
+  - id: human_escalation
+    title: "Human escalation — conditional approval"
+    narrative: |
+      The governance denial triggers human escalation. A human reviewer at the agency
+      reviews the proposed buy, the denial reason, and the governance plan. The human
+      approves the buy with conditions — for example, requiring weekly reporting. The
+      buyer calls check_governance again with the human's approval, and this time
+      the check returns approved with conditions.
+
+    steps:
+      - id: check_governance_approved
+        title: "Re-check governance after human approval (approved with conditions)"
+        narrative: |
+          After the human reviewer approves the buy, the buyer calls check_governance
+          again with the governance_context from the prior denial and the human's
+          approval. The governance agent returns approved with conditions that the
+          buyer must honor during the campaign.
+        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"
+        stateful: true
+        expected: |
+          Return an approved governance decision with conditions:
+          - decision: approved
+          - conditions: array of requirements the buyer must honor
+            - e.g., "Weekly delivery reporting required"
+            - e.g., "Human review required for any budget increase"
+          - governance_context: updated token the buyer passes to create_media_buy
+          - approved_by: identifier of the human who approved
+          - approved_at: timestamp of approval
+
+        sample_request:
+          plan_id: "gov_acme_q2_2026"
+          governance_context: "gov_ctx_acme_q2_escalated"
+          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
+          human_approval:
+            approved_by: "jsmith@pinnacle-agency.com"
+            approved_at: "2026-04-03T14:22:00Z"
+            conditions:
+              - "Weekly delivery reporting required"
+              - "Human review required for any budget increase above 10%"
+
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "decision"
+            description: "Response contains an approved governance decision"
+          - check: field_present
+            path: "conditions"
+            description: "Approval includes conditions"
+
+  - id: create_buy_with_governance
+    title: "Create media buy with governance context"
+    narrative: |
+      The buyer creates the media buy, passing the governance_context from the approved
+      governance check. The seller's platform verifies the governance approval before
+      confirming the buy.
+
+    steps:
+      - id: create_media_buy
+        title: "Create a media buy with governance approval"
+        narrative: |
+          The buyer creates the media buy with the governance_context token from the
+          approved check. The seller's platform validates the governance approval and
+          confirms the buy. Without a valid governance_context, the platform would
+          reject the buy because the governance agent is registered for this account.
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        stateful: true
+        expected: |
+          Confirm the media buy with governance approval:
+          - media_buy_id: your platform's identifier
+          - status: confirmed or active
+          - confirmed_at: timestamp
+          - governance_context: echoed back confirming governance was validated
+          - packages: confirmed line items
+          - valid_actions: creative sync, get_delivery, etc.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          brand:
+            domain: "acmeoutdoor.com"
+          governance_context: "gov_ctx_acme_q2_approved"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_ctv_q2"
+              budget: 30000
+              pricing_option_id: "cpm_guaranteed"
+              creative_assignments:
+                - creative_id: "video_30s_trail_pro"
+            - product_id: "outdoor_video_q2"
+              budget: 20000
+              pricing_option_id: "cpm_standard"
+              creative_assignments:
+                - creative_id: "video_15s_trail_pro"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+
+  - id: report_outcome
+    title: "Report governance outcome"
+    narrative: |
+      After the media buy is created, the buyer reports the outcome back to the
+      governance agent. This closes the governance loop by linking the actual media
+      buy to the governance check that authorized it.
+
+    steps:
+      - id: report_plan_outcome
+        title: "Report media buy outcome to governance"
+        narrative: |
+          The buyer reports the media buy creation back to the governance agent,
+          linking the media_buy_id to the governance check. This enables the governance
+          agent to track what was actually purchased against what was approved.
+        task: report_plan_outcome
+        schema_ref: "governance/report-plan-outcome-request.json"
+        response_schema_ref: "governance/report-plan-outcome-response.json"
+        doc_ref: "/governance/campaign/tasks/report_plan_outcome"
+        stateful: true
+        expected: |
+          Acknowledge the outcome report:
+          - outcome_id: identifier for this outcome record
+          - plan_id: the governance plan
+          - media_buy_id: the buy that was created
+          - governance_context: the approval that authorized it
+          - status: recorded
+
+        sample_request:
+          plan_id: "gov_acme_q2_2026"
+          governance_context: "gov_ctx_acme_q2_approved"
+          outcome:
+            type: "media_buy_created"
+            media_buy_id: "mb_acme_q2_2026"
+            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 report-plan-outcome-response.json schema"
+
+  - id: audit_trail
+    title: "Governance audit trail"
+    narrative: |
+      The buyer (or an auditor) retrieves the full audit trail for the governance
+      plan. This shows every decision in the chain: the initial denial, the human
+      escalation, the conditional approval, the media buy creation, and the outcome
+      report. The audit trail provides accountability for automated spending decisions.
+
+    steps:
+      - id: get_plan_audit_logs
+        title: "Retrieve the full governance audit trail"
+        narrative: |
+          The buyer requests the audit log for the governance plan. The log shows
+          every governance event: check requests, denials, escalations, approvals,
+          and outcome reports. Each entry has a timestamp, actor, and decision.
+        task: get_plan_audit_logs
+        schema_ref: "governance/get-plan-audit-logs-request.json"
+        response_schema_ref: "governance/get-plan-audit-logs-response.json"
+        doc_ref: "/governance/campaign/tasks/get_plan_audit_logs"
+        stateful: false
+        expected: |
+          Return the complete audit trail for the governance plan:
+          - plan_id: the governance plan
+          - entries: ordered list of governance events, including:
+            1. Plan registered with agent_limited authority and $20K threshold
+            2. Governance check denied — spending authority exceeded ($50K > $20K)
+            3. Human escalation initiated
+            4. Human approved with conditions (weekly reporting, budget increase review)
+            5. Media buy created with governance approval
+            6. Outcome reported linking media_buy_id to governance context
+          - Each entry includes: timestamp, event_type, actor, decision, details
+
+        sample_request:
+          plan_id: "gov_acme_q2_2026"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-plan-audit-logs-response.json schema"
+          - check: field_present
+            path: "entries"
+            description: "Response contains audit log entries"