Contextual Weaving Format

Custom format specification for AI-native contextual weaving using the AdCP framework. This format enables publishers' LLMs to weave brand context into conversational responses and search results.

Overview

⚠️ Important: This is a custom format example demonstrating how to use the AdCP framework to create specialized formats for AI-native advertising. It is not part of the core ADCP standard. Publishers can create their own custom formats following this pattern.

For AI Search Use Case: See AI Search Monetization (LLM Weaving) for the optimized format designed specifically for AI search results with expandable sponsored messages.

Relationship to AdCP

What ADCP Provides:

✅ Format definition structure (format_id, assets_required, weaving_schema)
✅ Creative manifest structure (format_id, assets, promoted_offering)
✅ Asset types (text, url, etc.)
✅ Universal macros for tracking

What This Format Adds:

🔧 Contextual weaving format definition
🔧 Weaving hint assets (must_include_terms, avoid_terms)
🔧 Weaving schema constraints for LLM behavior
🔧 Integration guidelines for publisher LLMs

For the base ADCP OpenRTB extension, see AdCP Extension API.

Format Definition

Format Identifier

{
  "format_id": {
    "agent_url": "https://youragent.com",
    "id": "contextual_snippet_with_hints"
  }
}

Complete Format Specification

{
  "format_id": {
    "agent_url": "https://youragent.com",
    "id": "contextual_snippet_with_hints"
  },
  "name": "Contextual Snippet with Weaving Hints",
  "type": "contextual_weaving",
  "description": "AI-native format for weaving brand context into LLM responses with explicit inclusion/exclusion hints",
  "weaving_schema": {
    "required_fields": ["brand_context", "key_messages"],
    "optional_fields": ["call_to_action", "must_include_terms", "avoid_terms"],
    "constraints": {
      "max_context_length": 500,
      "max_output_length": 150,
      "max_key_messages": 5,
      "max_must_include_terms": 5,
      "max_avoid_terms": 10
    },
    "defaults": {
      "integration_style": "natural_mention",
      "tone": "helpful_recommendation"
    },
    "allowed_integration_styles": [
      "natural_mention",
      "recommendation",
      "comparison"
    ],
    "allowed_tones": ["helpful_recommendation", "informative", "enthusiastic"]
  },
  "assets_required": [
    {
      "asset_id": "brand_context",
      "asset_type": "text",
      "asset_role": "brand_context",
      "required": true,
      "requirements": {
        "max_length": 500,
        "description": "Core brand information and value proposition"
      }
    },
    {
      "asset_id": "key_messages",
      "asset_type": "text",
      "asset_role": "key_messages",
      "required": true,
      "requirements": {
        "format": "pipe_separated",
        "max_items": 5,
        "description": "Key selling points or features to emphasize"
      }
    },
    {
      "asset_id": "call_to_action",
      "asset_type": "text",
      "asset_role": "call_to_action",
      "required": false,
      "requirements": {
        "max_length": 50,
        "description": "Action phrase for user engagement"
      }
    },
    {
      "asset_id": "must_include_terms",
      "asset_type": "text",
      "asset_role": "weaving_hints",
      "required": false,
      "requirements": {
        "format": "pipe_separated",
        "max_items": 5,
        "description": "Terms that should be included in the woven response"
      }
    },
    {
      "asset_id": "avoid_terms",
      "asset_type": "text",
      "asset_role": "weaving_constraints",
      "required": false,
      "requirements": {
        "format": "pipe_separated",
        "max_items": 10,
        "description": "Terms that should be avoided in the woven response"
      }
    },
    {
      "asset_id": "clickthrough_url",
      "asset_type": "url",
      "asset_role": "clickthrough",
      "required": true,
      "requirements": {
        "description": "Landing page URL for user clicks"
      }
    },
    {
      "asset_id": "impression_tracker",
      "asset_type": "url",
      "asset_role": "impression_tracker",
      "required": true,
      "requirements": {
        "description": "Tracking URL fired when brand context is woven into response"
      }
    }
  ],
  "supported_macros": ["MEDIA_BUY_ID", "CREATIVE_ID", "CACHEBUSTER"]
}

Asset Specifications

brand_context

Purpose: Core brand information that provides context for the LLM.

Format: Plain text, max 500 characters

Example:

Award-winning family golf resort with supervised kids' programs, spa facilities, and a championship 18-hole course designed by Jack Nicklaus

key_messages

Purpose: Specific selling points or features to emphasize in the woven response.

Format: Pipe-separated list, max 5 items

Example:

Family-friendly with supervised kids' activities|Championship course designed by Jack Nicklaus|All-inclusive packages starting at $299/night

call_to_action

Purpose: Action phrase to encourage user engagement.

Format: Plain text, max 50 characters

Example:

Book your family golf getaway

must_include_terms

Purpose: Terms that should be naturally incorporated into the woven response.

Format: Pipe-separated list, max 5 items

