🤖 Multi-Agent Social Media Automation System

Hybrid n8n + LangGraph Approach - Production-ready AI-powered social media automation

🎯 Overview

A sophisticated multi-agent system that automates social media content creation, scheduling, and publishing using 7 specialized AI agents working in harmony. Built with the recommended Hybrid n8n + LangGraph architecture for maximum flexibility and speed.

Why This Architecture?

✅ Fast Development: 3-4 weeks vs 2-3 months for pure code
✅ Visual Workflows: n8n provides intuitive workflow management
✅ Powerful AI: LangGraph handles complex agent reasoning
✅ Cost-Effective: ~$80-375/month vs $19,900 RUB/month alternatives
✅ Production-Ready: Scalable, maintainable, and extensible

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      n8n Workflows                           │
│  (Orchestration, Scheduling, API Integrations, Triggers)     │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/Webhooks
┌──────────────────────▼──────────────────────────────────────┐
│              FastAPI Backend (Port 8000)                     │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         LangGraph Agent Orchestration                  │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │ │
│  │  │Researcher│→ │ Marketer │→ │Copywriter│→ ...        │ │
│  │  └──────────┘  └──────────┘  └──────────┘            │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│              PostgreSQL Database                             │
│  (Business Info, Research, Content, Analytics)               │
└─────────────────────────────────────────────────────────────┘

The 7 AI Agents

🔍 AI Researcher - Market research, trend analysis, competitor audit
📊 AI Marketer - Content strategy, SMM goals, content planning
✍️ AI Copywriter - Text generation, variations, A/B testing ideas
🎨 AI Designer - Visual content, layouts, image generation (DALL-E)
✅ AI Moderator - Fact-checking, brand consistency, approval workflow
📅 AI Scheduler - Automatic publication via platform APIs
📈 AI Analytical - Metrics collection, pattern analysis, ROI/KPI

🚀 Quick Start

For a faster setup, see QUICKSTART.md - Get running in 5 minutes!

Prerequisites

Python 3.9+
Docker & Docker Compose (for n8n and PostgreSQL)
OpenAI API key
Platform API credentials (Telegram, VK, etc.)

1. Clone & Setup

cd multi_agent_social_media_automation

# Install Python dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your API keys

2. Start Infrastructure

# Start PostgreSQL and n8n
docker-compose up -d

# Wait for services to be ready (30 seconds)

3. Initialize Database

# Run database migrations
psql -h localhost -U postgres -d social_media < database/schema.sql

# Or use Python script
python scripts/init_database.py

4. Start LangGraph API

# Start FastAPI backend
uvicorn api.main:app --reload --port 8000

5. Configure n8n

Open http://localhost:5678
Import workflows from n8n_workflows/ directory
Configure environment variables in n8n settings
Test each workflow individually

6. Run Your First Workflow

# Trigger via API
curl -X POST http://localhost:8000/api/v1/trigger/researcher

# Or use n8n's manual trigger

📁 Project Structure

multi_agent_social_media_automation/
├── README.md                 # This file
├── docker-compose.yml         # Docker services (n8n, PostgreSQL)
├── requirements.txt           # Python dependencies
├── .env.example              # Environment variables template
│
├── langgraph_agents/         # LangGraph agent implementations
│   ├── __init__.py
│   ├── researcher.py         # AI Researcher agent
│   ├── marketer.py           # AI Marketer agent
│   ├── copywriter.py         # AI Copywriter agent
│   ├── designer.py           # AI Designer agent
│   ├── moderator.py          # AI Moderator agent
│   ├── scheduler.py          # AI Scheduler agent
│   ├── analytical.py        # AI Analytical agent
│   └── workflow.py           # LangGraph state graph orchestration
│
├── api/                      # FastAPI backend
│   ├── __init__.py
│   ├── main.py              # FastAPI app & routes
│   └── webhooks.py           # Webhook endpoints for n8n
│
├── n8n_workflows/            # n8n workflow JSON files
│   ├── 01_ai_researcher.json
│   ├── 02_ai_marketer.json
│   ├── 03_ai_copywriter.json
│   ├── 04_ai_designer.json
│   ├── 05_ai_moderator.json
│   ├── 06_ai_scheduler.json
│   └── 07_ai_analytical.json
│
├── database/                 # Database schema & migrations
│   ├── schema.sql            # PostgreSQL schema
│   └── migrations/           # Database migration scripts
│
├── config/                   # Configuration files
│   ├── __init__.py
│   └── settings.py           # App settings & constants
│
└── scripts/                  # Utility scripts
    ├── init_database.py      # Database initialization
    └── test_agents.py        # Test individual agents

