SEO Agent

AI-powered SEO auditor built with Vercel AI SDK v6. Continuously monitors websites, identifies SEO issues, tracks keyword rankings, and measures visibility in AI-powered search engines. Automatically fixes what it can (via GitHub PRs) and reports what requires manual intervention.

Problem

Traditional SEO tools give you dashboards full of data but leave you to figure out what to do. This agent does the full workflow: audit, analyze, generate fixes, create PRs, and write reports — all from a single conversational interface.

Architecture

┌─────────────────────────────────────────────────┐
│                   Next.js App                    │
│                                                  │
│  ┌──────────┐    ┌──────────────────────────┐   │
│  │  Chat UI  │◄──►│  /api/chat (Route Handler) │  │
│  │ (useChat) │    │                          │   │
│  └──────────┘    └──────────┬───────────────┘   │
│                              │                   │
│                   ┌──────────▼───────────┐      │
│                   │   ToolLoopAgent       │      │
│                   │   (Claude Sonnet 4)   │      │
│                   └──────────┬───────────┘      │
│                              │                   │
│         ┌────────────────────┼──────────────┐   │
│         ▼                    ▼              ▼   │
│  ┌────────────┐   ┌──────────────┐  ┌────────┐ │
│  │ 38 SEO     │   │  GitHub PR   │  │ Report │ │
│  │ Tools      │   │  Creation    │  │ Writer │ │
│  └────────────┘   └─────────────┘   └────────┘ │
└─────────────────────────────────────────────────┘

Agent Loop

The agent uses Vercel AI SDK's ToolLoopAgent pattern. Given a user prompt, the LLM autonomously decides which tools to call and in what order. A "full audit" triggers all tools. A focused "check Core Web Vitals" only runs the relevant subset.

Tools (38 total)

Category	Tools	External API
Data Collection	querySearchConsole, queryAnalytics, queryBacklinks, inspectUrl, checkSitemapStatus	Google Search Console, GA4, DataForSEO
Auditing	deepAuditPage, crawlSite, measureCoreWebVitals, auditSecurityHeaders, crossPageHreflangAudit, auditEEAT	PageSpeed Insights
Analysis	detectCannibalization, analyzeContentGaps, analyzeCompetitorSERP, detectContentDecay, identifyContentToPrune	None
Content	optimizePageContent, generateMissingContent, optimizeForSERPFeatures, generateAltTexts, researchKeywords, planContent	AI model
Linking	suggestInternalLinks, findUnlinkedMentions, deepBacklinkAnalysis, findLinkBuildingTargets, scrapeCompetitorSitemaps	DataForSEO
Topic Strategy	buildTopicClusterMap, trendingTopics, monitorCompetitorChanges	DataForSEO
Action	generateCodeFix, createGitHubPR, autoRefreshDecayingContent, draftOutreach, notifyTeam, verifyDeployedFix	GitHub API
Reporting	writeReport, generateDashboard	None

Configuration

Copy .env.example to .env.local and fill in your values:

cp .env.example .env.local

Required Environment Variables

Variable	Description	Example
ANTHROPIC_API_KEY	Anthropic API key for the agent model	sk-ant-...
SITE_URL	Your website URL	https://mystore.com
GSC_*	Google Search Console OAuth credentials	See .env.example

Recommended Environment Variables

Variable	Description	Example
COMPANY_NAME	Your company/brand name (used in prompts, outreach)	Acme Electronics
INDUSTRY_CONTEXT	Your industry (helps the agent understand your domain)	e-commerce electronics
GITHUB_REPO	GitHub repo for PR creation (owner/repo format)	acme/website
GITHUB_TOKEN	GitHub PAT with repo scope	ghp_...
GITHUB_BASE_BRANCH	Branch to create PRs against (default: main)	develop
TARGET_KEYWORDS	Comma-separated target keywords	best laptops, gaming PC
COMPETITORS	Comma-separated competitor domains	bestbuy.com, newegg.com
CONTACT_NAME	Name for outreach email signatures	Jane Smith
DISCORD_WEBHOOK_URL	Discord webhook for notifications	https://discord.com/api/webhooks/...

Optional Environment Variables

Variable	Description
GA4_PROPERTY_ID	Google Analytics 4 property ID
DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD	DataForSEO API credentials
SLACK_WEBHOOK_URL	Slack webhook for notifications
RESEND_API_KEY / NOTIFY_EMAIL	Email notifications via Resend
SMARTLEAD_API_KEY	Smartlead for outreach campaigns

Configuration Examples

E-commerce electronics store:

COMPANY_NAME=TechShop
SITE_URL=https://techshop.com
INDUSTRY_CONTEXT=e-commerce consumer electronics
TARGET_KEYWORDS=best laptops 2026, gaming monitors, wireless headphones
COMPETITORS=bestbuy.com, newegg.com, amazon.com

SaaS company:

COMPANY_NAME=DataFlow
SITE_URL=https://dataflow.io
INDUSTRY_CONTEXT=B2B SaaS data analytics platform
TARGET_KEYWORDS=data analytics platform, business intelligence tool, ETL pipeline
COMPETITORS=tableau.com, looker.com, metabase.com

Local business:

COMPANY_NAME=Green Leaf Dental
SITE_URL=https://greenleafdental.com
INDUSTRY_CONTEXT=dental practice, local healthcare
TARGET_KEYWORDS=dentist near me, teeth whitening, dental implants
COMPETITORS=aspendentalcom, 1800dentist.com

Tech Stack

• Vercel AI SDK v6 — ToolLoopAgent, createAgentUIStreamResponse, typed tool parts
• Next.js (App Router) — Server Components, Route Handlers, streaming
• TypeScript — End-to-end type safety
• Cheerio — Server-side HTML parsing for SEO analysis
• Tailwind CSS — UI styling

Quick Start

npm install
cp .env.example .env.local
# Fill in your API keys and site configuration
npm run dev

Open http://localhost:3000 and use the quick actions or type a custom prompt.

Usage Examples

Full website audit:

"Run a comprehensive SEO audit on my site. Crawl sitemap, check keyword rankings, measure Core Web Vitals, detect cannibalization. Generate fixes and create a PR."

Content decay detection:

"Find pages losing rankings over the past 28 days. Show position drops and generate refresh recommendations."

Competitor analysis:

"Who ranks for my target keywords? Audit the top 3 competitors and compare their SEO against my site."

Link building:

"Find unlinked mentions of my brand. Draft outreach emails for the top 10 opportunities."

Cron Jobs

Three cron endpoints for automated monitoring:

Schedule	Endpoint	Purpose
Daily	/api/cron/daily-check	Quick health check, critical issue alerts
Weekly	/api/cron/weekly-audit	Full audit with report and PR
Monthly	/api/cron/monthly-strategy	Strategic analysis, content planning

Set CRON_SECRET in your environment and configure cron triggers in your deployment platform.

Key Design Decisions

1. Agent over pipeline — The LLM decides which tools to use based on the request, handling edge cases gracefully.
2. Typed tool parts — InferAgentUIMessage provides compile-time type safety from agent definition to UI rendering.
3. Reports on disk — Markdown files for simplicity and portability. Can be tracked in git and diffed over time.
4. Configurable via env vars — No code changes needed to use with any website or industry.

License

MIT