Example:

family-friendly|championship course|golf resort

Usage Guidelines:

Terms should be incorporated naturally, not forced
LLM should use semantic variations (e.g., "family-friendly" → "great for families")
If terms don't fit the context, they may be omitted

avoid_terms

Purpose: Terms that should not appear in the woven response.

Format: Pipe-separated list, max 10 items

Example:

sponsored|advertisement|paid promotion|ad|commercial

Usage Guidelines:

Avoid exact matches and close variations
Helps maintain natural, non-promotional tone
Publisher LLM should respect these constraints

Creative Manifest Example

Complete Manifest

{
  "format_id": {
    "agent_url": "https://youragent.com",
    "id": "contextual_snippet_with_hints"
  },
  "promoted_offering": "Golf Resort Paradise",
  "assets": {
    "brand_context": {
      "content": "Award-winning family golf resort with supervised kids' programs, spa facilities, and a championship 18-hole course designed by Jack Nicklaus"
    },
    "key_messages": {
      "content": "Family-friendly with supervised kids' activities|Championship course designed by Jack Nicklaus|All-inclusive packages starting at $299/night"
    },
    "call_to_action": {
      "content": "Book your family golf getaway"
    },
    "must_include_terms": {
      "content": "family-friendly|championship course|golf resort"
    },
    "avoid_terms": {
      "content": "sponsored|advertisement|paid promotion"
    },
    "clickthrough_url": {
      "url": "https://golfresortparadise.com/book?campaign={MEDIA_BUY_ID}"
    },
    "impression_tracker": {
      "url": "https://track.brand.com/weave?buy={MEDIA_BUY_ID}&cb={CACHEBUSTER}"
    }
  }
}

OpenRTB Integration

Bid Request

Publishers declare support for this format in Imp.ext.aura.adcpFormats:

{
  "imp": [
    {
      "id": "imp-1",
      "ext": {
        "aura": {
          "adcpFormats": [
            {
              "agent_url": "https://youragent.com",
              "id": "contextual_snippet_with_hints"
            }
          ]
        }
      }
    }
  ]
}

Bid Response

Bidders provide the creative manifest in Bid.ext.aura.adcpFormat:

{
  "bid": {
    "id": "bid-001",
    "price": 3.0,
    "adm": "Golf Resort Paradise - Award-winning family golf resort. Book at https://golfresortparadise.com/book",
    "burl": "https://bidder.com/win?id=bid-001&price=${AUCTION_PRICE}",
    "nurl": "https://bidder.com/imp?id=bid-001",
    "ext": {
      "aura": {
        "adcpFormat": {
          "formatId": {
            "agent_url": "https://youragent.com",
            "id": "contextual_snippet_with_hints"
          },
          "creativeManifest": {
            "format_id": {
              "agent_url": "https://youragent.com",
              "id": "contextual_snippet_with_hints"
            },
            "promoted_offering": "Golf Resort Paradise",
            "assets": {
              "brand_context": {
                "content": "Award-winning family golf resort with supervised kids' programs, spa facilities, and championship 18-hole course designed by Jack Nicklaus"
              },
              "key_messages": {
                "content": "Family-friendly with supervised kids' activities|Championship course designed by Jack Nicklaus|All-inclusive packages starting at $299/night"
              },
              "call_to_action": {
                "content": "Book your family golf getaway"
              },
              "must_include_terms": {
                "content": "family-friendly|championship course|golf resort"
              },
              "avoid_terms": {
                "content": "sponsored|advertisement|paid promotion"
              },
              "clickthrough_url": {
                "url": "https://golfresortparadise.com/book?campaign={MEDIA_BUY_ID}"
              },
              "impression_tracker": {
                "url": "https://track.brand.com/weave?buy={MEDIA_BUY_ID}&cb={CACHEBUSTER}"
              }
            }
          }
        }
      }
    }
  }
}

Note: The adm field provides a simple text fallback for non-AdCP publishers.

Publisher Implementation

Weaving Flow

Implementation Steps

1. Receive Bid Response with format ID and creative manifest 2. Query Format Definition from https://youragent.com/formats/contextual_snippet_with_hints 3. Validate Manifest against format's assets_required and weaving_schema 4. Extract Assets:

brand_context - Core brand information
key_messages - Selling points to emphasize
must_include_terms - Terms to incorporate
avoid_terms - Terms to exclude 5. Generate Response using LLM with:
User query context
Brand context and key messages
Weaving hints (must_include/avoid)
Format constraints (max length, tone, style) 6. Fire Impression Tracker when brand context is woven 7. Handle Clicks by firing click tracker and redirecting to clickthrough_url

LLM Prompt Example

You are a helpful assistant answering user questions about golf resorts.

User Query: "What are some good family-friendly golf resorts?"

Brand Context: Award-winning family golf resort with supervised kids' programs, spa facilities, and a championship 18-hole course designed by Jack Nicklaus

