​

Migrating to AdCP v3

​

Why v3?

• Media Channel Taxonomy — 19 planning-oriented channels that reflect how buyers allocate budgets
• Proposals — Structured media plans with conversational refinement and direct execution
• Capability Discovery — Verify seller targeting support (geo systems, etc.) before purchasing
• Governance Protocol — Property lists and content standards for enterprise brand safety
• Sponsored Intelligence — Conversational brand experiences in AI assistants

​

What’s Different in v3

​

Key Themes

1. Media Planning Alignment - The new channel taxonomy reflects how buyers actually plan and allocate budgets across media types, not just how ads render technically.
2. Governance & Brand Safety - The Governance Protocol enables property lists and content standards for enterprise brand safety workflows.
3. Conversational Commerce - The Sponsored Intelligence Protocol defines how AI assistants invoke brand agents for rich conversational experiences.
4. Global Targeting - Named geo systems support international markets without US-centric assumptions.
5. Runtime Discovery - get_adcp_capabilities replaces static agent card extensions with dynamic capability discovery.

​

Migration by Role

• Breaking changes - Update all data structures to v3 format (channels, pricing, geo targeting)
• New implementations - Implement get_adcp_capabilities task for runtime discovery
• New integrations - Support property list filtering in get_products if working with governance agents

• Breaking changes - Update all requests and response handling to v3 format
• New consumption - Use get_adcp_capabilities to discover seller capabilities at runtime
• New integrations - Pass property lists to filter inventory; invoke SI sessions for conversational brand experiences

• Breaking changes - Update schema references from v2 to v3
• No channel changes - Signals Protocol doesn’t use media channels in its core model

• Breaking changes - Support assets array with required boolean for full asset discovery
• No channel changes - Format type field (video, display, audio) is IAB creative classification, not media channels

• New protocol - Implement property lists and content standards tasks
• See Governance Protocol for implementation details

• New protocol - Implement SI session tasks for conversational brand experiences
• See Sponsored Intelligence for implementation details

​

Breaking Changes

​

Media Channel Taxonomy

["display", "video", "audio", "native", "retail"]

[
  "display", "olv", "social", "search", "ctv", "linear_tv",
  "radio", "streaming_audio", "podcast", "dooh", "ooh",
  "print", "cinema", "email", "gaming", "retail_media",
  "influencer", "affiliate", "product_placement"
]

​

Channel Mapping Guide

​

Migration Steps

1. Audit channel usage - Find all places your code reads or writes channel values
2. Map old to new - Use the mapping table above to convert values
3. Update filters - If filtering by channel, update to new values
4. Test thoroughly - Channel mismatches will cause validation errors

​

Pricing Option Field Renames

{
  "pricing_option_id": "cpm_usd_auction",
  "pricing_model": "cpm",
  "currency": "USD",
  "price_guidance": {
    "floor": 10.00,
    "p50": 15.00,
    "p75": 18.00
  }
}

{
  "pricing_option_id": "cpm_usd_auction",
  "pricing_model": "cpm",
  "currency": "USD",
  "floor_price": 10.00,
  "price_guidance": {
    "p50": 15.00,
    "p75": 18.00
  }
}

​

Field Changes

​

Semantic Distinction

• Hard constraints (fixed_price, floor_price) - Publisher-enforced prices that cause bid rejection if violated
• Soft hints (price_guidance.p25, .p50, .p75, .p90) - Historical percentiles to help buyers calibrate bids

​

Migration Steps

1. Rename fixed_rate → fixed_price in all pricing options
2. Move floor from inside price_guidance to top-level floor_price
3. Update readers to look for new field names
4. Test auction bids to verify floor enforcement works correctly

const price = option.fixed_price ?? option.fixed_rate;
const floor = option.floor_price ?? option.price_guidance?.floor;

​

Creative Assignments with Weighting

{
  "creative_ids": ["creative_1", "creative_2"]
}

{
  "creative_assignments": [
    { "creative_id": "creative_1", "weight": 60 },
    { "creative_id": "creative_2", "weight": 40 }
  ]
}

​

What Weighting Enables

• Traffic allocation - Control what percentage of impressions each creative receives
• Placement targeting - Assign specific creatives to specific placements within a product
• A/B testing - Split traffic between creative variants

​

Simple Migration (Equal Weights)

{
  "creative_assignments": [
    { "creative_id": "creative_1" },
    { "creative_id": "creative_2" }
  ]
}

​

Placement Targeting

{
  "creative_assignments": [
    { "creative_id": "hero_video", "placement_ids": ["homepage_hero"] },
    { "creative_id": "sidebar_banner", "placement_ids": ["article_sidebar"] }
  ]
}

​

Geo Targeting with Named Systems

{
  "targeting": {
    "geo_metros": ["501", "602"],
    "geo_postal_codes": ["10001", "90210"]
  }
}

{
  "targeting": {
    "geo_metros": [
      { "system": "nielsen_dma", "code": "501" },
      { "system": "nielsen_dma", "code": "602" }
    ],
    "geo_postal_areas": [
      { "system": "us_zip", "code": "10001" },
      { "system": "us_zip", "code": "90210" }
    ]
  }
}

​

Why Named Systems?

​

Migration Steps

1. Identify geo targeting - Find all uses of geo_metros and geo_postal_codes
2. Add system specification - Wrap values in { "system": "...", "code": "..." }
3. Rename field - geo_postal_codes → geo_postal_areas
4. Verify systems - Use get_adcp_capabilities to check what systems sellers support

​

Unified Asset Discovery

{
  "assets_required": ["main_image", "headline"]
}

