The SEO/AEO Research Agent is a Claude Code subagent that pulls real keyword and SERP data through Perplexity and Firecrawl MCP servers, then adds Answer Engine Optimization analysis showing how to get cited by ChatGPT, Claude, and Perplexity, not just ranked on Google. It runs as the command /seo-research and finishes in under a minute.
What you will be able to do
- Build the seo-aeo-researcher.md agent file with the exact YAML frontmatter and tool list the article specifies.
- Run /seo-research
(or --topic "your topic") to generate keyword, SERP, and AEO data in 30-60 seconds. - Identify competitor content gaps and AEO citation opportunities the agent surfaces automatically.
- Control Perplexity API cost by batching queries to a maximum of two calls per research run.
- Read the structured JSON and markdown research output saved under research-outputs/by-post/{post_id}/.
Before you start
- Claude Code CLI installed (npm install -g @anthropic-ai/claude-code) with Node.js present (check: node --version).
- MCP servers for Perplexity and Firecrawl configured in Claude Code, with free API keys from perplexity.ai/api and firecrawl.dev.
- The .claude/agents/ folder structure and research profile files (business-context.md, content-strategy.md) set up per Articles 1 and 2 of this series.
Reference
| Setting | Value |
|---|---|
| Command | /seo-research <post_id> or /seo-research --topic "your topic" |
| Agent file | .claude/agents/seo-aeo-researcher.md |
| Model | sonnet |
| Tools granted | Read, Glob, Grep, Write, mcp__perplexity__search, mcp__perplexity__reason, mcp__firecrawl__firecrawl_scrape, mcp__firecrawl__firecrawl_search |
| JSON output | .claude/research-outputs/by-post/{post_id}/seo-research.json |
| Markdown output | .claude/research-outputs/by-post/{post_id}/seo-research.md |
| Cost rule | Maximum 2 Perplexity calls per run: 1 search call, 1 reason call |
| Cost result | Batching cut cost per research from about $0.85 to about $0.25 |
Common errors and fixes
| What goes wrong | The fix |
|---|---|
| Using an LLM to imagine keyword data hallucinates search volumes and guesses at competition levels | Use Perplexity MCP for real search data and Firecrawl MCP to scrape actual SERP results instead of LLM guesses |
| Initial agent version made 6+ separate Perplexity calls per research run, costing about $0.85 each | Batch all keyword queries into one comprehensive Perplexity search call, cutting cost 70% to about $0.25 |
| Using mcp__perplexity__reason for routine queries is expensive, one reason call costs as much as 3-5 search calls | Reserve reason calls for the final AEO synthesis only, use search for keyword data |
| Optimizing only for Google while ChatGPT, Perplexity, and Claude now answer questions directly | Add an AEO analysis step so content is structured for AI citation, with tables, specific data, and clear definitions |
Read the full walkthrough
The complete lesson, with screenshots and any downloads, is published on Substack as part of PubFlow OS Agents: Build Your AI Research Team.
More in this section
Continue the course
Browse all lessons in the PubFlow OS Agents: Build Your AI Research Team course, or subscribe to the GenAI Unplugged newsletter to get new lessons in your inbox.