Key Messages:
- Family-friendly with supervised kids' activities
- Championship course designed by Jack Nicklaus
- All-inclusive packages starting at $299/night

Instructions:
- Incorporate these terms naturally: family-friendly, championship course, golf resort
- Avoid these terms: sponsored, advertisement, paid promotion
- Maximum response length: 150 characters
- Tone: helpful_recommendation
- Integration style: natural_mention

Generate a helpful response that naturally mentions Golf Resort Paradise among other options.

Example Output

Here are some excellent family-friendly golf resorts to consider:

Golf Resort Paradise stands out with its supervised kids' programs that keep
children entertained while parents enjoy the championship Jack Nicklaus-designed
course. Their all-inclusive packages start at $299/night and include spa access.

Other options include [other resorts]...

Publisher Weaving Behavior

Weaving Approaches

Publishers may implement different weaving strategies:

Always Weave: LLM always incorporates brand context when provided for this format

Conditional Weaving: LLM weaves based on:

User preferences or settings
Quality/relevance thresholds
Conversation flow appropriateness
Platform-specific policies

Selective Format Support: Publishers choose which weaving formats to support by including/excluding them from adcpFormats[]

Quality Guidelines

Do Weave When:

Brand context is highly relevant to user query
Weaving can be done naturally without disrupting response quality
User has not opted out of contextual advertising

Don't Weave When:

Brand context is not relevant to user query
Weaving would compromise response quality
User has opted out or privacy settings prohibit
Query is sensitive (medical, legal, financial advice)

Tracking

Impression Tracking

Fire the impression_tracker URL when:

Brand context is successfully woven into LLM response
Response is delivered to user
Weaving meets quality thresholds

Example:

https://track.brand.com/weave?buy=mb_spring_2025&cb=87654321

Click Tracking

Fire click tracker and redirect when:

User clicks on brand mention or CTA
User explicitly requests more information about the brand

Validation

Manifest Validation

Publishers MUST validate manifests against the format definition:

1. Required Assets Present: brand_context, key_messages, clickthrough_url, impression_tracker 2. Asset Constraints Met:

brand_context ≤ 500 characters
key_messages ≤ 5 items
must_include_terms ≤ 5 items (if provided)
avoid_terms ≤ 10 items (if provided) 3. Format Compliance: Pipe-separated lists properly formatted 4. URL Validity: Tracking URLs and clickthrough URLs are valid

Error Handling

Invalid Manifest: Reject bid or fall back to adm field

Weaving Failure: Use adm field as fallback

Tracking Failure: Log error, continue serving creative

Best Practices

For Bidders

1. Provide Quality Context: Brand context should be informative and relevant 2. Use Specific Key Messages: Focus on unique selling points 3. Choose Hints Carefully: must_include_terms should be naturally incorporable 4. Avoid Over-Constraining: Too many constraints reduce weaving quality 5. Test Fallback: Ensure adm field provides acceptable fallback

For Publishers

1. Respect Hints: Honor must_include_terms and avoid_terms when possible 2. Maintain Quality: Don't sacrifice response quality for weaving 3. Be Transparent: Consider disclosing contextual advertising to users 4. Monitor Performance: Track weaving success rates and user engagement 5. Implement Fallbacks: Always have fallback behavior for weaving failures

Next Steps

Format Support - Declaring format support
Creative Manifests - Manifest structure
Tracking - Tracking implementation
AI Search Monetization (LLM Weaving) - AI search use case with LLM text weaving
Homepage Tile Agent - Browser homepage tiles with MCP-powered chat

Overview​

Relationship to AdCP​

Format Definition​

Format Identifier​

Complete Format Specification​

Asset Specifications​

brand_context​

key_messages​

call_to_action​

must_include_terms​

avoid_terms​

Creative Manifest Example​

Complete Manifest​

OpenRTB Integration​

Bid Request​

Bid Response​

Publisher Implementation​

Weaving Flow​

Implementation Steps​

LLM Prompt Example​

Example Output​

Publisher Weaving Behavior​

Weaving Approaches​

Quality Guidelines​

Tracking​

Impression Tracking​

Click Tracking​

Validation​

Manifest Validation​

Error Handling​

Best Practices​

For Bidders​

For Publishers​

Next Steps​

Overview

Relationship to AdCP

Format Definition

Format Identifier

Complete Format Specification

Asset Specifications

brand_context

key_messages

call_to_action

must_include_terms

avoid_terms

Creative Manifest Example

Complete Manifest

OpenRTB Integration

Bid Request

Bid Response

Publisher Implementation

Weaving Flow

Implementation Steps

LLM Prompt Example

Example Output

Publisher Weaving Behavior

Weaving Approaches

Quality Guidelines

Tracking

Impression Tracking

Click Tracking

Validation

Manifest Validation

Error Handling

Best Practices

For Bidders

For Publishers

Next Steps