{
  "assets": [
    { "asset_id": "main_image", "required": true },
    { "asset_id": "headline", "required": true },
    { "asset_id": "impression_tracker", "required": false }
  ]
}

​

What This Enables

• Full asset discovery - See ALL assets a format supports, not just required ones
• Optional asset usage - Use optional assets like trackers when available
• Better AI integration - Agents can see the complete asset interface

​

New Features

​

get_adcp_capabilities Task

// Request
{
  "task": "get_adcp_capabilities"
}

// Response
{
  "adcp": {
    "major_versions": [3]
  },
  "supported_protocols": ["media_buy", "signals", "governance"],
  "extensions_supported": ["scope3", "garm"],
  "media_buy": {
    "features": {
      "inline_creative_management": true,
      "property_list_filtering": true
    },
    "portfolio": {
      "publisher_domains": ["publisher.com"],
      "channels": ["display", "ctv"],
      "countries": ["US", "CA"]
    },
    "execution": {
      "targeting": {
        "geo_metros": [{ "system": "nielsen_dma" }],
        "geo_postal_areas": [{ "system": "us_zip" }]
      }
    }
  },
  "governance": {
    "property_features": [
      { "feature_id": "mfa_score", "type": "quantitative", "range": { "min": 0, "max": 100 } },
      { "feature_id": "garm_category", "type": "categorical", "categories": ["adult", "arms", "crime"] }
    ]
  }
}

​

Benefits Over Agent Card Extensions

​

Migration Steps

1. Remove agent card extension - Delete adcp-extension.json from your agent card
2. Implement get_adcp_capabilities - Add the task to your agent
3. Update buyers - Call get_adcp_capabilities instead of parsing agent cards

​

Governance Protocol

​

Property Lists

// Create a property list
{
  "task": "create_property_list",
  "name": "Premium News Sites",
  "filters": {
    "mfa_score": { "max": 30 },
    "garm_categories": { "exclude": ["adult", "arms"] }
  }
}

• create_property_list - Create a new list
• get_property_list - Retrieve with resolved properties
• update_property_list - Modify filters
• delete_property_list - Remove a list
• list_property_lists - Enumerate available lists

​

Content Standards

// Create content standards
{
  "task": "create_content_standards",
  "name": "Family Brand Standards",
  "policies": [
    { "category": "adult", "action": "block" },
    { "category": "alcohol", "action": "allow_with_warning" }
  ]
}

• create_content_standards - Define policies
• get_content_standards - Retrieve configuration
• update_content_standards - Modify policies
• calibrate_content - Collaborative dialogue for alignment
• validate_content_delivery - Batch validate delivery records

​

Property List Filtering in get_products

{
  "task": "get_products",
  "brief": "Premium video inventory for auto brand",
  "property_list": {
    "governance_agent_url": "https://governance.example.com",
    "list_id": "premium_news_sites"
  }
}

​

Sponsored Intelligence Protocol

​

The Flow

1. User expresses interest → Host identifies opportunity
2. Consent prompt → User decides whether to share identity
3. Session initiation → Host invokes brand agent with context
4. Conversational engagement → Brand interacts via text, voice, or UI components
5. Session termination → Handoff for transaction (via ACP) or completion

​

Key Tasks

• si_check_availability - Check if brand agent is available
• si_initiate_session - Start a brand conversation
• si_send_message - Exchange messages during session
• si_terminate_session - End session with optional transaction handoff

​

Example Session

// Initiate session
{
  "task": "si_initiate_session",
  "context": "User wants to fly to Boston next Tuesday",
  "identity": {
    "consent_granted": true,
    "user": { "email": "[email protected]", "name": "Jane Smith" }
  }
}

// Response with product card
{
  "session_id": "sess_abc123",
  "response": {
    "message": "I found DL632 at 6:15 AM. As a Gold member, you qualify for a free upgrade!",
    "ui_elements": [
      {
        "type": "product_card",
        "data": {
          "title": "DL632 to Boston",
          "price": "$199",
          "badge": "Free Premium Economy Upgrade"
        }
      }
    ]
  }
}

​

Removed in v3

​

Migration Checklist

​

All Implementations

• Update channel enum values to new taxonomy
• Rename fixed_rate → fixed_price in pricing options
• Move price_guidance.floor → floor_price (top-level)
• Replace creative_ids with creative_assignments
• Add system specification to metro/postal targeting
• Rename geo_postal_codes → geo_postal_areas
• Update format parsing to use assets array
• Validate all requests/responses against v3 schemas

​

Seller Agents

• Implement get_adcp_capabilities task
• Remove adcp-extension.json from agent card
• Support property list filtering in get_products if integrating with governance agents

​

Buyer Agents & Orchestrators

• Update to call get_adcp_capabilities for runtime discovery
• Pass property lists to filter inventory when working with governance agents
• Invoke SI sessions when connecting users with brand agents

​

Signals Agents

• Update schema references from v2 to v3
• Ensure get_adcp_capabilities returns major_versions: [3]

​

Creative Agents

• Support assets array with required boolean (replaces assets_required)
• Update schema references from v2 to v3

​

Governance Agents (new in v3)

• Implement property list tasks (create_property_list, get_property_list, etc.)
• Implement content standards tasks (create_content_standards, calibrate_content, etc.)
• Implement get_adcp_capabilities with governance in supported_protocols

​

Sponsored Intelligence Agents (new in v3)

• Implement SI session tasks (si_initiate_session, si_send_message, si_terminate_session)
• Implement get_adcp_capabilities with sponsored_intelligence in supported_protocols

​

Getting Help

• Community: Slack
• Issues: GitHub Issues
• Support: [email protected]