Marketing Crew Wiki

Welcome to the comprehensive wiki for the Marketing Crew project! This document serves as your complete guide to understanding, configuring, and extending the AI-powered marketing automation system.

📚 Table of Contents

1. Getting Started
2. Architecture Deep Dive
3. Agent System
4. Task Workflow
5. Configuration Guide
6. API Reference
7. Troubleshooting
8. Advanced Usage
9. Examples & Templates
10. FAQ

🚀 Getting Started

Prerequisites

Before you begin, ensure you have:

• Python 3.12+: The project requires Python 3.12 or higher
• UV Package Manager: Recommended for dependency management
• Gemini API Key: Required for Google AI integration
• Git: For version control

Environment Setup

1. Clone the Repository

   git clone <repository-url>
   cd marketing
   

2. Create Virtual Environment

   # Using UV (recommended)
   uv venv
   uv sync
   
   # Or using standard Python
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

3. Configure Environment Variables

   # Create .env file
   cp .env.example .env
   
   # Edit .env with your API keys
   GOOGLE_API_KEY=your_gemini_api_key_here
   SERPER_API_KEY=your_serper_api_key_here  # Optional
   

4. Verify Installation

   python -c "import crewai; print('CrewAI installed successfully!')"
   

🏗️ Architecture Deep Dive

System Overview

The Marketing Crew follows a multi-agent architecture where specialized AI agents collaborate to complete marketing tasks:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Input Data   │───▶│  CrewAI Engine   │───▶│  Output Files   │
│                 │    │                  │    │                 │
│ - Product Info │    │ - Agent Manager  │    │ - Strategies    │
│ - Target       │    │ - Task Scheduler │    │ - Content       │
│ - Budget       │    │ - Process Flow   │    │ - Calendars     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   AI Agents      │
                    │                  │
                    │ • Head of Mkt    │
                    │ • Content Creator│
                    │ • Blog Writer    │
                    │ • SEO Specialist │
                    └──────────────────┘

Core Components

1. CrewAI Framework

• Agent Management: Handles agent lifecycle and communication
• Task Orchestration: Manages task execution and dependencies
• Process Control: Supports sequential and parallel execution modes

2. LLM Integration

• Model: Gemini 2.0 Flash (configurable)
• Temperature: 0.7 (balanced creativity and consistency)
• Rate Limiting: 3 RPM to manage API costs

3. Tool Integration

• SerperDev: Web search and research capabilities
• Web Scraping: Competitor and market data collection
• File Operations: Automated content storage and retrieval

🤖 Agent System

Agent Types & Responsibilities

Head of Marketing

Role: Strategic leadership and market analysis Responsibilities:

• Market research and trend analysis
• Competitor analysis and positioning
• Marketing strategy development
• Budget allocation and planning

Tools: Full access to all research and planning tools Output: Strategic documents and market insights

Content Creator (Social Media)

Role: Social media content and video production Responsibilities:

• Social media post creation
• Video script development
• Content calendar planning
• Platform-specific optimization

Tools: Content creation tools, research capabilities Output: Post drafts, video scripts, content calendars

Content Writer (Blogs)

Role: Long-form content creation Responsibilities:

• Blog post research and writing
• Content structure and flow
• Brand voice consistency
• Content optimization

Tools: Research tools, writing assistance Output: Blog drafts, research reports

SEO Specialist

Role: Search engine optimization Responsibilities:

• Keyword research and optimization
• Meta tag optimization
• Internal linking strategies
• Content performance analysis

Tools: SEO analysis tools, content optimization Output: SEO-optimized content, performance reports

Agent Configuration

Each agent is configured through YAML files in config/agents.yaml:

agent_name:
  llm: gemini/gemini-2.0-flash
  role: "Agent's specific role"
  goal: "Primary objective"
  backstory: "Context and expertise level"

Configuration Options:

• llm: AI model specification
• role: Clear responsibility definition
• goal: Measurable objective
• backstory: Context for better decision-making

📋 Task Workflow

Task Execution Flow

The Marketing Crew executes tasks in a sequential workflow:

1. Market Research
   ↓
2. Marketing Strategy
   ↓
3. Content Calendar
   ↓
4. Content Creation
   ↓
5. SEO Optimization

Task Configuration

