SEO Research Agent

Conversational SEO research assistant powered by OpenAI and SerpApi. The agent conducts keyword research, SERP analysis, ranking checks, and topical news discovery. It works iteratively — planning, calling tools, and refining results — before producing a structured SEO Report in Markdown.

Includes both an interactive CLI chat mode and a Python class API.

Features

• Multi-tool integration via SerpApi:

  • search_web: Google Search (organic results, snippets, competitors).
  • search_autocomplete: Google Autocomplete keyword suggestions.
  • search_news: Google News for topical trends.
  • check_rank: Ranking position of a domain for given keywords.

• Iterative research loop: plan → execute tool calls → refine → report.

• Generates full SEO Reports in Markdown:

  • Keyword opportunities
  • SERP insights
  • Domain ranking positions
  • News & topical opportunities

• Chat-style CLI (type queries, get structured reports).

• Optional JSON trace (--outfile) with step-by-step logs.

Requirements

• Python 3.9+ (3.10+ recommended)

• Environment variables:

  • OPENAI_API_KEY
  • SERPAPI_API_KEY

Install

git clone https://github.com/serpapi/seo-research-agent
cd seo-research-agent
pip install -r requirements.txt

Setup API keys

Option A — export in your shell:

export OPENAI_API_KEY="sk-..."
export SERPAPI_API_KEY="..."

Option B — .env file:

# .env
export OPENAI_API_KEY="sk-..."
export SERPAPI_API_KEY="..."
source .env

⚠️ Never commit or share your keys.

Quick start

Single-query mode:

python seo_agent.py -q "SEO analysis for serpapi.com"

Interactive chat mode:

python seo_agent.py

Exit with exit, quit, or Ctrl+C.

Save JSON trace:

python seo_agent.py -q "SEO opportunities for AI startups" --outfile trace.json

CLI Usage

python seo_agent.py -h

usage: seo_agent.py [-h] [-q QUERY] [-m {o3,o3-mini,o4-mini,gpt-4o}]
                    [-n TOPN] [-o OUTFILE] [-d]

SEO Research Agent CLI

options:
  -q, --query        Initial query (omit for chat mode)
  -m, --model        Model: gpt-4o (default) | o3 | o3-mini | o4-mini
  -n, --topn         Organic results per search (default: 10)
  -o, --outfile      Save JSON trace to file
  -d, --debug        Enable debug logs

How it works

1. Planning phase — model writes a research plan.
2. Execution phase — agent batches SerpApi calls (search_web, search_autocomplete, search_news, check_rank).
3. Iteration phase — if results are incomplete, the model loops back with new queries.
4. Reporting phase — generates a polished SEO Report in Markdown.

Example

python seo_agent.py -q "SEO analysis for serpapi.com" --debug

Sample Markdown output (truncated):

# SEO Report for serpapi.com

## Keyword Opportunities
- serpapi python tutorial
- serpapi google trends
- serpapi vs competitors
- ...

## SERP Insights
- Competitor: apify.com — web scraping & automation [Source]
- Competitor: brightdata.com — data APIs & scrapers [Source]

## Domain Ranking
- serpapi.com ranks #1 for "google serp api"
- serpapi.com ranks #4 for "seo data api"
- serpapi.com not in top 50 for "keyword research api"

## News & Topical Opportunities
- "AI agents using SerpApi for automation" [Source]
- "Search API usage growth in SEO workflows" [Source]

## Recommendations
- Create content around **AI agents** + SEO APIs
- Target long-tail keywords: "python serpapi tutorial", "google trends api serpapi"
- Improve rankings for mid-tail queries like "seo data api"

Programmatic use

from seo_agent import SEOResearchAgent

agent = SEOResearchAgent(model="gpt-4o", topn=10)
result = agent.ask("SEO analysis for serpapi.com")
print(result["answer"])  # final Markdown SEO report

JSON trace example

{
  "question": "SEO analysis for serpapi.com",
  "answer": "... full SEO report ...",
  "steps": [
    { "type": "tool_call", "tool": "search_autocomplete", "query": "serpapi" },
    { "type": "tool_result", "content": "- serpapi python\n- serpapi google trends" },
    { "type": "assistant_answer", "content": "... report ..." }
  ]
}

Troubleshooting

• "OPENAI_API_KEY and SERPAPI_API_KEY must be set." → Export both keys.
• Empty results → check SerpApi key/quota.
• Model errors → try switching to gpt-4o.

License

MIT License — see LICENSE.