What Are the AI Agents in OpenSEO Used For? Technical Capabilities Explained

The AI agents in OpenSEO serve as specialized digital SEO assistants that automate keyword research, site audit analysis, backlink tracking, and user onboarding through persistent Durable Objects integrated directly into the OpenSEO backend.

These agents operate as "stateful microservices" inside the every-app/open-seo repository, leveraging the Cloudflare Agents SDK to maintain conversation context across sessions. Unlike simple chatbots, they execute domain-specific SEO operations—reading Google Search Console data, parsing site audit reports, and managing project memory—without consuming user credits for basic read operations.

Core SEO Functions of OpenSEO AI Agents

Onboarding and User Guidance

The SAM (Search Assistant Model) onboarding agent handles first-time user experiences. Located in src/server/features/onboarding/OnboardingChatAgent.ts, this agent introduces itself as "Sam" and steers new users toward appropriate UI flows. It explains platform capabilities and gathers initial project requirements, reducing friction in the signup process.

Keyword Research and Competitive Analysis

The primary SAM chat agent defined in src/server/features/sam/samSystemPrompt.ts functions as an SEO research assistant. According to the system prompt source code, the agent helps users "research keywords, analyze domains and competitors, inspect SERPs, review backlinks, and read rank tracking and Google Search Console data." This agent transforms raw search data into actionable next steps, acting as an interface layer between complex SEO datasets and natural language queries.

Site Audit Interpretation

Agents access completed site audits through src/server/mcp/tools/site-audit-tools.ts. The implementation allows agents to "read the prioritized issue report from a completed site audit" without charging credits—explicitly marked as "Free — reads OpenSEO state" in the source. This enables users to query specific technical issues ("Why is my LCP score low?") and receive contextual remediation guidance directly from the audit database.

Backlink and Rank Tracking Intelligence

Through src/server/mcp/tools/search-console-tools.ts, agents query backlink tracking databases with automatic row limiting ("rowLimit is clamped to the agent cap"). This prevents resource exhaustion while allowing conversational exploration of link profiles and historical ranking data. The agents summarize complex backlink graphs into concise, actionable intelligence.

Project Context Sharing

The shared project memory system in src/server/mcp/tools/project-context.ts enables multiple agents to maintain synchronized state. As implemented in the source code, this tool "writes to a project's shared memory so the app, SAM, and other agents see it." This architecture prevents duplicate work—if the onboarding agent records a user's industry preference, the research agent immediately accesses that context without requiring the user to repeat information.

Technical Architecture and State Management

Durable Objects and Persistent Chat Sessions

OpenSEO agents run as Durable Objects (DOs) that persist state across HTTP requests. Unlike serverless functions that lose context after each execution, these agents maintain conversation history and project state indefinitely. The SamChatAgent.ts implementation throws an error if the OPENROUTER_API_KEY environment variable is missing, ensuring agents only initialize when properly configured with model access credentials.

Request Routing with routeAgentRequest

All agent traffic flows through a centralized routing layer in src/server.ts. The backend intercepts requests to /agents/* paths and delegates them to the appropriate Durable Object via the routeAgentRequest function imported from the "agents" SDK:

// src/server.ts
import { routeAgentRequest } from "agents";

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/agents/")) {
      return routeAgentRequest(request, env);
    }
    // Handle standard API routes...
  },
};

This pattern enforces consistent CORS handling, authentication checks, and credit limit enforcement across all agent interactions.

Credit-Free Data Access

The agents utilize a lightweight scraping utility in src/server/lib/scrape.ts for "lightweight, dependency-free site reading." This shared utility allows agents to fetch raw HTML for analysis without deducting from the user's credit pool. Similarly, reading existing site audit states and project context memory incurs no credit cost, making exploratory SEO research economically feasible for users.

Implementation Examples

Frontend Integration with React Hooks

Client-side components interact with agents through the useChat hook provided by the Agents SDK:

import { useChat } from "agents/react";

function SEOResearchAgent() {
  const { messages, sendMessage } = useChat({
    agent: "sam-onboarding",
    model: "gpt-oss-120b",
  });

  function analyzeDomain(domain: string) {
    sendMessage(`Analyze the backlink profile for ${domain}`);
  }

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>{m.content}</div>
      ))}
      <button onClick={() => analyzeDomain("example.com")}>
        Analyze Domain
      </button>
    </div>
  );
}

Defining Agent Behavior via System Prompts

The SAM agent's personality and capabilities are encapsulated in src/server/features/sam/samSystemPrompt.ts:

export const SAM_SYSTEM_PROMPT = `
You are SAM, the SEO agent inside OpenSEO. You help the user research keywords,
analyze domains and competitors, inspect SERPs, review backlinks, read rank
tracking and Google Search Console data, and turn it all into clear next steps.
`;

This prompt engineering ensures consistent, domain-specific responses that reference actual OpenSEO data structures rather than generating generic SEO advice.

Summary

• OpenSEO agents function as persistent, stateful SEO assistants running on Cloudflare Durable Objects.
• SAM (Search Assistant Model) handles everything from user onboarding to complex keyword and competitor research.
• Credit-free operations allow agents to read site audits, scrape HTML, and access project memory without consuming user credits.
• Shared project context ensures multiple agents maintain synchronized state through project-context.ts.
• Route aggregation via routeAgentRequest in src/server.ts provides centralized management of agent lifecycle and security.

Frequently Asked Questions

What does SAM stand for in OpenSEO?

SAM stands for Search Assistant Model. It is the primary AI agent persona defined in src/server/features/sam/samSystemPrompt.ts and implemented in src/server/features/sam/SamChatAgent.ts. SAM specializes in SEO research tasks including keyword analysis, SERP inspection, and backlink evaluation.

Do OpenSEO agents consume user credits for every query?

No. While complex operations may incur costs, the agents specifically optimize for credit-free reads. According to src/server/mcp/tools/site-audit-tools.ts, reading completed audit reports is "Free — reads OpenSEO state." Similarly, src/server/lib/scrape.ts provides lightweight HTML scraping shared by chat agents without credit deduction.

How do OpenSEO agents maintain conversation history between messages?

Agents persist state using Cloudflare Durable Objects. The routeAgentRequest function in src/server.ts routes requests to specific DO instances that maintain memory across sessions. This architecture allows agents to reference previous messages and project context indefinitely, unlike stateless serverless functions.

Can I use custom AI models with OpenSEO agents?

The agents default to OpenRouter models such as gpt-oss-120b, configured via the OPENROUTER_API_KEY environment variable. The SamChatAgent.ts implementation validates this key at initialization and throws an error if missing. While the current implementation targets OpenRouter, the Agents SDK architecture supports model provider swaps through environment configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}