Marketing Campaign Planner

An AI-powered multi-agent system that guides users through end-to-end marketing campaign planning via an interactive, phased conversation.

Framework: CrewAI · Category: Marketing & Strategy · Language: Python

Overview

This template implements a full-stack marketing campaign planning agent built with CrewAI Flows and a React frontend. The system walks users through a structured 5-phase workflow — from market discovery to final content delivery — using specialized AI crews that collaborate to produce brand creatives, channel strategies, and integrated campaign plans. Human-in-the-loop feedback is built into every phase, allowing users to iterate on outputs before advancing.

• Multi-phase orchestration: discovery, planning (brand + channel in parallel), integration, content generation, and finalization
• Human-in-the-loop at every stage via CrewAI's @human_feedback decorator with approve, redo, and rollback actions
• Real-time SSE streaming of agent reasoning and structured card outputs
• Session persistence with sticky routing — conversations survive instance restarts via store-backed recovery
• Branch operations (redo brand, redo channel, rollback) handled outside the main flow without restarting

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | AI_GATEWAY_API_KEY | Yes | Model gateway API key. Use your Makers Models API Key, or any OpenAI-compatible provider key. | | AI_GATEWAY_BASE_URL | Yes | Gateway base URL. For Makers Models, use https://ai-gateway.edgeone.link/v1. | | AI_GATEWAY_MODEL | No | Model ID. Defaults to @makers/deepseek-v4-flash. |

This template follows the OpenAI-compatible standard — point these at Makers Models or any compatible provider.

How to get AI_GATEWAY_API_KEY

1. Open the Makers Console
2. Sign in and enable Makers
3. Go to Makers → Models → API Key and create a key
4. Copy it into AI_GATEWAY_API_KEY

The built-in model is free with rate limits — suitable for development and evaluation. For production workloads, bind your own provider key (BYOK).

Local Development

Prerequisites

• Node.js >= 18
• Python >= 3.11

Commands

# Install frontend dependencies
npm install

# Install Python agent dependencies
pip install -r requirements.txt

# Copy environment variables
cp .env.example .env
# Fill in AI_GATEWAY_API_KEY and AI_GATEWAY_BASE_URL

# Start local development (frontend + agent + cloud functions)
edgeone makers dev

The dev server runs the Vite frontend, the CrewAI agent (agents/stream.py), and cloud functions simultaneously. Visit http://localhost:8088 for the app and http://localhost:8080/agent-metrics for the observability panel.

Project Structure

.
├── agents/                          # CrewAI agent runtime (Python)
│   ├── stream.py                    # POST /stream — main SSE entry point
│   ├── _lib/
│   │   ├── flow.py                  # MarketingCampaignFlow (5-step orchestration)
│   │   ├── persistence.py           # In-process FlowPersistence + store sync
│   │   ├── feedback_provider.py     # Human feedback provider bridge
│   │   ├── llm.py                   # LLM initialization helper
│   │   └── logger.py               # Structured logger
│   └── _crews/
│       ├── agents.yaml              # Shared agent definitions
│       ├── discovery_crew/          # Market analyst — audience & insights Q&A
│       ├── brand_creative_crew/     # Brand strategist — visual & messaging identity
│       ├── channel_planning_crew/   # Channel planner — media mix & budget
│       ├── integration_crew/        # Integration strategist — unified plan
│       └── content_crew/            # Copywriter — final deliverable content
├── cloud-functions/                 # Auxiliary HTTP endpoints (Python)
│   ├── history.py                   # POST /history — load conversation history
│   ├── delete.py                    # POST /delete — delete a conversation
│   └── requirements.txt
├── src/                             # React + TypeScript frontend
│   ├── App.tsx                      # Main app + state management
│   ├── components/
│   │   ├── cards/                   # Structured output cards (brand, channel, etc.)
│   │   ├── views/                   # Phase-specific views (discovery, planning, etc.)
│   │   ├── Header.tsx               # Navigation + locale toggle
│   │   ├── PhaseProgress.tsx        # 5-phase progress indicator
│   │   ├── InputBar.tsx             # Chat input with suggestions
│   │   ├── StartPanel.tsx           # Campaign brief entry
│   │   └── HistoryPanel.tsx         # Session history sidebar
│   ├── hooks/
│   │   ├── useSSE.ts               # SSE stream consumer
│   │   └── useHistory.ts           # Conversation history hook
│   ├── i18n.ts                      # Internationalization (zh/en)
│   ├── types/index.ts               # TypeScript type definitions
│   └── utils/export.ts              # Markdown export utility
├── edgeone.json                     # EdgeOne Makers configuration
├── package.json                     # Frontend dependencies & scripts
├── requirements.txt                 # Python dependencies (crewai[litellm,tools])
└── vite.config.ts                   # Vite + React + TailwindCSS config

