@adcp/client 4.21.0 → 4.22.1

package/storyboards/brand_rights.yaml

@@ -0,0 +1,131 @@
+id: brand_rights
+version: "1.0.0"
+title: "Brand rights flow"
+category: brand_rights
+summary: "Agent that provides brand identity, queries rights, and supports rights acquisition."
+track: core
+required_tools:
+  - get_brand_identity
+
+narrative: |
+  You run a brand rights platform — a system that manages brand identity information,
+  tracks rights associated with brands, and facilitates rights acquisition. A caller
+  connects to retrieve brand identity details, query existing rights, and initiate
+  new rights acquisitions.
+
+  The caller starts by fetching the brand identity for a given domain. Then they
+  query what rights are currently associated with that brand. Finally, they request
+  acquisition of additional rights, optionally in dry_run mode to preview without
+  committing.
+
+  This storyboard walks through the complete brand rights flow from discovery
+  through acquisition.
+
+agent:
+  interaction_model: brand_rights
+  capabilities:
+    - brand_identity
+    - rights_management
+  examples:
+    - "Brand registry platforms"
+    - "Rights management systems"
+    - "Brand safety and compliance platforms"
+
+caller:
+  role: buyer_agent
+  example: "Agency brand compliance tool"
+
+prerequisites:
+  description: |
+    The caller needs a brand domain to query. The test uses example.com as a
+    default domain suitable for validating the brand rights protocol flow.
+
+phases:
+  - id: brand_rights_flow
+    title: "Brand rights flow"
+    narrative: |
+      The caller retrieves brand identity, queries existing rights, and initiates
+      rights acquisition. Each step builds on the previous: the brand identity
+      confirms the brand exists, the rights query shows what is already held,
+      and the acquisition request adds new rights.
+
+    steps:
+      - id: get_brand_identity
+        title: "Retrieve brand identity"
+        narrative: |
+          The caller requests brand identity information for a specific domain.
+          The agent returns the brand name, domain, and any associated guidelines
+          or metadata. This confirms the brand is known to the platform.
+        task: get_brand_identity
+        stateful: false
+        expected: |
+          Return the brand identity:
+          - request_id: echoes the caller's request_id
+          - brand_name: human-readable brand name
+          - brand_domain: the queried domain
+          - guidelines: brand usage guidelines (optional)
+
+        sample_request:
+          type: "get_brand_identity_request"
+          request_id: "e2e-brand-id-001"
+          brand_domain: "example.com"
+
+        validations:
+          - check: field_present
+            path: "brand_name"
+            description: "Response includes the brand name"
+          - check: field_present
+            path: "brand_domain"
+            description: "Response includes the brand domain"
+
+      - id: get_rights
+        title: "Query current brand rights"
+        requires_tool: get_rights
+        narrative: |
+          The caller queries what rights are currently associated with the brand.
+          The agent returns a list of rights with their types, scopes, and
+          expiration dates.
+        task: get_rights
+        stateful: false
+        expected: |
+          Return the current rights:
+          - request_id: echoes the caller's request_id
+          - rights: array of right objects, each with type, scope, and optional expires_at
+
+        sample_request:
+          type: "get_rights_request"
+          request_id: "e2e-rights-001"
+          brand_domain: "example.com"
+
+        validations:
+          - check: field_present
+            path: "rights"
+            description: "Response includes a rights array"
+
+      - id: acquire_rights
+        title: "Acquire brand rights"
+        requires_tool: acquire_rights
+        narrative: |
+          The caller initiates acquisition of brand rights. The dry_run flag
+          allows previewing the acquisition without committing. The agent
+          returns the acquisition status and a rights_id for tracking.
+        task: acquire_rights
+        stateful: true
+        expected: |
+          Return the acquisition result:
+          - request_id: echoes the caller's request_id
+          - status: granted, pending, denied, or dry_run
+          - rights_id: identifier for the acquired or pending rights
+          - dry_run: true when the request was a preview
+
+        sample_request:
+          type: "acquire_rights_request"
+          request_id: "e2e-acquire-001"
+          brand_domain: "example.com"
+          rights_type: "usage"
+          dry_run: true
+
+        validations:
+          - check: field_present
+            path: "status"
+            description: "Response includes acquisition status"

package/storyboards/creative_ad_server.yaml