⚙️ Configuration

Environment Variables

Create a .env file:

# OpenAI API
OPENAI_API_KEY=sk-...

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/social_media

# Platform Credentials
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
VK_ACCESS_TOKEN=...
VK_GROUP_ID=...

# n8n
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=yourpassword
N8N_ENCRYPTION_KEY=your-encryption-key

# API
API_HOST=0.0.0.0
API_PORT=8000

n8n Configuration

Access n8n: http://localhost:5678
Set Credentials: Go to Settings → Credentials
Import Workflows: Use the JSON files in n8n_workflows/
Configure Webhooks: Update webhook URLs to point to your API

🔄 Workflow Flow

Content Generation Pipeline

1. Schedule Trigger (n8n)
   ↓
2. AI Researcher (LangGraph via API)
   → Research market trends & competitors
   → Save to database
   ↓
3. AI Marketer (LangGraph via API)
   → Create content strategy
   → Define themes & goals
   ↓
4. AI Copywriter (LangGraph via API)
   → Generate text content
   → Create variations for A/B testing
   ↓
5. AI Designer (n8n OpenAI node)
   → Generate images with DALL-E
   → Process & optimize images
   ↓
6. AI Moderator (LangGraph via API)
   → Review content quality
   → Check brand guidelines
   → Decision: Approve/Reject
   ↓
7a. If Approved → AI Scheduler (n8n)
    → Publish to platforms
    → Save published post
    ↓
7b. If Rejected → Loop back to Copywriter
   ↓
8. AI Analytical (LangGraph via API)
   → Collect metrics after 24h
   → Analyze performance
   → Generate recommendations
   → Update strategy (feedback loop)

📡 API Endpoints

LangGraph Agent Endpoints

# Trigger AI Researcher
POST /api/v1/agents/researcher
Body: { "business_id": 1 }

# Trigger AI Marketer
POST /api/v1/agents/marketer
Body: { "research_id": 123 }

# Trigger AI Copywriter
POST /api/v1/agents/copywriter
Body: { "strategy_id": 456, "platform": "telegram", "theme": "business_tips" }

# Trigger AI Designer
POST /api/v1/agents/designer
Body: { "content_text": "...", "style": "modern" }

# Trigger AI Moderator
POST /api/v1/agents/moderator
Body: { "content_id": 789, "brand_guidelines": "..." }

# Trigger AI Scheduler
POST /api/v1/agents/scheduler
Body: { "content_id": 789, "platform": "telegram", "scheduled_time": "2024-01-01T10:00:00" }

# Trigger AI Analytical
POST /api/v1/agents/analytical
Body: { "post_id": 101112 }

Webhook Endpoints (for n8n)

# Receive webhook from n8n
POST /webhook/content-approved
POST /webhook/content-rejected
POST /webhook/post-published
POST /webhook/analytics-ready

Health & Status

GET /health
GET /api/v1/status
GET /api/v1/agents/status

🧪 Testing

Test Individual Agents

# Test Researcher
python scripts/test_agents.py --agent researcher

# Test Full Workflow
python scripts/test_agents.py --workflow full

Test API Endpoints

# Using curl
curl -X POST http://localhost:8000/api/v1/agents/researcher \
  -H "Content-Type: application/json" \
  -d '{"business_id": 1}'

# Using Python
python scripts/test_api.py