How It Works

Session Mode & Sticky Routing

Each conversation is identified by a conversation_id. The frontend sends this via the Makers-Conversation-Id HTTP header on every request. EdgeOne's agent runtime uses sticky routing to pin a conversation to a specific instance, ensuring in-memory Flow state (pause/resume contexts) remains accessible across requests. On cold starts or instance migration, pending state is recovered from the persistent store via load_pending_from_store().

Workflow Phases

The MarketingCampaignFlow class (in agents/_lib/flow.py) orchestrates a 5-step sequential workflow using CrewAI's @start, @listen, and @router decorators:

Discovery → Planning → Integration → Content → Finalize

1. Discovery — The DiscoveryCrew (market analyst) asks iterative questions (up to 4 rounds) to gather campaign goals, target audience, and market context. Each round pauses via @human_feedback and resumes with user input. When the analyst detects sufficient information, it emits [READY] to advance.

2. Planning — Two crews:

   • BrandCreativeCrew — generates brand identity, visual direction, and messaging framework
   • ChannelPlanningCrew — produces media channel mix, budget allocation, and timing strategy

   Both outputs are presented as structured cards. Users confirm each independently.

3. Integration — The IntegrationCrew merges brand and channel outputs into a unified, coherent campaign strategy document.

4. Content — The ContentCrew generates final copywriting deliverables (headlines, body copy, CTAs, social variants) based on the integrated strategy.

5. Finalize — Summarizes the complete campaign plan, resolves any remaining conflicts, and marks the flow as finished. Users can export the result as Markdown.

Human-in-the-Loop

Every phase boundary uses CrewAI's @human_feedback decorator with a custom FeedbackProvider. The flow pauses after each crew output, streams results to the frontend as structured card events (card_update), and waits for user action:

• Confirm — accept and advance to the next phase
• Redo — regenerate the current phase output (with comparison view showing old vs. new)
• Rollback — return to a previous phase without losing downstream data

Branch operations (redo_brand, redo_channel, rollback) are intercepted by the handler layer in stream.py and invoke crews directly, bypassing the main flow router.

Tools & Crews

| Crew | Agent Role | Purpose | |------|-----------|---------| | DiscoveryCrew | Market Analyst | Structured Q&A to extract campaign requirements | | BrandCreativeCrew | Creative Director | Brand positioning, visual identity, messaging | | ChannelPlanningCrew | Channel Planner | Media mix, budget, scheduling | | IntegrationCrew | Chief Strategist | Synthesize all inputs into unified strategy | | ContentCrew | Copywriter | Final deliverable content production |

Key Routes

| Method | Path | Handler | Description | |--------|------|---------|-------------| | POST | /stream | agents/stream.py | Main agent entry — SSE streaming, kickoff/resume | | POST | /history | cloud-functions/history.py | Load conversation messages and phase state | | POST | /delete | cloud-functions/delete.py | Delete a conversation from the store |

Conversation ID Passing

1. The frontend sends the Makers-Conversation-Id header with every request.
2. On first contact (no ID), the runtime generates a new conversation_id and returns it in the SSE stream as a conversation_id event.
3. Subsequent requests include this ID to resume the same flow instance.
4. Sticky routing ensures the request reaches the same runtime instance holding the in-memory flow state.
5. If the instance has restarted, persistence.py recovers the pending HumanFeedbackPending context from context.store.

Runtime Configuration (edgeone.json)

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "agents": {
    "framework": "crewai",
    "dir": "agents",
  }
}

| Field | Value | Purpose | |-------|-------|---------| | agents.framework | crewai | Tells the runtime to load the CrewAI agent handler | | agents.dir | agents | Directory containing stream.py and crew definitions | | buildCommand | npm run build | Vite production build for the frontend | | outputDirectory | dist | Static assets served alongside the agent |

Resources

• EdgeOne Makers Agents Documentation
• Makers Quick Start
• Makers Models

License

MIT