@adcp/client 4.22.1 → 4.24.0

package/storyboards/creative_generative.yaml

@@ -0,0 +1,317 @@
+id: creative_generative
+version: "1.0.0"
+title: "Generative creative agent"
+category: creative_generative
+summary: "Agent that takes a brief and generates finished creatives from scratch — no input assets required."
+
+narrative: |
+  You run a generative creative platform — an AI ad network, a generative DSP, or any system
+  that creates ad creatives from a natural-language brief and brand identity. The buyer doesn't
+  push assets to you. Instead, they describe what they want, point you at a brand.json, and
+  your agent produces finished creatives ready for trafficking.
+
+  This is fundamentally different from template-based transformation (Celtra) or library-based
+  retrieval (Innovid). Your agent creates something new. The buyer sends a brief, optionally
+  with seed assets or constraints, and your platform generates creatives — potentially in
+  multiple formats at once.
+
+  This storyboard walks through the generation flow: format discovery, brief-driven generation,
+  multi-format builds, iterative refinement, and quality progression from draft to production.
+
+agent:
+  interaction_model: stateless_generate
+  capabilities:
+    - supports_generation
+  examples:
+    - "OpenAds"
+    - "AI ad networks"
+    - "Generative DSPs"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity (brand.json at the brand's domain) for the agent
+    to resolve visual identity — logos, colors, fonts, tone. The test kit provides a
+    sample brand with campaign parameters.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: format_discovery
+    title: "Discover generative formats"
+    narrative: |
+      The buyer needs to know what your agent can generate. Unlike a template platform
+      where formats are fixed dimensions, generative formats describe what the agent
+      produces — the output type, constraints, and what inputs it accepts. A generative
+      format might be "display_300x250_generative" that accepts a brief and produces
+      a finished banner, or "social_post_generative" that creates platform-native content.
+
+    steps:
+      - id: discover_formats
+        title: "Discover available generative formats"
+        narrative: |
+          The buyer asks: "What can you generate?" Your platform returns the formats
+          you support. Each format describes the output type, dimensions, and what
+          inputs it needs (brief text, brand reference, seed images, etc.).
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_sync
+        stateful: false
+        expected: |
+          Return your generative formats. Each format should include:
+          - format_id with your agent_url and a unique id
+          - Human-readable name and description
+          - Asset slots describing what inputs are accepted (brief text, images, etc.)
+          - Render dimensions for the output
+          - Variables for any dynamic fields the buyer can control
+
+        sample_request: {}
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains a formats array"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Each format has a format_id with agent_url"
+
+  - id: generate_from_brief
+    title: "Generate from brief"
+    narrative: |
+      The buyer describes what they want in natural language and your agent generates
+      a creative from scratch. The brief includes the campaign message, target audience
+      context, and a brand reference so your agent can resolve visual identity.
+
+      This is the core generative flow. The buyer doesn't provide finished assets —
+      they provide intent, and your agent creates.
+
+    steps:
+      - id: build_draft
+        title: "Generate a draft creative from brief"
+        narrative: |
+          The buyer sends a brief describing the campaign and a target format. Your
+          agent generates a draft creative — fast, lower-fidelity output the buyer can
+          review before committing to a production build.
+
+          The brief is passed as a message alongside the target format. The brand
+          reference lets your agent resolve brand.json for visual identity.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a generated creative manifest:
+          - creative_manifest with the generated assets (images, copy, serving code)
+          - format_id matching the target format
+          - If include_preview is true, include a preview render
+
+          The output should be a coherent creative that reflects the brief and brand
+          identity — not a template with placeholder text.
+
+        sample_request:
+          message: "Create a display banner for a summer outdoor gear sale. Bold, adventurous tone. Headline should emphasize 40% off. Target audience: active adults 25-54."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          brand:
+            domain: "acme-outdoor.example.com"
+          quality: "draft"
+          include_preview: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Output manifest includes generated assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Output manifest includes format_id"
+
+  - id: refine
+    title: "Refine the creative"
+    narrative: |
+      The buyer reviews the draft and wants changes. They send the generated manifest
+      back with refinement instructions. Your agent modifies the creative based on the
+      feedback — adjusting copy, swapping imagery, or changing the layout.
+
+      This is iterative: the buyer can refine multiple times until they're satisfied,
+      then request a production-quality build.
+
+    steps:
+      - id: refine_creative
+        title: "Refine with feedback"
+        narrative: |
+          The buyer passes the generated manifest back with a message describing what
+          to change. Your agent applies the refinements and returns an updated creative.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a refined creative manifest reflecting the requested changes.
+          The output should preserve what worked in the original while applying
+          the refinements.
+
+        sample_request:
+          message: "Make the headline larger. Replace the mountain imagery with a trail running scene. Add a CTA button that says 'Shop Now'."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              - asset_id: "generated_image"
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123.jpg"
+              - asset_id: "headline"
+                asset_type: "text"
+                text: "Summer Sale — 40% Off All Gear"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          brand:
+            domain: "acme-outdoor.example.com"
+          quality: "draft"
+          include_preview: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Refined manifest includes assets"
+
+  - id: multi_format
+    title: "Multi-format generation"
+    narrative: |
+      The buyer needs the creative in multiple sizes. Instead of generating each
+      format separately, they pass target_format_ids (plural) and your agent produces
+      all formats in a single call. This is where generative agents shine — adapting
+      a concept across formats while maintaining visual coherence.
+
+    steps:
+      - id: build_multi_format
+        title: "Generate for multiple formats"
+        narrative: |
+          The buyer passes the refined manifest with multiple target formats. Your
+          agent generates a creative for each format, adapting layout, copy, and
+          imagery to fit each size while maintaining brand consistency.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return creative manifests for each requested format in creative_manifests
+          (plural). Each manifest should:
+          - Have a format_id matching one of the target formats
+          - Contain complete, format-appropriate assets
+          - Maintain visual coherence across formats
+
+          If a format cannot be produced, include it with an error — don't fail
+          the entire request.
+
+        sample_request:
+          message: "Generate production-ready versions for all three sizes."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              - asset_id: "generated_image"
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123-refined.jpg"
+              - asset_id: "headline"
+                asset_type: "text"
+                text: "Summer Sale — 40% Off All Gear"
+              - asset_id: "cta"
+                asset_type: "text"
+                text: "Shop Now"
+          target_format_ids:
+            - agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_728x90_generative"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_320x50_generative"
+          brand:
+            domain: "acme-outdoor.example.com"
+          quality: "production"
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifests"
+            description: "Response contains creative_manifests array (plural)"
+
+  - id: production_build
+    title: "Production build"
+    narrative: |
+      The buyer is satisfied with the concept and needs a final, production-quality
+      creative ready for trafficking. They switch quality from draft to production.
+      Your agent generates the finished output with full-fidelity assets.
+
+    steps:
+      - id: build_production
+        title: "Build at production quality"
+        narrative: |
+          The buyer requests a production-quality build of the approved concept. Your
+          agent generates the final creative with full-fidelity rendering, polished
+          assets, and serving code ready for trafficking.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a production-quality creative manifest:
+          - Full-fidelity generated assets
+          - Serving code (HTML, JavaScript, or VAST) ready for trafficking
+          - Provenance metadata if AI-generated (digital_source_type, ai_tool)
+
+        sample_request:
+          message: "Final production build. No changes needed."
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250_generative"
+            assets:
+              - asset_id: "generated_image"
+                asset_type: "image"
+                url: "https://your-agent.example.com/generated/abc123-refined.jpg"
+              - asset_id: "headline"
+                asset_type: "text"
+                text: "Summer Sale — 40% Off All Gear"
+              - asset_id: "cta"
+                asset_type: "text"
+                text: "Shop Now"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250_generative"
+          brand:
+            domain: "acme-outdoor.example.com"
+          quality: "production"
+          include_preview: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Production manifest includes assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Production manifest includes format_id"

package/storyboards/creative_lifecycle.yaml

@@ -0,0 +1,284 @@
+id: creative_lifecycle
+version: "1.0.0"
+title: "Creative lifecycle"
+category: creative_lifecycle
+summary: "Full creative lifecycle on a stateful platform: sync multiple creatives, list with filtering, build and preview across formats, observe status transitions."
+track: creative
+required_tools:
+  - list_creative_formats
+
+narrative: |
+  You run a creative platform with a persistent library — an ad server, creative management
+  platform, or publisher that accepts and stores creative assets. A buyer agent pushes
+  multiple creatives in different formats, queries the library, builds serving tags, previews
+  renderings, and monitors creative status as assets move through your review pipeline.
+
+  This storyboard covers the complete creative lifecycle from the buyer's perspective:
+  uploading assets, browsing the library, building deliverables across formats, and
+  observing status transitions as creatives move from pending_review through to accepted.
+
+  The individual creative storyboards (template, ad server, sales agent) cover specific
+  interaction models. This storyboard tests the full lifecycle across multiple creatives
+  and formats on a single platform.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - has_creative_library
+    - supports_transformation
+  examples:
+    - "Innovid"
+    - "Flashtalking"
+    - "CM360"
+    - "Creative management platforms"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs creative assets in multiple formats (display, video, native) and
+    a brand identity. The test kit provides sample assets at standard ad dimensions.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover_formats
+    title: "Discover accepted formats"
+    narrative: |
+      Before pushing any creatives, the buyer discovers what formats your platform accepts.
+      This determines which assets to prepare and what dimensions and specs to target.
+
+    steps:
+      - id: list_formats
+        title: "List creative formats"
+        narrative: |
+          The buyer calls list_creative_formats to discover what your platform accepts.
+          The response defines format specs: dimensions, asset requirements, mime types,
+          and any platform-specific constraints.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_lifecycle
+        stateful: false
+        expected: |
+          Return all creative formats your platform accepts:
+          - format_id with your agent_url and unique id
+          - Asset requirements (dimensions, file sizes, mime types)
+          - Render dimensions
+          - At least two formats (e.g., display and video)
+
+        sample_request: {}
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains formats array"
+
+  - id: sync_multiple
+    title: "Sync multiple creatives"
+    narrative: |
+      The buyer pushes three creatives in different formats to your platform: a display
+      banner, a video spot, and a native card. Your platform validates each creative
+      against its format specs and returns per-creative status.
+
+    steps:
+      - id: sync_creatives
+        title: "Push three creatives in different formats"
+        narrative: |
+          The buyer syncs three creatives simultaneously: a 300x250 display banner, a 30s
+          video spot, and a native content card. Your platform validates each against its
+          format specs and returns per-creative action and status.
+        task: sync_creatives
+        schema_ref: "creative/sync-creatives-request.json"
+        response_schema_ref: "creative/sync-creatives-response.json"
+        doc_ref: "/creative/task-reference/sync_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Accept and validate all three creatives:
+          - Per-creative action: created
+          - Per-creative status: accepted or pending_review
+          - Validation results for each creative
+          - Platform-assigned IDs if applicable
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          creatives:
+            - creative_id: "display_trail_pro_300x250"
+              name: "Trail Pro 3000 - Display 300x250"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                - asset_id: "image"
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-300x250.png"
+                  mime_type: "image/png"
+            - creative_id: "video_30s_trail_pro"
+              name: "Trail Pro 3000 - 30s Video"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "video_30s"
+              assets:
+                - asset_id: "video"
+                  asset_type: "video"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-30s.mp4"
+                  mime_type: "video/mp4"
+            - creative_id: "native_trail_pro"
+              name: "Trail Pro 3000 - Native Card"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "native_content"
+              assets:
+                - asset_id: "image"
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-native.png"
+                  mime_type: "image/png"
+                - asset_id: "headline"
+                  asset_type: "text"
+                  content: "Trail Pro 3000 — Built for the Summit"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "results"
+            description: "Response contains per-creative results"
+
+  - id: list_and_filter
+    title: "List creatives with filtering"
+    narrative: |
+      The buyer queries the creative library to see their synced creatives. First a broad
+      list, then filtered by format. This verifies the library correctly stores and indexes
+      the pushed creatives.
+
+    steps:
+      - id: list_all
+        title: "List all creatives in library"
+        narrative: |
+          The buyer calls list_creatives with no filters to see all creatives in the
+          library for their account. The response includes the three creatives synced
+          in the previous phase.
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Return creatives in the library:
+          - creatives array containing the synced items
+          - Each creative includes: creative_id, name, format_id, status
+          - At least three creatives from the sync phase
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json schema"
+          - check: field_present
+            path: "creatives"
+            description: "Response contains creatives array"
+
+      - id: list_filtered
+        title: "List creatives filtered by format"
+        narrative: |
+          The buyer lists creatives filtered to a specific format (display only). The
+          response should only include creatives matching that format.
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Return only creatives matching the format filter:
+          - creatives array filtered to display format
+          - Should include display_trail_pro_300x250 but not video or native
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          filters:
+            format_ids:
+              - agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json schema"
+          - check: field_present
+            path: "creatives"
+            description: "Response contains filtered creatives"
+
+  - id: build_and_preview
+    title: "Build and preview across formats"
+    narrative: |
+      The buyer builds serving tags and previews renderings for the synced creatives.
+      This tests multi-format output: a display tag, a VAST tag for video, and a
+      native rendering preview.
+
+    steps:
+      - id: preview_display
+        title: "Preview the display creative"
+        narrative: |
+          The buyer calls preview_creative for the display banner to see how it renders
+          in the platform's environment before going live.
+        task: preview_creative
+        schema_ref: "creative/preview-creative-request.json"
+        response_schema_ref: "creative/preview-creative-response.json"
+        doc_ref: "/creative/task-reference/preview_creative"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Return a preview of the display creative:
+          - preview_url: rendered preview the buyer can inspect
+          - render_dimensions: matches the 300x250 format
+          - status: preview available
+
+        sample_request:
+          creative_id: "display_trail_pro_300x250"
+
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+
+      - id: build_video_tag
+        title: "Build a VAST tag for the video creative"
+        narrative: |
+          The buyer builds a serving tag for the video creative. The platform produces
+          a VAST-compatible tag that the buyer can traffic to ad servers.
+        task: build_creative
+        schema_ref: "creative/build-creative-request.json"
+        response_schema_ref: "creative/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Return a built serving tag for the video creative:
+          - tag: VAST-compatible serving tag or URL
+          - format: matches the video format
+          - creative_id: matches the requested creative
+
+        sample_request:
+          creative_id: "video_30s_trail_pro"
+          output_format:
+            agent_url: "https://your-platform.example.com"
+            id: "vast_30s"
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"

package/storyboards/creative_sales_agent.yaml

@@ -3,14 +3,10 @@ version: "1.0.0"
 title: "Sales agent with creative capabilities"
 category: creative_sales_agent
 summary: "Stateful sales agent that accepts pushed creative assets and renders them in its environment."
-platform_types:
-  - retail_media
-  - social_platform
-
 track: creative
 required_tools:
   - sync_creatives
-  - list_creative_formats
+
 narrative: |
   You run a publisher platform, retail media network, or other sell-side system that
   accepts creative assets from buyers. The buyer pushes assets or catalog items to your
@@ -165,5 +161,5 @@ phases:
           - check: response_schema
             description: "Response matches preview-creative-response.json schema"
           - check: field_present
-            path: "previews[0].renders[0].url"
+            path: "previews[0].renders[0].preview_url"
             description: "Preview includes a renderable URL"

package/storyboards/creative_template.yaml

@@ -3,14 +3,10 @@ version: "1.0.0"
 title: "Creative template and transformation agent"
 category: creative_template
 summary: "Stateless creative agent that takes assets in, applies templates, and produces tags or rendered output."
-platform_types:
-  - creative_transformer
-  - creative_library
-
 track: creative
 required_tools:
   - build_creative
-  - list_creative_formats
+
 narrative: |
   You build a creative management or rich media platform — think Celtra, a format
   conversion service, or any tool that defines ad templates and transforms input assets
@@ -122,6 +118,7 @@ phases:
             description: "Response matches schema"
           - check: field_value
             path: "formats[*].type"
+            value: "display"
             description: "All returned formats are display type"
 
   - id: preview
@@ -186,7 +183,7 @@ phases:
           - check: response_schema
             description: "Response matches preview-creative-response.json schema"
           - check: field_present
-            path: "previews[0].renders[0].url"
+            path: "previews[0].renders[0].preview_url"
             description: "Preview includes a renderable URL"
 
   - id: build