agent-content-kit

2. Start Everything

# Start all services (API + Celery + Redis)
docker compose -f docker-compose.agents.yml up -d

That's it! All services start automatically:

• FastAPI backend (port 8000)
• Celery worker (background tasks)
• Celery beat (scheduler)
• Redis (task queue)

3. Open Dashboard

Navigate to http://localhost:8000 — the Setup Wizard will guide you through the rest!

🔧 Alternative: Manual Setup (Python)

If you prefer running locally without Docker:

Prerequisites

• Python 3.9+
• Node.js 18+ (for dashboard)
• FFmpeg — required for video composition
• yt-dlp — required for content fetching
• Google Chrome — required for auto-publishing

macOS:

brew install ffmpeg yt-dlp

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg
pip install yt-dlp

⚠️ FFmpeg is required — without it, videos will not render. Verify with ffmpeg -version

Installation Steps

# 1. Create virtual environment
python3 -m venv venv

# 2. Activate it (IMPORTANT!)
# macOS/Linux:
source venv/bin/activate
# Windows: venv\Scripts\activate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Install Playwright browser
playwright install chromium

# 5. Build dashboard
cd dashboard
npm install
npm run build
cd ..

# 6. Start the server
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Open http://localhost:8000 to access the dashboard.

🔑 Required API Keys

Minimum Setup (Required)

Recommended (For Full Experience)

Optional

Quick start: Set LLM_PROVIDER=openai, add your OPENAI_API_KEY and PEXELS_API_KEY — that's all you need to create your first video. No Telegram? The system still works, but you'll need to manually approve jobs via the Dashboard before auto-publishing.

📱 Auto-Publishing (No OAuth Required)

Auto-publishing uses Playwright browser automation with a real Chrome session. No developer apps, no API keys — just login once.

Connect Platforms

# One-time login (opens Chrome window)
python -m backend.core.browser_session login youtube
python -m backend.core.browser_session login tiktok
python -m backend.core.browser_session login facebook

Or go to http://localhost:8000/connections → click Connect for each platform.

📅 Content Calendar — Set It and Forget It

Agent Content Kit's scheduler runs fully automatically on a cron schedule. Define a template once — it creates and publishes new videos every day without any manual input.

How the Scheduler Works

⏰ Celery Beat ticks every minute
     ↓
Finds schedules that are due
     ↓
Auto-creates a new ContentJob from the template
     ↓
🤖 Runs the full 10-agent pipeline
     ↓
📱 Sends video preview to Telegram for approval
     ↓
✅ Approve → auto-publishes to YouTube / TikTok / Facebook

Create a Schedule (via API)

curl -X POST http://localhost:8000/api/v1/schedules/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily TikTok from VnExpress",
    "cron_expression": "0 9 * * *",
    "source_url": "https://vnexpress.net",
    "video_count": 3,
    "platforms": ["tiktok", "youtube"],
    "language": "vi",
    "niche": "news"
  }'

Or Use the Dashboard

Go to http://localhost:8000 → Calendar tab → click + New Schedule

Cron Expression Cheat Sheet

Schedule Management

# List all schedules
GET /api/v1/schedules/

# Trigger a schedule immediately (for testing)
POST /api/v1/schedules/{id}/run-now

# Enable / disable a schedule
POST /api/v1/schedules/{id}/toggle

# Update cron timing
PUT /api/v1/schedules/{id}

Requirements

⚠️ The Content Calendar requires Celery + Redis running alongside the API.

# Option A: Docker Compose (recommended)
docker compose -f docker-compose.agents.yml up -d
# Includes API + Celery Worker + Celery Beat + Redis automatically

# Option B: Manual
uvicorn backend.main:app --host 0.0.0.0 --port 8000  # Terminal 1
celery -A backend.core.celery_app worker --loglevel=info -Q processing  # Terminal 2
celery -A backend.core.celery_app beat --loglevel=info  # Terminal 3

💬 Telegram Approval Flow

Pipeline completes
     ↓
📱 Telegram sends: preview message + video file + thumbnail
     ↓
[✅ Approve & Upload]   [❌ Reject]
     ↓
✅ → Auto uploads to YouTube, TikTok, Facebook
❌ → Job marked as rejected, no upload

Setup (2 minutes):

1. Open Telegram → search @BotFather → send /newbot
2. Copy the token into .env as TELEGRAM_BOT_TOKEN
3. Open your bot → send /start
4. Go to Setup Wizard → Telegram → click "Detect my Chat ID"
5. ✅ Done!

🧪 API Reference

Interactive docs: http://localhost:8000/docs

🐛 Troubleshooting

"uvicorn: command not found"

Cause: Virtual environment not activated.

Fix: Either activate the venv first:

source venv/bin/activate
uvicorn backend.main:app --host 0.0.0.0 --port 8000

Or use the full path:

./venv/bin/uvicorn backend.main:app --host 0.0.0.0 --port 8000

Dashboard not loading / 404 errors

Cause: Dashboard not built or built incorrectly.

Fix: Rebuild the dashboard:

cd dashboard
npm run build
cd ..

"API key configuration not found" warning

Cause: .env file missing or required API keys not set.

Fix: Ensure .env exists and contains at least OPENAI_API_KEY and PEXELS_API_KEY.

FFmpeg errors during video creation

Cause: FFmpeg not installed or not in PATH.

Fix: Install FFmpeg and verify with ffmpeg -version.

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feature/amazing
3. Commit your changes
4. Push: git push origin feature/amazing
5. Open a Pull Request

All contributions welcome — bug fixes, new uploaders, new LLM providers, UI improvements.

📬 Contact & Support

🙏 Credits

• OpenAI / Anthropic / [Google](h