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"]
  }
}

Related Documentation

• Creative Formats - Understanding format structure
• Creative Manifests - How manifests work
• Asset Types - Asset specifications
• list_creative_formats Task - API reference
• preview_creative Task - API reference
• build_creative Task - API reference