Test n8n Workflows

Open n8n UI
Click "Execute Workflow" on any workflow
Check execution logs
Verify database entries

📊 Database Schema

Key tables:

business_info - Company/business information
research_data - Market research results
content_strategy - Marketing strategies
generated_content - Generated posts (draft/approved/rejected)
published_posts - Published content
analytics - Performance metrics
recommendations - AI-generated recommendations

See database/schema.sql for full schema.

🔧 Development

Adding a New Agent

Create agent file in langgraph_agents/:

# langgraph_agents/new_agent.py
from langgraph.graph import StateGraph
from typing import TypedDict

class AgentState(TypedDict):
    input_data: str
    output_data: str

def new_agent_node(state: AgentState) -> AgentState:
    # Your agent logic here
    return state

Add to workflow in langgraph_agents/workflow.py
Create API endpoint in api/main.py
Create n8n workflow in n8n_workflows/

Adding a New Platform

Create adapter (reuse from social_media_automation/platform_adapters/)
Add to scheduler in langgraph_agents/scheduler.py
Update n8n workflow 06_ai_scheduler.json

🚢 Deployment

Production Setup

Use managed PostgreSQL (AWS RDS, DigitalOcean, etc.)
Deploy FastAPI (Gunicorn + Nginx, or Docker)
Deploy n8n (Docker, or n8n Cloud)
Set up monitoring (Prometheus, Grafana)
Configure backups (Database + n8n workflows)

Docker Production

# Build and run
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose logs -f

Environment-Specific Configs

.env.development - Local development
.env.staging - Staging environment
.env.production - Production environment

📈 Monitoring & Analytics

Built-in Analytics

Performance Reports: /api/v1/analytics/report
Agent Metrics: Track execution times, success rates
Content Performance: Engagement rates, top posts
Cost Tracking: API usage, costs per post

Logging

Application Logs: logs/app.log
Agent Logs: logs/agents.log
API Logs: FastAPI automatic logging

Alerts

Configure alerts for:

Failed agent executions
High API costs
Low engagement rates
Database connection issues

💰 Cost Breakdown

Monthly Costs (Estimated):

n8n: $0 (self-hosted) or $20 (cloud)
OpenAI API: $50-200 (depending on volume)
DALL-E: $20-100 (image generation)
PostgreSQL: $0-25 (self-hosted or managed)
Server/Hosting: $10-50 (VPS)

Total: ~$80-375/month

Cost per Post:

Text only: ~$0.03-0.06 (GPT-4)
With image: ~$0.07-0.14 (GPT-4 + DALL-E)

🐛 Troubleshooting

Common Issues

n8n not starting:

# Check Docker logs
docker-compose logs n8n

# Verify port 5678 is available
netstat -an | grep 5678

Database connection errors:

# Test connection
psql -h localhost -U postgres -d social_media

# Check DATABASE_URL in .env

API not responding:

# Check if FastAPI is running
curl http://localhost:8000/health

# Check logs
tail -f logs/app.log

Agent execution failures:

Check OpenAI API key
Verify database has required data
Check agent logs in logs/agents.log

📚 Documentation

Development Approaches - Detailed comparison
n8n Implementation Guide - n8n setup
API Reference - Full API docs
Agent Details - Agent specifications

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📝 License

This project is provided as-is for educational and commercial use.

🆘 Support

Issues: Open a GitHub issue
Questions: Check documentation or open a discussion
Commercial Support: Contact for enterprise support

🎉 Acknowledgments

Built with LangGraph
Workflow automation by n8n
AI powered by OpenAI

Ready to automate your social media? Start with the Quick Start guide above! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
api		api
config		config
database		database
langgraph_agents		langgraph_agents
n8n_workflows		n8n_workflows
scripts		scripts
.gitignore		.gitignore
QUICKSTART.md		QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example
requirements.txt		requirements.txt

soulcrancerdev/multi-agent-social-media-automation

Folders and files

Latest commit

History

Repository files navigation