@@ -0,0 +1,171 @@
+id: creative_ad_server
+version: "1.0.0"
+title: "Creative ad server"
+category: creative_ad_server
+summary: "Stateful ad server with pre-loaded creatives. Generates serving tags per media buy."
+platform_types:
+  - creative_ad_server
+
+track: creative
+required_tools:
+  - build_creative
+  - sync_creatives
+narrative: |
+  You run a creative ad server — think Innovid, Flashtalking, or CM360. Your clients
+  have already uploaded their creatives through your UI. Buyers connect to browse your
+  creative library and request serving tags for their media buys.
+
+  Your agent is stateful: creatives already exist in your system. The buyer never pushes
+  assets to you. Instead, they browse your library, pick creatives, and ask you to generate
+  tags for specific placements. For a campaign with 25 media buys, you'll generate 25 tags.
+
+  This storyboard walks through that flow from the buyer's perspective.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - has_creative_library
+  examples:
+    - "Innovid"
+    - "Flashtalking"
+    - "CM360"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    Creatives must already exist in the ad server's library, loaded through the
+    platform's own UI or API. The buyer does not push assets — they browse and
+    request tags for what's already there.
+
+phases:
+  - id: browse_library
+    title: "Browse the creative library"
+    narrative: |
+      The buyer connects to your ad server and wants to see what creatives are
+      available for a campaign. They call list_creatives to browse concepts and
+      individual creatives in your library.
+
+      For an Innovid-like platform, this returns the advertiser's uploaded video
+      creatives, display ads, and any other assets managed in the platform.
+
+    steps:
+      - id: list_creatives
+        title: "Browse available creatives"
+        narrative: |
+          The buyer asks: "What creatives do you have for this advertiser?" This is
+          the primary entry point for ad server interactions — the buyer browses your
+          library to find creatives to use in their media buys.
+        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_flow
+        stateful: true
+        expected: |
+          Return creatives from your library. Each creative should include:
+          - creative_id (your platform's identifier)
+          - format_id referencing the creative's format
+          - name and status (approved, pending_review, rejected)
+          - concept_id grouping related creatives across sizes
+
+      - id: list_output_formats
+        title: "Check available output formats"
+        narrative: |
+          The buyer checks what output formats your ad server supports. For an ad
+          server, this is typically the tag formats you can generate — HTML, JavaScript,
+          VAST, native. The input formats are less relevant because creatives are already
+          in your system.
+        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 the output formats you support. For an ad server, these are typically
+          tag formats (HTML, JavaScript, VAST) rather than visual ad formats.
+
+  - id: generate_tags
+    title: "Generate serving tags"
+    narrative: |
+      The buyer has selected creatives from your library and now needs serving tags
+      for their media buys. They call build_creative for each media buy/package
+      combination, passing the creative_id and the context needed to generate the
+      right tag.
+
+      This is the core of the ad server interaction: turning library creatives into
+      traffickable tags.
+
+    steps:
+      - id: build_tag
+        title: "Generate a tag for a media buy"
+        narrative: |
+          The buyer requests a serving tag for a specific creative, format, and media
+          buy. Your ad server generates a tag scoped to that placement.
+
+          For Innovid, this produces a VAST tag for a CTV placement. For Flashtalking,
+          this might produce an HTML tag for a display placement. The media_buy_id and
+          package_id provide the trafficking context.
+        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: true
+        expected: |
+          Return a creative manifest with the serving tag. The output should include:
+          - An HTML, JavaScript, or VAST asset containing the tag
+          - The format_id matching the target format
+          - Macro placeholders (CLICK_URL, CACHEBUSTER) if applicable
+
+        sample_request:
+          creative_id: "campaign_hero_video"
+          target_format_id:
+            agent_url: "https://your-ad-server.example.com"
+            id: "vast_30s"
+          media_buy_id: "mb_summer_campaign_001"
+          package_id: "pkg_ctv_premium"
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Output includes a serving tag asset"
+
+  - id: track_delivery
+    title: "Track creative delivery"
+    narrative: |
+      After the campaign runs, the buyer checks how each creative performed. They call
+      get_creative_delivery to get variant-level delivery data — impressions, spend, and
+      breakdowns by creative variant.
+
+    steps:
+      - id: get_delivery
+        title: "Get creative delivery metrics"
+        narrative: |
+          The buyer asks: "How did my creatives perform across the media buys?" Your ad
+          server returns delivery data per creative, including impressions, spend, and
+          variant-level breakdowns.
+        task: get_creative_delivery
+        schema_ref: "creative/get-creative-delivery-request.json"
+        response_schema_ref: "creative/get-creative-delivery-response.json"
+        doc_ref: "/creative/task-reference/get_creative_delivery"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Return per-creative delivery metrics including:
+          - Impressions and spend per creative
+          - Variant-level breakdowns (which version of each creative was served)
+          - Media buy context (which buys each creative was active on)
+
+        sample_request:
+          media_buy_ids:
+            - "mb_summer_campaign_001"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-creative-delivery-response.json schema"

package/storyboards/creative_sales_agent.yaml

@@ -0,0 +1,169 @@
+id: creative_sales_agent
+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
+  platform, and you render them in your environment.
+
+  Your agent is stateful: buyers push creatives to you via sync_creatives, and you
+  persist them for rendering. This is where catalogs get interesting — the buyer might
+  push product feeds (flights, hotels, retail products) that your platform renders as
+  native ads.
+
+  This storyboard walks through the push-and-preview flow from the buyer's perspective.
+
+agent:
+  interaction_model: stateful_push
+  capabilities:
+    - has_creative_library
+  examples:
+    - "Publisher platforms"
+    - "Retail media networks"
+    - "Native ad platforms"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The buyer has creative assets (images, catalog feeds, or ad tags) ready to push.
+    The test kit provides sample assets compatible with common publisher formats.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover_accepted_formats
+    title: "Discover accepted formats"
+    narrative: |
+      The buyer first needs to know what creative formats your platform accepts.
+      For a publisher, this includes your native ad formats, display placements,
+      and any custom units. For retail media, this might include product listing
+      formats or sponsored product cards.
+
+    steps:
+      - id: list_formats
+        title: "Discover accepted creative formats"
+        narrative: |
+          The buyer asks: "What creative formats does your platform accept?" Your
+          platform returns the formats you support — native post formats, display
+          units, video slots, or product listing formats.
+        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 the creative formats your platform accepts. Each format should define:
+          - Asset requirements (what the buyer needs to provide)
+          - Render dimensions
+          - Any catalog requirements (for product-feed formats)
+
+  - id: push_creatives
+    title: "Push creative assets"
+    narrative: |
+      The buyer pushes their creative assets to your platform. This could be:
+      - Standard display assets (images, HTML tags)
+      - Catalog items (product feeds, flight listings, hotel inventory)
+      - Native ad content (headlines, descriptions, images)
+
+      Your platform validates the assets against your format specs and stores them.
+
+    steps:
+      - id: sync_creatives
+        title: "Push creatives to the platform"
+        narrative: |
+          The buyer uploads creative assets to your platform. For standard ads, this
+          is images and copy. For catalog-driven formats, this is a product feed or
+          set of catalog items. Your platform validates each creative against the
+          format's asset requirements and returns a per-creative 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_sync
+        stateful: true
+        expected: |
+          Accept the creatives, validate against format specifications, and return:
+          - Per-creative action (created or updated)
+          - Per-creative status (accepted, pending_review, rejected)
+          - Platform-assigned IDs if applicable
+          - Validation errors for rejected creatives
+
+        sample_request:
+          creatives:
+            - creative_id: "acme_summer_native_001"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "native_post"
+              assets:
+                - asset_id: "headline"
+                  asset_type: "text"
+                  text: "Summer Sale — 40% Off All Gear"
+                - asset_id: "image"
+                  asset_type: "image"
+                  url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-master.jpg"
+                - asset_id: "click_url"
+                  asset_type: "url"
+                  url: "https://acme-outdoor.example.com/summer-sale"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "creatives[0].action"
+            description: "Each creative has an action (created/updated)"
+
+  - id: preview
+    title: "Preview pushed creatives"
+    narrative: |
+      After pushing assets, the buyer wants to see how their creatives will render
+      in your platform's environment. For a publisher, this shows the ad in the
+      publication's native chrome — with engagement buttons, community badges, and
+      platform-specific styling that the buyer can't preview elsewhere.
+
+    steps:
+      - id: preview_synced
+        title: "Preview a pushed creative"
+        narrative: |
+          The buyer asks to see how a synced creative will look in your environment.
+          Your platform renders the creative with its native chrome — the surrounding
+          UI, engagement buttons, and platform-specific styling.
+        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 showing the creative in your platform's environment.
+          The preview should include your platform's native chrome — not just the
+          raw assets, but how they'll actually appear to users.
+
+        sample_request:
+          request_type: "single"
+          creative_manifest:
+            creative_id: "acme_summer_native_001"
+            format_id:
+              agent_url: "https://your-platform.example.com"
+              id: "native_post"
+          output_format: "url"
+          quality: "draft"
+
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+          - check: field_present
+            path: "previews[0].renders[0].url"
+            description: "Preview includes a renderable URL"