aeo-agent

# Superlines AEO Agent > **🚧 Work in Progress** — This project works locally and is under active development. Automated deployment (GitHub Actions, cron) is coming soon. Expect breaking changes. An AI-powered content intelligence and optimization agent that runs a daily 7-phase pipeline for [AI Search Engine Optimization (AEO/GEO)](https://www.superlines.io/glossary/answer-engine-optimization). Built with [Mastra](https://mastra.ai), [Superlines MCP](https://docs.superlines.io/mcp/overview), [Bright Data MCP](https://docs.brightdata.com/scraping-automation/mcp), and [Sanity CMS](https://www.sanity.io). **[Full step-by-step cookbook →](https://www.superlines.io/cookbook/agentic-aeo-content-pipeline)** ## What It Does The agent runs 7 phases daily using 3 specialized AI agents: | Phase | Agent | What It Does | |-------|-------|-------------| | 1. Intelligence Gathering | Analyst | Reads Superlines AI search data: brand visibility, citations, competitive gaps, content opportunities | | 2. Competitive Deep Dive | Analyst + Researcher | Identifies top competitor URLs winning AI citations, scrapes and analyzes their content | | 3. Content Health Audit | Content Manager | Scans existing Sanity articles for outdated content, flags articles needing updates | | 4. Fact Check | Content Manager + Researcher | Extracts pricing/stats claims from articles, verifies against live sources | | 5. Industry Insights | Researcher | Searches for trending topics, Reddit discussions, industry reports | | 6. Data Storytelling | Analyst | Finds interesting patterns in analytics data to embed in articles | | 7. Content Actions | Content Manager | Creates new article drafts, updates existing articles, fixes incorrect facts | ## Architecture ``` ┌──────────────────────────────────────────────────────┐ │ Daily Pipeline │ │ │ │ ┌─────────┐ ┌────────────┐ ┌──────────────────┐ │ │ │ Analyst │ │ Researcher │ │ Content Manager │ │ │ │ Agent │ │ Agent │ │ Agent │ │ │ └────┬─────┘ └─────┬──────┘ └────────┬─────────┘ │ │ │ │ │ │ │ ┌────┴──────────────┴───────────────────┴─────────┐ │ │ │ Shared Memory (LibSQL) │ │ │ │ - Message History - Working Memory │ │ │ │ - Thread Isolation - Cross-run Persistence │ │ │ └──────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────┘ │ │ │ ┌────┴────┐ ┌──────┴──────┐ ┌────┴─────┐ │Superlines│ │ Bright Data │ │ Sanity │ │ MCP(SSE) │ │ MCP (SSE) │ │ CMS │ └──────────┘ └─────────────┘ └──────────┘ ``` **Tech Stack:** - **[Mastra](https://mastra.ai)** — TypeScript AI agent framework with MCP, memory, and multi-step tool calling - **[Superlines MCP](https://docs.superlines.io/mcp/overview)** — 32 AI search analytics tools (brand visibility, citations, competitive gaps, webpage audit) - **[Bright Data MCP](https://docs.brightdata.com/scraping-automation/mcp)** — Web scraping and search tools for competitor research and fact-checking - **[Sanity CMS](https://www.sanity.io)** — Headless CMS for reading and writing articles - **[LibSQL](https://turso.tech/libsql)** — Persistent memory storage (local SQLite or Turso remote) ## Quick Start ### Prerequisites - **Node.js 22.13+** - **[Superlines](https://www.superlines.io) account** (Starter plan or above) with an API key - **[Anthropic](https://console.anthropic.com) API key** for Claude - **[OpenAI](https://platform.openai.com) API key** for embeddings - **[Bright Data](https://brightdata.com) API token** (free tier: 5,000 requests/month) - **[Sanity](https://www.sanity.io) project** with a write token ### 1. Clone and install ```bash git clone https://github.com/Superlines/aeo-agent.git cd aeo-agent npm install ``` ### 2. Configure environment ```bash cp .env.example .env # Edit .env with your API keys ``` See `.env.example` for all available configuration options. ### 3. Run the pipeline ```bash npm start ``` The pipeline takes 5-15 minutes depending on article count and content actions. Reports are saved to `data/reports/`. ## File Structure ``` aeo-agent/ ├── src/ │ ├── index.ts # Entry point, env validation │ ├── pipeline.ts # 7-phase pipeline orchestrator │ ├── report.ts # Report generator (markdown, Slack) │ ├── mastra/ │ │ ├── index.ts # Mastra initialization (singleton) │ │ ├── agents.ts # 3 agent definitions with specialized instructions │ │ ├── mcp.ts # MCP client setup (Superlines + Bright Data) │ │ ├── memory.ts # Memory config (LibSQL, working memory) │ │ └── tools/ │ │ └── sanity.ts # Sanity CMS tools (list, get, create, update, fact-check) │ └── utils/ │ ├── sanity-client.ts # Sanity API client + GROQ queries │ ├── fact-check.ts # Claim extraction (pricing, stats, features, dates) │ └── markdown-to-portable-text.ts # Markdown → Sanity Portable Text converter ├── data/ # Runtime data (memory DB, reports) ├── .env.example # Environment variable template ├── package.json ├── tsconfig.json └── README.md ``` ## Key Design Decisions **Why 3 agents instead of 1?** Loading all MCP tools from both Superlines (32 tools) and Bright Data (8+ tools) into a single agent pushes the combined tool schemas past Claude's 200k token context limit. Splitting by role keeps each agent's context manageable. **Why disable semantic recall?** Previous pipeline runs contain large MCP tool responses (100k+ tokens). When semantic recall re-injects these into future conversations, they blow past the context limit. Working memory provides a compact structured alternative. **Why thread-per-phase?** Each pipeline phase writes to its own memory thread. This prevents tool results from Phase 1 from crowding Phase 7's context window. **Why draft-only?** All new articles are created with `draft=true`. The agent never publishes directly. A human reviews every article in Sanity Studio before publishing. ## Cost Estimates | Component | Cost per run | |-----------|-------------| | Claude Sonnet 4 | ~$0.50-2 | | Claude Opus 4 | ~$1-4 | | Superlines MCP | Included with plan | | Bright Data MCP | Free tier (5k req/mo) | | Sanity CMS | Free tier | | **Daily total (Sonnet)** | **~$0.50-2** | | **Daily total (Opus)** | **~$1-4** | Roughly **$15-120/month** for daily runs depending on model choice. ## Safety - All new articles created as **drafts** — never auto-published - Superlines MCP tools are **read-only** — they never modify your analytics account - Content updates only change specific fields — never deletes content - Full audit trail in memory database ## Status | Feature | Status | |---------|--------| | Local pipeline execution | ✅ Works | | 7-phase daily pipeline | ✅ Works | | Superlines MCP integration | ✅ Works | | Bright Data MCP integration | ✅ Works | | Sanity CMS read/write | ✅ Works | | Fact-checking pipeline | ✅ Works | | Report generation (markdown) | ✅ Works | | Slack notifications | ✅ Works | | GitHub Actions deployment | 🚧 Coming soon | | Vercel deploy hook | ✅ Works | | Remote memory (Turso) | ✅ Works | ## Related - **[Cookbook: Build an Agentic AEO Content Pipeline](https://www.superlines.io/cookbook/agentic-aeo-content-pipeline)** — Step-by-step guide - **[Superlines MCP Documentation](https://docs.superlines.io/mcp/overview)** — Setup and tools reference - **[Mastra Documentation](https://mastra.ai/docs)** — Agent framework reference - **[Bright Data MCP](https://docs.brightdata.com/scraping-automation/mcp)** — Web scraping MCP server ## License MIT