AgentSEO Documentation

Welcome to AgentSEO, your Autonomous SEO Copilot for WordPress. AgentSEO is an advanced, autonomous AI-powered platform designed to handle your SEO, content creation, and business management workflows.

This documentation will guide you through installing the application on your own server, configuring the necessary API keys, and setting up your autonomous agents.

2. Database Setup

AgentSEO requires a PostgreSQL database to store your business data, articles, and agent configurations securely.

Option A: cPanel PostgreSQL

If your hosting provider supports PostgreSQL natively in cPanel, you can create a new database and user directly from the "PostgreSQL Databases" section in cPanel. Note the database name, username, and password.

Option B: External Managed Database (Recommended)

If your host only provides MySQL, or if you prefer a dedicated database service, we highly recommend using a free or paid external PostgreSQL provider such as:

• Supabase (Free tier available)
• Neon.tech (Free tier available)
• Render

Regardless of the method you choose, you must obtain a DATABASE_URL connection string. It will look something like this:

3. Installation (VPS/Ubuntu - Recommended)

For advanced users installing on an unmanaged VPS (Ubuntu 22.04/24.04), follow these CLI steps.

1. Prerequisites: Ensure Node.js (v20+) and PM2 are installed.
2. Extract Files: Upload and unzip the project files into your desired directory (e.g., /var/www/agentseo).
3. Install Dependencies:

   cd /var/www/agentseo
   npm install

4. Configure Environment: Create a .env file:

   cp .env.example .env
   nano .env

   Fill in the required variables (DATABASE_URL, APP_MASTER_KEY, CRON_SECRET, APP_URL). Remember that APP_MASTER_KEY must be at least 32 characters.
5. Build the App:

   npm run build

6. Start with PM2:

   pm2 start npm --name "agentseo" -- start
   pm2 save
   pm2 startup

Remember to visit https://your-domain.com/setup to run the database migrations!

4. Installation (cPanel - Shared Hosting)

While a VPS is recommended, AgentSEO can run on a standard cPanel shared hosting environment if your provider allows background tasks.

1. Upload and Extract: Upload the AgentSEO zip file to your chosen directory (e.g., public_html/agentseo) via cPanel File Manager and extract it.
2. Setup Node.js App: In cPanel, locate the "Setup Node.js App" icon under the Software section.
   
3. Configure App:
   • Node.js Version: Select 20.x or higher.
   • Application Mode: Production
   • Application Root: The folder where you extracted the files (e.g., public_html/agentseo).
   • Application URL: The domain/subdomain where the app will be accessible.
   • Application Startup File: server.js