Tasks are defined in config/tasks.yaml with:

• Description: Detailed task requirements
• Expected Output: Deliverable specifications
• Agent Assignment: Responsible agent
• Input Parameters: Required data and context

Task Types

Research Tasks

• Market Research: Industry analysis and insights
• Content Research: Topic research and keyword analysis
• Competitor Analysis: Market positioning and strategies

Planning Tasks

• Strategy Development: Comprehensive marketing plans
• Content Calendar: Weekly content scheduling
• Budget Planning: Resource allocation

Creation Tasks

• Content Drafting: Social media, blogs, videos
• Script Writing: Video and audio content
• Copywriting: Marketing copy and messaging

Optimization Tasks

• SEO Optimization: Search engine visibility
• Content Refinement: Quality improvement
• Performance Analysis: Metrics and insights

⚙️ Configuration Guide

Environment Configuration

Required Variables

# .env file
GOOGLE_API_KEY=your_gemini_api_key_here

Optional Variables

SERPER_API_KEY=your_serper_api_key_here
LOG_LEVEL=INFO
MAX_RPM=3

Agent Customization

Modifying Agent Behavior

1. Edit config/agents.yaml
2. Adjust role, goal, and backstory
3. Restart the application

Adding New Agents

1. Define agent in YAML config
2. Add agent method in crew.py
3. Assign tools and permissions
4. Integrate into task workflow

Task Customization

Modifying Task Parameters

1. Edit config/tasks.yaml
2. Adjust description and expected output
3. Modify agent assignments
4. Update input parameters

Adding New Tasks

1. Define task in YAML config
2. Create task method in crew.py
3. Assign to appropriate agent
4. Integrate into workflow

LLM Configuration

Model Selection

llm = LLM(
    model="gemini/gemini-2.0-flash",  # Change model here
    temperature=0.7,                   # Adjust creativity (0.0-1.0)
)

Rate Limiting

max_rpm=3  # Requests per minute
max_iter=30  # Maximum iterations per task

🔧 API Reference

Core Classes

TheMarketingCrew

Main crew class that orchestrates all operations.

Methods:

• head_of_marketing(): Returns Head of Marketing agent
• content_creator_social_media(): Returns Content Creator agent
• content_writer_blogs(): Returns Blog Writer agent
• seo_specialist(): Returns SEO Specialist agent
• marketingcrew(): Returns configured crew instance

Agent

Individual AI agent with specific capabilities.

Properties:

• config: Agent configuration from YAML
• tools: Available tools and capabilities
• llm: Language model instance
• max_rpm: Rate limiting configuration

Task

Individual task definition and execution.

Properties:

• config: Task configuration from YAML
• agent: Assigned agent
• output_json: Expected output format

Tool Integration

Available Tools

• SerperDevTool: Web search capabilities
• ScrapeWebsiteTool: Web scraping functionality
• DirectoryReadTool: File system access
• FileWriterTool: File creation and editing
• FileReadTool: File reading and parsing

Tool Configuration

tools=[
    SerperDevTool(),
    ScrapeWebsiteTool(),
    DirectoryReadTool('resources/drafts'),
    FileWriterTool(),
    FileReadTool()
]

🚨 Troubleshooting

Common Issues

1. API Key Errors

Problem: "Invalid API key" or authentication errors Solution:

• Verify API key in .env file
• Check key permissions and quotas
• Ensure proper environment variable loading

2. Import Errors

Problem: Module not found errors Solution:

• Verify Python version (3.12+)
• Install dependencies: uv sync or pip install -r requirements.txt
• Check virtual environment activation

3. Rate Limiting

Problem: "Rate limit exceeded" errors Solution:

• Reduce max_rpm in agent configuration
• Implement exponential backoff
• Check API provider limits

4. File Permission Errors

Problem: Cannot write to output directories Solution:

• Check directory permissions
• Ensure write access to resources/drafts/
• Verify file paths in configuration

Debug Mode

Enable verbose logging:

crew = Crew(
    agents=self.agents,
    tasks=self.tasks,
    process=Process.sequential,
    verbose=True,  # Enable debug output
    planning=True,
)

Log Analysis

Check logs for:

• Agent communication patterns
• Task execution flow
• Error messages and stack traces
• Performance bottlenecks

