Creative Ad Agent

An AI-powered creative advertising agent that generates conversion-focused ads using a hook-first methodology. Built with the Claude Agent SDK, it analyzes brand websites, extracts factual data, and creates 6 diverse ad concepts with AI-generated images.

Features

• Hook-First Ad Generation - Hooks are mined from research data using proven formulas (hooks = 80% of ad performance)
• Research-Driven - Extracts real data from brand websites: offers, value props, proof points, testimonials
• 6 Diverse Concepts - Each concept uses a different emotional trigger (social proof, urgency, curiosity, etc.)
• AI Image Generation - Creates visuals via fal.ai Nano Banana Pro
• Session Management - Stateful conversations with forking for A/B testing
• Dual Deployment - Local development server + Cloudflare Workers production

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR (Main Agent)                 │
│                                                              │
│   ┌─────────────┐   ┌──────────────────┐   ┌─────────────┐  │
│   │  research   │ → │ hook-methodology │ → │  art-style  │  │
│   │   (Agent)   │   │     (Skill)      │   │   (Skill)   │  │
│   └─────────────┘   └──────────────────┘   └─────────────┘  │
│          ↓                   ↓                    ↓          │
│   research.md          hook-bank.md         prompts.json    │
│                                                   ↓          │
│                                          ┌─────────────┐    │
│                                          │ nano-banana │    │
│                                          │  (MCP/fal)  │    │
│                                          └─────────────┘    │
│                                                   ↓          │
│                                            6 PNG images      │
└─────────────────────────────────────────────────────────────┘

Workflow

1. Parse - Extract URL and brand name from request
2. Research - Agent fetches homepage, extracts offers/value props/proof points
3. Hooks - Skill generates 10+ hooks, selects 6 with diversity matrix
4. Art - Skill creates visual prompts for each hook
5. Images - MCP generates images via fal.ai
6. Complete - Returns 6 ad concepts with images

Quick Start

Prerequisites

• Node.js v20+
• Anthropic API Key
• fal.ai API Key

Installation

# Clone the repository
git clone https://github.com/DV0x/creative-ad-agent.git
cd creative-ad-agent

# Install server dependencies
cd server && npm install

# Create environment file
cp .env.example .env
# Edit .env with your API keys

Running Locally

# Start the server
cd server
npm run dev

# Server runs at http://localhost:3001

Generate Ads

curl -X POST http://localhost:3001/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create ads for https://example.com"}'

Project Structure

creative-ad-agent/
├── agent/                      # Agent ecosystem
│   └── .claude/
│       ├── agents/
│       │   └── research.md     # Data extraction agent
│       └── skills/
│           ├── hook-methodology/
│           │   ├── SKILL.md    # Hook generation skill
│           │   └── formulas.md # Hook formula reference
│           └── art-style/
│               ├── SKILL.md    # Visual prompt skill
│               └── workflows/  # Style-specific workflows
│
├── server/                     # Local Express server
│   ├── sdk-server.ts          # Main server
│   └── lib/
│       ├── ai-client.ts       # Claude SDK wrapper
│       ├── nano-banana-mcp.ts # fal.ai MCP integration
│       ├── session-manager.ts # Session handling
│       └── orchestrator-prompt.ts
│
├── client/                     # React frontend
│   └── src/
│       ├── App.tsx
│       ├── hooks/useGenerate.ts
│       └── components/
│
├── creative-agent-cf/          # Cloudflare Workers deployment
│   ├── src/                   # Worker code
│   └── sandbox/               # Container code
│
└── docs/                       # Documentation

API Endpoints

Hook Methodology

The system uses a research-first approach where every hook is traceable to specific data:

...