Skip to main content

​
Implementing Creative Agents

This guide explains how to implement a creative agent that defines and manages creative formats.

​
What is a Creative Agent?

A creative agent is a service that:
  • Defines formats - Specifies what assets are required and how they should be structured
  • Validates manifests - Ensures creative manifests meet format requirements
  • Generates previews - Shows how creatives will render
  • Builds creatives (optional) - Generates manifests from natural language briefs
Creative agents are independent of sales agents. A third-party creative agency, ad tech platform, or publisher can implement a creative agent to serve multiple buyers and publishers.

​
Core Requirements

​
1. Format ID Namespacing

Every format you define must use namespaced format IDs to prevent conflicts. Pattern: {domain}:{format_id} Examples:
  • creative.adcontextprotocol.org:display_300x250
  • youragency.com:video_story_15s
  • brandstudio.com:interactive_carousel
Rules:
  • Domain must match your agent’s domain
  • Format ID portion should be descriptive and unique within your namespace
  • Use lowercase with underscores for consistency

​
2. Format Validation

When formats reference your agent_url, you are the authority for:
  • Format specifications
  • Asset validation rules
  • Technical requirements
  • Preview generation
Format definition example: 
{
  "format_id": {
    "agent_url": "https://youragency.com",
    "id": "story_sequence_5frame"
  },
  "name": "5-Frame Story Sequence",
  "type": "display",
  "min_frames": 5,
  "max_frames": 5,
  "frame_schema": {
    "assets": [
      {
        "asset_type": "image",
        "asset_role": "frame_image",
        "required": true,
        "requirements": {
          "width": 1080,
          "height": 1920,
          "file_types": ["jpg", "png", "webp"],
          "max_file_size_kb": 500
        }
      },
      {
        "asset_type": "text",
        "asset_role": "caption",
        "required": false,
        "requirements": {
          "max_length": 100
        }
      }
    ]
  },
  "global_assets": [
    {
      "asset_type": "image",
      "asset_role": "brand_logo",
      "required": true,
      "requirements": {
        "width": 200,
        "height": 200,
        "transparency_required": true
      }
    }
  ]
}

​
Required Tasks

Creative agents must implement these two tasks:

​
list_creative_formats

Return all formats your agent defines. This is how buyers discover what creative formats you support. Key responsibilities:
  • Return complete format definitions with all assets_required
  • Include your agent_url in each format
  • Use proper namespacing for format_id values
See list_creative_formats task reference for complete API specification.

​
preview_creative

Generate a visual preview showing how a creative manifest will render in your format. Key responsibilities:
  • Validate manifest against format requirements
  • Return validation errors if manifest is invalid
  • Generate visual representation (URL, image, or HTML)
  • Preview should be accessible for at least 24 hours
See preview_creative task reference for complete API specification.

​
Optional Tasks

​
build_creative

Generate a creative manifest from a natural language brief. This enables AI-powered creative generation workflows. Key responsibilities:
  • Parse natural language brief
  • Generate or source appropriate assets
  • Return valid manifest for your format
  • Optionally return preview URL
See build_creative task reference for complete API specification.

​
Validation Best Practices

​
Manifest Validation

When validating manifests:
  1. Check format_id - Ensure it references your agent
  2. Validate required assets - All required assets must be present
  3. Check asset types - Assets must match specified types
  4. Validate requirements - Dimensions, file types, sizes, etc.
  5. URL accessibility - Verify asset URLs are accessible (optional but recommended)
Example validation errors: 
{
  "status": "error",
  "error": "validation_failed",
  "validation_errors": [
    {
      "asset_id": "frame_1_image",
      "error": "missing_required_asset",
      "message": "Required asset 'frame_1_image' is missing"
    },
    {
      "asset_id": "brand_logo",
      "error": "invalid_dimensions",
      "message": "Logo must be 200x200px, got 150x150px"
    }
  ]
}

​
Format Evolution

When updating format definitions:
  • Additive changes (new optional assets) are safe
  • Breaking changes (removing assets, changing requirements) require new format_id
  • Consider versioning: youragency.com:format_name_v2
  • Maintain backward compatibility when possible

​
Deployment Checklist

Before launching your creative agent:
  • MCP and/or A2A endpoints are accessible
  • All format_ids use proper namespacing (domain:id)
  • Domain in format_id matches your agent_url domain
  • list_creative_formats returns all your formats
  • preview_creative validates manifests and generates previews
  • Format definitions include complete asset requirements
  • Documentation available for your custom formats

​
Integration Patterns

​
Pattern 1: Creative Agency

You’re a creative agency building custom formats for brands: 
{
  "format_id": {
    "agent_url": "https://brandstudio.com",
    "id": "hero_video_package"
  },
  "name": "Hero Video Package",
  "type": "video",
  "description": "Premium video creative with multiple aspect ratios",
  "assets_required": [
    {"asset_role": "hero_video_16x9", ...},
    {"asset_role": "hero_video_9x16", ...},
    {"asset_role": "hero_video_1x1", ...}
  ]
}

​
Pattern 2: Platform-Specific Formats

You’re a platform defining specialized formats: 
{
  "format_id": {
    "agent_url": "https://platform.com",
    "id": "interactive_quiz"
  },
  "name": "Interactive Quiz Ad",
  "type": "rich_media",
  "description": "Engagement-driven quiz format",
  "assets_required": [
    {"asset_role": "question_1", "asset_type": "text", ...},
    {"asset_role": "answer_1a", "asset_type": "text", ...},
    // ... quiz structure
  ]
}

​
Pattern 3: Format Extension Service

You provide enhanced versions of standard formats: 
{
  "format_id": {
    "agent_url": "https://enhanced.com",
    "id": "video_30s_optimized"
  },
  "name": "Optimized 30s Video",
  "type": "video",
  "extends": "creative.adcontextprotocol.org:video_30s",
  "description": "Standard 30s video with automatic optimization",
  "assets_required": [
    // Same requirements as standard format
  ],
  "enhancements": {
    "auto_transcode": true,
    "quality_optimization": true,
    "format_variants": ["mp4", "webm", "hls"]
  }
}