🚀 Advanced Usage

Custom Workflows

Parallel Execution

crew = Crew(
    agents=self.agents,
    tasks=self.tasks,
    process=Process.parallel,  # Execute tasks in parallel
    verbose=True,
)

Conditional Task Execution

@task
def conditional_task(self) -> Task:
    return Task(
        config=self.tasks_config['conditional_task'],
        agent=self.head_of_marketing(),
        context="Execute only if market research shows opportunity"
    )

Integration Patterns

External API Integration

from crewai_tools import BaseTool

class CustomAPITool(BaseTool):
    name: str = "Custom API Tool"
    description: str = "Integrates with external marketing APIs"
    
    def _run(self, query: str) -> str:
        # Implement API integration logic
        return "API response"

Database Integration

class DatabaseTool(BaseTool):
    name: str = "Database Tool"
    description: str = "Stores and retrieves marketing data"
    
    def _run(self, operation: str, data: dict) -> str:
        # Implement database operations
        return "Database operation result"

Performance Optimization

Caching Strategies

• Implement result caching for repeated queries
• Cache market research data
• Store agent responses for reuse

Batch Processing

• Group similar tasks for efficiency
• Process multiple content pieces simultaneously
• Optimize API calls and rate limiting

📝 Examples & Templates

Input Templates

Product Launch

inputs = {
    "product_name": "AI-Powered Analytics Platform",
    "target_audience": "Data Scientists, Business Analysts, Product Managers",
    "product_description": "Advanced analytics platform with AI-driven insights",
    "budget": "$100,000",
    "launch_date": "2024-03-15",
    "current_date": datetime.now().strftime("%Y-%m-%d"),
}

Content Campaign

inputs = {
    "campaign_name": "Summer Product Launch",
    "target_audience": "Young professionals, 25-35",
    "campaign_goal": "Increase brand awareness by 40%",
    "budget": "$50,000",
    "duration": "3 months",
    "current_date": datetime.now().strftime("%Y-%m-%d"),
}

Output Templates

Marketing Strategy

# Marketing Strategy: [Product Name]

## Executive Summary
Brief overview of the strategy and objectives.

## Market Analysis
- Target audience segmentation
- Competitor analysis
- Market opportunities

## Strategy Components
- Positioning strategy
- Marketing channels
- Budget allocation
- Timeline and milestones

## Key Performance Indicators
- Success metrics
- Measurement methods
- Reporting schedule

Content Calendar

# Content Calendar: [Week of Date]

## Monday
- **Blog Post**: [Topic] - [Author]
- **Social Media**: [Platform] - [Content Type]

## Tuesday
- **Video Content**: [Script Topic] - [Creator]
- **Email Campaign**: [Subject Line] - [Target Audience]

## Wednesday
- **Social Media**: [Platform] - [Content Type]
- **Blog Post**: [Topic] - [Author]

❓ FAQ

General Questions

Q: What makes Marketing Crew different from other marketing tools? A: Marketing Crew uses AI agents that work collaboratively, understanding context and creating cohesive strategies rather than isolated content pieces.

Q: Can I use my own AI models? A: Yes, the system is designed to be model-agnostic. You can configure different LLM providers in the configuration.

Q: How does the system handle different industries? A: The agents adapt to industry context through the input parameters and can be customized for specific verticals.

Technical Questions

Q: What's the maximum content length the system can generate? A: Content length is limited by the LLM's context window and can be configured through task parameters.

Q: Can I integrate with my existing marketing tools? A: Yes, the system supports custom tool integration through the CrewAI tools framework.

Q: How do I handle sensitive information? A: Sensitive data should be stored in environment variables and never committed to version control.

Usage Questions

Q: How often should I run the marketing crew? A: Frequency depends on your content needs. Weekly runs are recommended for most businesses.

Q: Can I customize the output format? A: Yes, output formats are configurable through the task definitions and can include various file types.

Q: What if I need to modify generated content? A: All generated content is stored as editable markdown files that can be reviewed and modified before publication.

---

📚 Additional Resources

• CrewAI Documentation
• Google AI Gemini Documentation
• Marketing Best Practices
• Content Strategy Guide

---

Need Help? Create an issue in the repository or check the troubleshooting section above.