Add Creative Performance Reporting Task to Creative Agent Spec

[pkras]

Problem Statement

Buyers need complete campaign performance visibility that combines:

1. Media delivery metrics from sales agents (impressions, spend, placements)
2. Creative performance metrics from creative agents/3PAS (interactions, quartiles, engagement)

Currently, AdCP only defines media delivery reporting via get_media_buy_delivery. There is no standard way for buyers to retrieve creative-specific performance data.

Why Creative Agents Are the Source of Truth

Creative companies (especially 3PAS providers acting as creative agents) instrument the creative assets and collect granular data that sales agents don't have:

• Interaction data: Button clicks, expansions, swipes, game completions
• Video engagement: Quartiles, VCR, skip rate, mute/unmute, pause/resume
• Attention metrics: Time in view, attention score, viewability
• Element performance: Which CTAs, images, headlines drove engagement
• Variant analysis: A/B test results, dynamic personalization outcomes

Sales agents provide WHERE and HOW MUCH. Creative agents provide HOW IT PERFORMED.

Proposed Solution

Add a new task to the Creative Agent specification: get_creative_performance

Buyer agents call creative agents to retrieve performance metrics.

Request Schema

{
  "task": "get_creative_performance",
  "media_buy_id": "mb_12345",
  "creative_ids": ["creative_001", "creative_002"], // optional
  "date_range": {
    "start": "2026-01-20",
    "end": "2026-01-27"
  },
  "granularity": "daily", // hourly, daily, weekly
  "metrics": [
    "interactions",
    "video_quartiles",
    "engagement_rate"
  ] // optional - request specific metrics
}

Response Schema

{
  "media_buy_id": "mb_12345",
  "date_range": {
    "start": "2026-01-20",
    "end": "2026-01-27"
  },
  "creatives": [
    {
      "creative_id": "creative_001",
      "format_id": "video_1920x1080",
      "metrics": {
        "impressions": 150000,
        "interactions": 4500,
        "interaction_rate": 0.03,
        "video": {
          "starts": 148000,
          "completions": 95000,
          "completion_rate": 0.642,
          "quartiles": {
            "25": 145000,
            "50": 130000,
            "75": 110000,
            "100": 95000
          },
          "skip_rate": 0.05,
          "mute_rate": 0.15
        },
        "engagement": {
          "average_time_engaged": 12.5,
          "expansion_rate": 0.08,
          "cta_clicks": 2100,
          "carousel_swipes": 850
        },
        "attention": {
          "attention_score": 0.78,
          "viewability_rate": 0.92,
          "time_in_view": 8.2
        },
        "element_performance": [
          {
            "element_id": "cta_primary",
            "element_type": "button",
            "interactions": 2100
          }
        ]
      },
      "timeseries": [
        {
          "date": "2026-01-20",
          "impressions": 21000,
          "interactions": 630
        }
      ]
    }
  ]
}

Metric Categories

Core Metrics

• impressions, interactions, interaction_rate, clicks, ctr

Video Metrics

• starts, completions, completion_rate, quartiles, skip_rate, mute_rate, average_watch_time

Engagement Metrics

• expansion_rate, average_time_engaged, cta_clicks, carousel_swipes, game_completions

Attention Metrics

• viewability_rate, time_in_view, attention_score

Element-Level Metrics

• element_performance array with per-element interaction counts

Integration with Sales Agent Reporting

Buyers get complete picture:

1. Call get_media_buy_delivery on sales agent → impressions, spend, placement data
2. Call get_creative_performance on creative agent → engagement, interactions, attention
3. Aggregate using media_buy_id + creative_id as matching keys

Open Questions for Creative WG

1. Where does this task live?

   • Creative Agent spec (buyer calls creative agent directly)
   • Sales Agent spec (sales agent aggregates from creative agent)
   • Separate performance protocol

2. Authentication: How does creative agent know buyer is authorized?

3. Media buy linking: How does creative agent learn media_buy_id?

   • Passed during build_creative/sync_creatives?
   • Buyer provides mapping when requesting performance?

4. Privacy: What data should be shared?

   • Aggregate metrics: YES
   • User-level data: NO
   • Placement-level breakdowns: TBD

5. Standards alignment: Should we adopt VAST events, IAB viewability, OMID?

6. Real-time vs batch: Near-real-time or daily aggregates?

7. Custom metrics: How to handle format-specific or proprietary event tracking?

Use Cases

Buyers: Complete campaign dashboards, creative optimization, variant analysis

Creative Agents: Demonstrate value, support A/B testing, feed learning loops

Publishers: Understand creative quality impact on performance

label:creative

[flaviolivolsi]

I'm building something in the space that would consume this, so I'd like to offer my two cents on some of the open questions:

• Spec location: +1 on Creative Agent - reasoning makes sense to me

• Placement breakdowns: I'd like this included where available, would be useful for optimization. If some inventory sources don't expose it, the response field can just be nullable

• Reporting cadence: for optimization loops, near-real-time (or at least hourly) is significantly more useful than daily. Daily means you catch fatigue after the budget is already burned. If full real-time is too heavy, a lightweight push/event model for threshold alerts (e.g., "CTR dropped 30%") could be a middle ground

• Custom metrics: a generic custom_events field makes sense for format-specific stuff the spec can't anticipate (playable ads, AR, etc.). Keeps the core schema stable