4. Environment Variables: Scroll down to the Environment Variables section and add the following strictly required variables:
   • DATABASE_URL: Your PostgreSQL connection string (from Step 2).
   • APP_MASTER_KEY: A secure random string. Must be exactly 32 characters or longer.
   • CRON_SECRET: A secure random string used to protect your automated cron jobs.
   • NEXT_PUBLIC_APP_URL (or APP_URL): Your full application URL (e.g., https://yourdomain.com).
   • NODE_ENV: Set to production.
5. Install & Build: Click the Run NPM Install button. Once complete, find the option to run a custom script and execute npm run build.
6. Start App: Click the Start App button at the top of the Node.js setup page.

5. Initial Setup

After your database is migrated, the next step is to create your master administrator account.

Navigate to /register on your domain to create your login credentials. This first user automatically becomes the system owner.

Once logged in, you will arrive at the main AgentSEO dashboard, your central hub for operations.

6. Settings: AI Brain & System Configuration

Navigate to Settings > AI Brain to configure the AI models, APIs, and email settings.

Selecting AI Models

You can choose different AI models for various tasks:

• Heavy Duty Model: Used for complex reasoning and deep research.
• Default Model: Used for standard generation and everyday tasks.
• Image Model: Used for generating AI images.

API Keys

OpenRouter API Key (For AI Models)

OpenRouter provides access to models like Claude 3.5, Gemini, and Llama.

1. Go to openrouter.ai and Sign In (or create a free account).
2. Navigate to your account settings and click on API Keys.
3. Click Create API Key. Give it a name like "AgentSEO".
4. Copy the key (it starts with sk-or-v1-) and paste it into the OpenRouter field.

Serper.dev API Key (For Google Search)

1. Go to serper.dev and create a free account.
2. Your API key will be in the dashboard. Copy and paste it.

Pixabay and Freepik API Keys (For Stock Photos)

These keys allow the AI to search for high-quality stock photos.

1. Pixabay: Sign up at Pixabay API Docs and get your key.
2. Freepik: Sign up at Freepik API and get your key.

SMTP Email Configuration

Configure your SMTP settings to allow the system to send emails, such as password reset links.

AWS S3 Image Storage (Required)

To ensure images generated by the AI are permanently and securely stored, AgentSEO connects directly to Amazon Web Services (AWS) S3.

Step 1: Create the S3 Bucket

1. Log in to your AWS Management Console and navigate to S3.
2. Click Create bucket.
3. Bucket name: Enter a unique name (e.g., agentseo-assets). Save this as your AWS_S3_BUCKET_NAME.
4. AWS Region: Choose your preferred region. Save this code (e.g., us-east-1) as your AWS_REGION.
5. Block Public Access: Uncheck "Block all public access" and acknowledge the warning. This is required so your blog visitors can view the images.
6. Click Create bucket.

Step 2: Make the Bucket Publicly Readable

1. Click on your new bucket and go to the Permissions tab.
2. Scroll to Bucket policy and click Edit.
3. Paste the following JSON, replacing YOUR-BUCKET-NAME with your actual bucket name:

   {
       "Version": "2012-10-17",
       "Statement":[
           {
               "Sid": "PublicReadGetObject",
               "Effect": "Allow",
               "Principal": "*",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
           }
       ]
   }

4. Click Save changes.

Step 3: Create an IAM User

1. Navigate to the IAM dashboard in AWS.
2. Go to Users -> Create user. Name it agentseo-user.
3. Under permissions, choose Attach policies directly and select AmazonS3FullAccess. Create the user.
4. Click on the new user, go to the Security credentials tab, and click Create access key.
5. Choose Application running outside AWS.
6. Copy the Access key ID and Secret access key. Enter all four of these values into your AgentSEO settings page.

7. Settings: Business Identity

Navigate to Settings > Business Identity to set the foundational knowledge for your AI.

This is where you define your business. The AI uses this context for everything it writes.

• Company Name: Your brand's name.
• Product Description: What you sell or offer.
• Target Audience: Who your customers are.
• USP (Unique Selling Proposition): What makes you better than competitors.

Filling this out ensures the AI writes highly contextual, tailored content rather than generic articles.

8. Settings: Brand Voice & Writing Style

Navigate to Settings > Brand Voice and Settings > Writing Style to configure how the AI sounds.

Brand Voice Generator

You can use the built-in AI Brand Voice Generator to automatically create a voice profile based on your business identity, or paste a manual markdown strategy if you have specific guidelines.

Writing Style Examples

Upload writing style examples so the AI can learn your exact cadence and tone.

• Paste Text: Paste examples of your best content directly.
• Import URL: Provide a link to an existing blog post or article, and the system will extract the style.

9. Settings: Knowledge Base / RAG

Navigate to Settings > Knowledge to provide specific data to your AI.

Product Evangelist Mode

When "Product Evangelist Mode" is active, the AI actively uses the information in your Knowledge Base to promote your products naturally within the generated articles.

Uploading Knowledge

You can train the AI on your specific business data by uploading:

• PDFs: Manuals, brochures, or whitepapers.
• URLs: Links to your website pages or documentation.
• Text: Raw text snippets or FAQs.
• Product Images: Images of your products for the AI to reference or include.

10. Settings: Integrations

Navigate to Settings > Integrations to connect external services.

Connecting WordPress

To allow AgentSEO to publish articles directly to your blog, connect your WordPress site.

Creating a WordPress Application Password:

For security, never use your main WordPress admin password. Instead, generate an Application Password.

1. Log in to your WordPress admin dashboard.
2. Go to Users > Profile (or Edit your specific user profile).
3. Scroll down to the Application Passwords section.
4. Enter a name for the application (e.g., "AgentSEO") and click Add New Application Password.
5. WordPress will generate a secure, 24-character password.
6. Copy this password and use it along with your WordPress username in the AgentSEO Integration modal.

Custom Webhook

You can configure a custom webhook to trigger external actions when certain events occur in AgentSEO. This serves as an alternative to the WordPress blog integration, allowing you to publish your generated articles to any custom platform.

• Webhook URL: The URL that will receive the POST request.
• Secret: A secret key to secure your webhook payload.

Google Service Account JSON Key

The Performance Agent requires access to Google Analytics 4 (GA4) and Google Search Console (GSC) to monitor your site's performance.

Prerequisites

• Admin access to your Google Analytics 4 property
• A Google Cloud project (will be created if you don't have one)

Step 1: Enable the Google Analytics Data API & Google Search Console API

1. Go to the Google Cloud Console
2. Select or create a project for your AgentSEO integration
3. Navigate to APIs & Services > Library
4. Search for "Google Analytics Data API"
5. Click on the API and click Enable
6. Search for "Google Search Console API"
7. Click on the API and click Enable

Step 2: Create a Service Account

1. In Google Cloud Console, go to APIs & Services > Credentials
2. Click Create Credentials and select Service Account
3. Fill in the service account details:
   • Name: agent-seo-ga4 (or any descriptive name)
   • Description: "Service account for AgentSEO GA4 integration"
4. Click Create and Continue
5. Skip the optional "Grant this service account access to project" step (click Continue)
6. Skip the optional "Grant users access to this service account" step (click Done)

Step 3: Create and Download the Service Account Key

1. Find your newly created service account in the Credentials page
2. Click on the service account email
3. Go to the Keys tab
4. Click Add Key > Create new key
5. Select JSON as the key type
6. Click Create
7. The JSON key file will automatically download to your computer
8. Important: Keep this file secure! It provides access to your GA4 and GSC data

Step 4: Grant Access to Your GA4 Property

1. Go to Google Analytics
2. Select your GA4 property
3. Click Admin (gear icon in bottom left)
4. Under Property, click Property access management
5. Click the + button in the top right and select Add users
6. Enter the service account email (from Step 2, looks like seo-machine-ga4@your-project.iam.gserviceaccount.com)
7. Select the role Viewer (read-only access)
8. Uncheck "Notify new users by email"
9. Click Add

Step 5: Grant Access to Your Search Console Property

1. Go to Google Search Console
2. Select your property (website)
3. Click Settings in the left sidebar
4. Click Users and permissions
5. Click Add user
6. Enter the service account email (e.g., seo-machine-ga4@your-project.iam.gserviceaccount.com)
7. Select permission level: Full (required for API access, but only provides read access)
8. Click Add

Step 6: Configure the Integration

Once you have your JSON Key file, navigate to the AgentSEO Integration settings page. Upload the downloaded JSON file in the Google Service Account JSON Key section.

Sitemap URL

Add your website's Sitemap URL so AgentSEO can discover your existing pages and better understand your site structure.

11. How to Use AgentSEO

Once your setup is complete, you can start using AgentSEO to manage your content and SEO.

The Dashboard

The Dashboard is your command center. It provides an overview of:

• Analytics: High-level metrics on your site's performance.
• Recent Posts: Quick access to your latest published or drafted articles.
• Agent Activity Logs: See what your autonomous agents are currently working on in the background.

The Blog Writer (/blog-writer)

The Blog Writer allows you to manually initiate a new post generation.

• Generate a Post: Input a topic or keyword to start drafting.
• Product Evangelist Mode: Check this box to ensure the AI weaves your products (from the Knowledge Base) into the article.
• Target Word Count: Specify how long the article should be.
• Revision & Regeneration Dialog: Once a draft is ready, use the dialog to request revisions or regenerate sections until it's perfect.

The Content Calendar & Ideas (/calendar)

Manage your publishing schedule and discover new topics.

• AI Ideas Tab: The Trend Agent continuously scours the web for trending topics in your niche and populates this tab with fresh, unscheduled content ideas.
• Schedule Posts: Review AI ideas and drag them onto the calendar to schedule them for autonomous drafting and publishing.

The Media Hub (/image-generator)

Manage all visual assets for your articles.

• Generate AI Images: Use the configured Image Model to create custom artwork.
• Search Stock Photos: Search through Pixabay and Freepik (if configured) directly within the app.
• Upload Local Files: Upload your own images.
• Insert into Drafts: Easily select any image from the Media Hub to insert into your blog drafts.

12. Smart Copilot Setup (WhatsApp & Telegram)

Control your AI agents from your phone by setting up the Smart Copilot under Settings > Copilot.

Setting up a Telegram Bot

1. Open Telegram and search for @BotFather (the official Telegram bot creator).
2. Send the command /newbot.
3. Follow the prompts to choose a name and a username (must end in "bot") for your bot.
4. BotFather will give you a Bot Token (e.g., 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
5. Paste this token into the Telegram configuration in AgentSEO to enable the connection.

Setting up WhatsApp Cloud API

1. Go to the Meta for Developers website and log in.
2. Click Create App, select Other then click next, and select Business, and follow the prompts to create the app. In the use cases section, make sure to choose Set up WhatsApp integration as shown in the image below.
   
3. After creating the app, you will be taken to the app dashboard. Find the Connect with customers through WhatsApp use case and click Customize.
   
4. Follow the setup to associate a Meta Business Account.
5. Navigate to WhatsApp > API Setup in the left sidebar.
6. Here you will find your Temporary Access Token (note: temporary token lasts up to 24 hours, but test numbers can last up to 90 days. For production, you will need to generate a permanent system token in Business Settings), Phone Number ID, and WhatsApp Business Account ID.
   Important: If you are using a test number, you must whitelist the phone numbers that will be interacting with it (e.g., adding them as test numbers in the API Setup page). Enter these details into AgentSEO.
   
7. You will also need to configure the Webhook in the Meta dashboard using the URL provided in the AgentSEO Copilot settings to receive messages.

13. Cron Jobs (Background Tasks)

AgentSEO relies on background tasks to process autonomous agents, generate content, and publish schedules. You must set up a cron job on your server to trigger these processes.

Your server needs to make a GET request to the following endpoint every minute:

Security Header

To prevent unauthorized triggers, you must pass the CRON_SECRET you defined in your environment variables as an Authorization header: Authorization: Bearer YOUR_CRON_SECRET

Example: cPanel Cron Job

In cPanel, go to Cron Jobs. Set the schedule to Once Per Minute (* * * * *) and use the following command (replace with your domain and secret):

curl -H "Authorization: Bearer YOUR_CRON_SECRET" https://yourdomain.com/api/cron/process-agents >/dev/null 2>&1

Example: Linux crontab (VPS)

Run crontab -e and add the following line:

* * * * * curl -H "Authorization: Bearer YOUR_CRON_SECRET" https://yourdomain.com/api/cron/process-agents >/dev/null 2>&1

14. Autonomous Agents & AI Tools

AgentSEO is powered by an ecosystem of specialized AI agents and tools that work together to manage your content pipeline, from ideation to publishing.

The Autonomous Agents

In the Agents tab (/agents), you can monitor and manage the core workers driving the platform. Each agent serves a distinct purpose in your SEO workflow:

• System Executive Agent: The "manager" agent. It orchestrates all background jobs, assigns tasks to other agents, and ensures the content pipeline runs smoothly without user intervention.
• SEO Analyzer Agent: Continuously monitors your connected integrations (like Google Analytics and Search Console) and your published posts to provide actionable SEO insights and health scores.
• Trend & Ideation Agent: Scours the web (using Reddit and Serper APIs) to identify trending topics in your niche. It automatically populates your "AI Ideas" tab in the content calendar with fresh, relevant concepts.
• Content Drafting Agent: The heavy lifter. It takes topics from your calendar or direct requests, conducts SERP research, forms an outline, and drafts the full article while adhering to your Brand Voice and Knowledge Base.
• Publishing Agent: Handles the final step. It takes "Review Ready" or approved drafts and pushes them to your connected platforms (WordPress or Webhooks) according to your calendar schedule.
• Custom Agents: AgentSEO allows you to create your own custom agents tailored to your specific needs. You can define their trigger conditions, schedules, and custom prompts to automate unique workflows.

The Smart Copilot Tools (Internal & External)

The Copilot acts as your Digital Chief of Staff. It's accessible via the web dashboard chat, or externally via WhatsApp and Telegram. It utilizes a vast array of tools to execute your commands:

Content Tools

• Blog Post Generator: Instantly drafts complete articles based on a simple prompt or topic.
• Research Assistant: Conducts deep dives into specific subjects, providing summaries and key data points.
• On-Page SEO Analyzer: Evaluates existing drafts or published content and suggests optimizations (keywords, meta tags, readability).
• Repurpose Content: Takes existing content (or URLs) and transforms it into different formats (e.g., summarizing an article into social media posts).
• AI Image Generation: Creates custom featured images or in-line graphics for your content.
• Keyword Research: Identifies high-value keywords, search volumes, and competition levels.
• Competitor Analysis: Scrapes and analyzes competitor URLs to find content gaps and ranking opportunities.
• Knowledge Base Retrieval: Interrogates your uploaded business data (PDFs, text) to provide accurate, company-specific answers.

System & Automation Tools

• Google Search (Serper): Performs live web searches to ground responses in real-time data.
• Calendar Management: Retrieves your content schedule and allows you to schedule new posts directly via chat.
• Agent Control: Lists active agents and allows you to manually trigger them (e.g., "Run the SEO Analyzer now").
• Performance Stats: Fetches high-level analytics from your dashboard.

Use Cases

• On-the-go Management: Send a WhatsApp message to your bot: "Draft an article about the latest SEO trends and schedule it for next Friday." The Copilot uses the blogPostGeneratorTool and schedulePostTool seamlessly.
• Competitive Intelligence: Ask the web chat: "Analyze this competitor URL [link] and suggest a better outline." The Copilot uses the competitorAnalysisTool and researchAssistantTool.
• Instant Insights: Message via Telegram: "How is my site performing this week?" The Copilot uses the getPerformanceStatsTool.