AdPilot - Conversational AdTech Agent System

AdPilot is an AI-powered platform that allows non-technical business owners to manage their digital marketing campaigns through natural language conversation. The system integrates with advertising and marketing APIs and executes actions through specialized AI sub-agents.

🚀 Features

• Conversational Interface: Manage campaigns through natural language chat
• Multi-LLM Support: Switch between OpenAI, Anthropic Claude, Google Gemini, and z.ai
• Specialized AI Agents:
  • MediaBuyerAgent: Manage ad campaigns, budgets, and performance
  • EmailCopyAgent: Generate email content and manage campaigns
  • AnalyticsAgent: Analyze performance and provide insights
  • SchedulingAgent: Automate recurring tasks and optimizations
• Mock Integrations: Google Ads, Meta Ads, Klaviyo, Mailchimp with realistic sample data
• Real-time Chat: Stream responses from AI agents
• Analytics Dashboard: Visual performance metrics and comparisons
• User Authentication: Secure access with Clerk

📋 Tech Stack

• Frontend: Next.js 14 (App Router), React 19, TailwindCSS
• Backend: Next.js API Routes, Vercel Edge Functions
• Database: Supabase (PostgreSQL)
• Authentication: Clerk
• LLM Providers: OpenAI, Anthropic, Google Gemini, z.ai
• Language: TypeScript

🏗️ Architecture

AdPilot/
├── app/                          # Next.js App Router
│   ├── (auth)/                   # Auth pages (sign-in, sign-up)
│   ├── (dashboard)/              # Protected dashboard pages
│   │   ├── chat/                 # Main chat interface
│   │   ├── analytics/            # Analytics dashboard
│   │   ├── integrations/         # Integration management
│   │   └── settings/             # User settings
│   ├── api/                      # API routes
│   │   ├── chat/                 # Main chat endpoint
│   │   ├── agents/               # Agent-specific endpoints
│   │   └── auth/                 # Auth webhooks
│   ├── layout.tsx                # Root layout
│   └── page.tsx                  # Landing page
├── agents/                       # AI Agent implementations
│   ├── core/                     # Base agent, router, context
│   └── implementations/          # Specialized agents
├── components/                   # React components
│   ├── chat/                     # Chat UI components
│   ├── dashboard/                # Dashboard components
│   └── ui/                       # Reusable UI components
├── integrations/                 # Platform integrations
│   └── mock/                     # Mock API implementations
├── lib/                          # Utilities and clients
│   ├── db/                       # Database client & schema
│   ├── llm/                      # LLM provider abstraction
│   └── utils/                    # Helper functions
└── types/                        # TypeScript definitions

🛠️ Setup Instructions

Prerequisites

• Node.js 18+ and npm
• Supabase account
• Clerk account
• API keys for at least one LLM provider (OpenAI, Anthropic, Google, or z.ai)

1. Clone and Install

git clone https://github.com/roberjo/AdPilot.git
cd AdPilot
npm install

2. Environment Variables

Create a .env.local file in the root directory:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard/chat
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard/chat

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxxxx
SUPABASE_SERVICE_ROLE_KEY=xxxxx

# OpenAI (optional, but recommended)
OPENAI_API_KEY=sk-xxxxx

# Anthropic Claude (optional)
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Google Gemini (optional)
GOOGLE_GENERATIVE_AI_API_KEY=xxxxx

# z.ai (optional)
ZAI_API_KEY=xxxxx
ZAI_API_URL=https://api.z.ai

# Application Settings
NEXT_PUBLIC_APP_URL=http://localhost:3000
DEFAULT_LLM_PROVIDER=openai

3. Set Up Supabase

1. Create a new Supabase project at supabase.com
2. Go to Project Settings > API to get your keys
3. Run the database schema:
   • Go to SQL Editor in Supabase
   • Copy contents from lib/db/schema.sql
   • Execute the SQL

4. Set Up Clerk

1. Create a Clerk application at clerk.com
2. Enable Email/Password and OAuth providers (Google, Facebook)
3. Copy your API keys to .env.local
4. Update Clerk settings:
   • Set redirect URLs to match your app
   • Configure session settings

5. Get LLM API Keys

Choose at least one provider:

