SEO Master Agent: An Autonomous Multi-LLM SEO Manager for Five Workflows
TL;DR: The SEO Master Agent is an open-source system that runs five SEO workflows — on-page optimization, off-page link-building prospecting, Google Business Profile copy, content repurposing, and geo/programmatic SEO — through a single multi-LLM gateway (OpenAI, Anthropic, Gemini, GLM, local Ollama). It's a FastAPI backend with a Next.js frontend, async background jobs, per-task system prompts that force structured JSON output, API-key auth, an SSRF guard, and a smoke test that boots its own server to verify everything. We read the code to verify. It's working, self-hostable software. Two honest caveats: "rank tracking" appears in the repo description but isn't in the current task set, and the GMB workflow generates copy — it doesn't post to Google for you.
The problem: SEO is five jobs, not one
Ask what "doing SEO" means and you get five different jobs: fixing on-page elements (titles, meta descriptions, headings), prospecting link-building targets and writing outreach, managing the Google Business Profile, repurposing content across social platforms, and writing geo-targeted landing pages for every city you serve. Agencies charge monthly retainers for this bundle because it's genuinely labor-intensive.
The SEO Master Agent (github.com/Shivay00001/seo-master-agent) treats those five jobs as five task types behind one API, with an LLM doing the drafting and the code handling routing, safety, and structure. It's the sibling of the Website Optimizer Agent — same FastAPI + Next.js skeleton, same security posture — pointed at ongoing SEO work instead of one-shot audits.
The five workflows
| Task type | What you give it | What you get back (structured JSON) |
|---|---|---|
onpage | URL + target keyword | Optimized title, meta description, H1 suggestion, keyword-density analysis, content recommendations |
offpage | Niche | Target domain types to prospect, outreach email subject + body, follow-up email |
gmb | Business name + services | Optimized business description, 5 Q&A pairs, 3 update posts |
content | Blog URL | Twitter thread, LinkedIn article, Facebook post — repurposed for semantic search |
geo | City + service | Geo title, meta description, local landmarks to mention, 2 paragraphs of localized body copy |
Each task type has required inputs enforced by the API (REQUIRED_INPUTS in backend/server.py) — submit a geo task without a city and you get a 422, not a hallucinated guess.
How it works: prompts as contracts
The most interesting design decision is in get_system_prompt(): every task type gets a system prompt that forces the LLM to output only a raw JSON object with fixed keys — no markdown fences. The on-page prompt demands exactly optimized_title, optimized_meta_description, h1_suggestion, keyword_density_analysis, and content_recommendations. The geo prompt demands geo_title, geo_meta_description, local_landmarks_to_mention, and localized_body_copy. This turns the LLM from a chatbot into a function with a typed return value — the downstream code (and your client deliverables) can rely on the shape of the output.
Around that core:
- Multi-LLM gateway.
resolve_llm_config()routes by model prefix —gpt,claude,gemini,zhipu/glm,ollama— through LiteLLM. Provider credentials resolve per-request headers first (X-OpenAI-Key,X-Anthropic-Key,X-Gemini-Key,X-GLM-Key), env vars as fallback, and are used in-memory only, never persisted. One honest caveat in the code:POST /api/settings/keysstores keys in the local SQLite DB as a self-host convenience — the README flags it as not-a-secrets-manager and recommends env vars in production. - Async jobs.
POST /api/executeenqueues the job (202 +task_id); a background worker runs the LLM call and updates theExecutionLogthroughpending → running → success/error;GET /api/tasks/{task_id}returns status plus the result JSON. - SSRF guard.
is_private_url()refuses non-http(s)schemes and any host resolving to private/loopback IPs before the website fetcher touches it — the same protection as its sibling project. - Auth that fails closed. All
/api/*endpoints requireX-API-Key(constant-time compare); the server refuses to boot withoutSEO_API_KEYset. Errors are structured JSON — never stack traces.
The smoke test boots its own server
tests/smoke_test.py is better than most: it spawns uvicorn itself on port 18099 with a hermetic environment (only SEO_API_KEY plus dummy values, inherited LLM keys stripped out), waits for /health, then asserts the full contract — 401 without the key, 422 on bad task types/missing inputs/bad URLs, a valid execute returning task_id, task status retrieval, and structured error bodies with no stack traces. Exit code 0 means pass. Run it with python tests/smoke_test.py — no manual setup.
How to run it
Backend:
cp .env.example .env
# generate a secret: python -c "import secrets; print(secrets.token_hex(32))"
# set SEO_API_KEY in .env to it
pip install -r backend/requirements.txt
uvicorn backend.server:app --host 0.0.0.0 --port 8000
# health: curl localhost:8000/health → {"status":"ok"}Run a task:
curl -X POST localhost:8000/api/execute \
-H "Content-Type: application/json" -H "X-API-Key: $SEO_API_KEY" \
-d '{"task_type":"geo","inputs":{"city":"Chennai","service":"Dentist"},"model_id":"gpt-4o"}'
# -> {"status":"success","task_id":"..."}
curl -H "X-API-Key: $SEO_API_KEY" localhost:8000/api/tasks/<task_id>Frontend: cd frontend && cp .env.example .env.local (set NEXT_PUBLIC_API_URL), npm install && npm run dev. A Dockerfile and Render deployment steps are included.
The API contract, end to end
The full request lifecycle is worth spelling out because it's the whole product:
POST /api/executewith{"task_type":"onpage","inputs":{"url":"https://…","keyword":"…"},"model_id":"gpt-4o"}. Auth viaX-API-Key; optionalX-OpenAI-Keyetc. for per-request provider keys.- Validation: task type must be one of the five, required inputs must be present, URLs must be
http(s), model prefix must be recognized. Failures return 422 with field-level details. - The job is enqueued with a
task_id; the response returns immediately. - A background worker fetches the target site (for
onpageandcontenttasks), builds the task-specific system prompt, calls the LLM via LiteLLM, and stores the structured JSON result. GET /api/tasks/{task_id}returnspending,running,success(with the result), orerror(with a structured code, never a stack trace).
The Next.js frontend wraps this in a dashboard: pick a task type, fill the inputs, choose a model, watch the job progress, and read the structured result. Because every task returns fixed-shape JSON, the frontend can render each workflow's output as proper UI — titles in title fields, Q&A pairs as cards — instead of dumping a chat transcript.
A shared engineering lineage
Readers of the Website Optimizer Agent showcase will recognize the skeleton: same FastAPI + Next.js split, same X-API-Key auth with constant-time comparison, same SSRF guard on the website fetcher, same per-request LLM keys that are never stored, same async job lifecycle. The two repos are clearly built from one hardened template, and it shows in the consistency — the security model you audit once applies twice. What differs is the product surface: one-shot audits versus five ongoing SEO workflows, and the prompt-as-contract pattern that turns the LLM into a typed function. If you adopt one, adopting the other is nearly free.
Honest status and roadmap
| Aspect | Status |
|---|---|
| Five SEO workflows | Working — on-page, off-page, GMB copy, content repurposing, geo SEO |
| Multi-LLM gateway | Working — 5 providers incl. local Ollama; per-request keys never stored |
| Security + tests | Working — SSRF guard, fail-closed auth, self-booting smoke test |
| Rank tracking | Not in the current build — it's in the repo description, but the task set has no rank-tracking workflow yet |
| GMB "updates" | Generates the copy (descriptions, Q&A, posts) — does not post to Google automatically |
| Deployment | Not deployed — Docker/Render ready, needs a host + LLM key |
The honest read: this is a working multi-workflow SEO engine with genuinely good prompt-as-contract design and a test suite that verifies its own security claims. The two caveats above aren't hidden — they're the difference between reading the description and reading the code, which is exactly what we did. If you're an SEO freelancer, the geo task alone (city + service → full localized landing copy with landmarks) is a deliverable generator. The roadmap writes itself: rank tracking to match the description, scheduled recurring tasks, and report exports.
Who this is for
SEO freelancers get the clearest win: the five workflows map directly to line items on a client invoice — on-page optimization, outreach prospecting, GBP copy, content repurposing, local landing pages. Generate the drafts with the agent, review and refine, deliver. Small agencies can productize it: a fixed-price "SEO starter pack" where the agent does the drafting and humans do QA. Multi-location businesses (clinics, franchises, real-estate groups) can generate a localized landing page per city with the geo task instead of paying a copywriter per location.
The boundary to respect: this drafts, it doesn't publish. That's a deliberate safety property, not a missing feature — auto-publishing AI-generated outreach emails or GBP updates would be a reputation incident waiting to happen. The human review step is the product working as designed.
Frequently asked questions
Does it really work autonomously?
It runs the five workflows end-to-end: you submit a task type with inputs, it calls the LLM with a structured-output contract, and returns typed JSON. A human should still review AI-generated copy before publishing — it's a manager that drafts, not one that publishes.
Which AI models are supported?
OpenAI, Anthropic, Google Gemini, Zhipu GLM, and local Ollama models — routed by model prefix through LiteLLM. You can even mix providers per request.
Are my API keys safe?
Per-request LLM keys are used in-memory only and never persisted. The server refuses to boot without its own SEO_API_KEY. (One exception: the optional settings endpoint stores keys in local SQLite for self-host convenience — use env vars in production.)
Does it post to my Google Business Profile automatically?
No — the GMB workflow generates optimized descriptions, Q&A pairs, and update posts as copy. Publishing to Google is still done by you, which is the safe default.
The bottom line
The SEO Master Agent compresses five retainer-priced workflows into one self-hosted API with structured, reliable output. The prompt-as-contract pattern — forcing raw JSON with fixed keys per task — is the kind of design detail that separates a demo from a tool. The code is public at github.com/Shivay00001/seo-master-agent: run the smoke test, then fire a geo task at your own city and service and judge the copy yourself.
Want SEO automation for your business? VisionQuantech builds custom SEO systems, content pipelines, and AI agents for SMBs — with working demos before you pay anything. Contact: [email protected]