• OpenAI: platform.openai.com
• Anthropic: console.anthropic.com
• Google AI: ai.google.dev
• z.ai: Contact z.ai for API access

6. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

📖 Usage

Chat with AI Agents

1. Sign up or sign in to your account
2. Navigate to the Chat page
3. Ask questions or give commands in natural language:
   • "Show me my campaign performance"
   • "Increase the budget for my top campaign by $100"
   • "Write an email for our summer sale"
   • "Compare Google Ads vs Meta Ads performance"

Agent Capabilities

MediaBuyerAgent

• Query campaign performance (CTR, ROAS, CPA)
• Modify campaign budgets
• Pause/resume campaigns
• Create new campaigns
• Provide optimization recommendations

EmailCopyAgent

• Generate email subject lines
• Write email body copy
• Create preview text and CTAs
• Schedule email campaigns
• Provide A/B testing suggestions

AnalyticsAgent

• Analyze performance across platforms
• Calculate and interpret KPIs
• Identify trends and patterns
• Generate comparative reports
• Provide actionable recommendations

SchedulingAgent

• Schedule recurring optimizations
• Set up automated reports
• Create scheduled budget adjustments
• Configure email automation
• Manage multi-step workflows

🔧 Configuration

Switching LLM Providers

Update DEFAULT_LLM_PROVIDER in .env.local:

• openai - OpenAI GPT-4
• anthropic - Claude 3.5 Sonnet
• google - Gemini 1.5 Pro
• zai - z.ai models

Users can also change their preferred provider in Settings.

Custom Agent Instructions

Users can add custom instructions in Settings to personalize AI behavior:

• Preferred tone and style
• Business-specific context
• Priority metrics

🧪 Mock Data

The application includes mock integrations with realistic sample data for:

• Google Ads campaigns
• Meta Ads campaigns
• Email campaigns (Klaviyo/Mailchimp)

Mock APIs simulate delays and provide CRUD operations for testing without real API connections.

📊 Database Schema

Key tables:

• users - User profiles and preferences
• conversations - Chat history
• ad_accounts - Connected ad accounts
• integrations - OAuth tokens (encrypted)
• agent_memory - Agent-specific memory
• actions_log - Audit trail
• scheduled_tasks - Automation jobs
• subscriptions - Billing (future)
• usage_tracking - Usage metrics (future)

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables
4. Deploy

npm run build

Environment Variables for Production

Update .env.local values for production:

• Use production Clerk keys
• Use production Supabase keys
• Set NEXT_PUBLIC_APP_URL to your domain
• Ensure all LLM API keys are valid

🔐 Security

• All tokens encrypted at rest in Supabase
• JWT-based authentication for API routes
• Row Level Security (RLS) enabled on all tables
• Clerk handles authentication and session management
• Action logging for auditability

🎯 Roadmap

Phase 1 - MVP ✅

• ✅ Authentication (Clerk)
• ✅ Database setup (Supabase)
• ✅ Multi-LLM support
• ✅ Core agent system
• ✅ Chat interface
• ✅ Mock integrations

Phase 2 - Action Layer

• Real ad platform OAuth integration
• Write operations for campaigns
• Email campaign scheduling
• Permission management
• Action confirmation flows

Phase 3 - Automation

• Multi-agent collaboration
• Advanced scheduling
• Billing integration (Stripe)
• Usage tracking and limits
• White-label options

Phase 4 - Optimization

• Additional platform integrations (TikTok, LinkedIn)
• Enhanced caching and performance
• ML-based optimization suggestions
• Agent marketplace

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

See LICENSE file for details.

🐛 Known Issues

• Mock integrations do not persist data between sessions
• No real OAuth flows implemented yet
• Streaming responses not yet implemented in UI
• Email sending functionality is simulated

📞 Support

For issues and questions:

• GitHub Issues: github.com/roberjo/AdPilot/issues
• Email: support@adpilot.ai

🙏 Acknowledgments

• Built with Next.js, React, and TailwindCSS
• Powered by OpenAI, Anthropic, Google, and z.ai
• Authenticated by Clerk
• Stored in Supabase

---

Note: This is a demonstration/MVP version. Real integrations with ad platforms require OAuth implementation and proper API credentials. Mock data is used for all platform integrations.