Build an AI SEO Audit Team with Gemini

SEO optimization is both critical and time-consuming for teams building businesses. Manually auditing pages, researching competitors, and synthesizing actionable recommendations can eat up hours that you'd rather spend strategizing.

In this tutorial, we'll build an AI SEO Audit Team using Google's Agent Development Kit (ADK) and Gemini 2.5 Flash. This multi-agent system autonomously crawls any webpage, researches live search results, and delivers a polished optimization report through a clean web interface that traces every step of the workflow.

What makes Google ADK special?

Google ADK is a powerful framework for building multi-agent systems with specialized roles. It lets you build teams with advanced patterns and hierarchies. Combined with Gemini 2.5 Flash’s intelligence, Firecrawl for accurate page scraping, and Google Search for SERP intelligence, ADK provides everything you need to build production-ready agentic systems.

Don’t forget to share this tutorial on your social channels and tag Unwind AI (X, LinkedIn, Threads, Facebook) to support us!

What We’re Building

This application implements a three-agent sequential pipeline that takes a webpage URL and produces a comprehensive SEO optimization report. Each agent specializes in a distinct phase of the audit workflow, passing structured data to the next stage.

Our AI Agent Team:

1. Page Auditor Agent - Uses Firecrawl MCP to scrape URL, inspects page structure, summarizes technical/content signals, and infers target keywords.

2. Serp Analyst Agent - Uses Google Search, extracts patterns for each keyword, identified opportunities, and differentiation angles.

3. Optimization Advisor Agent - Combines Page Audit + Serp Analyst’s insights into a professional report with clear priorities and next steps.

Features:

• Automated On-Page Audits: Crawls live pages with Firecrawl and extracts title tags, headings, word count, link health, and technical signals

• Competitive SERP Research: Performs Google Search for the inferred primary keyword and analyzes top-10 competitors

• Actionable Optimization Reports: Generates prioritized recommendations with rationale, expected impact, and effort estimates

• ADK Dev UI: Traces every agent step with visual workflow inspection, making debugging convenient

Prerequisites

Before we begin, make sure you have the following:

1. Python installed on your machine (version 3.11 is recommended)

2. Your Firecrawl and Gemini API key

3. A code editor of your choice (we recommend VS Code or PyCharm for their excellent Python support)

4. Basic familiarity with Python programming

Code Walkthrough

Setting Up the Environment

First, let's get our development environment ready:

1. Clone the GitHub repository:

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git

🌟 Don't forget to star the opensource repo to show your support.

2. Go to the ai_seo_audit_team folder:

cd advanced_ai_agents/multi_agent_apps/agent_teams/ai_seo_audit_team

3. Install the required dependencies:

pip install -r requirements.txt

4. Set your Firecrawl API key and Gemini API key from Google AI Studio as environment variables:

export GOOGLE_API_KEY=your_gemini_key_here
export FIRECRAWL_API_KEY=your_firecrawl_key_here

Alternatively, you can create a .env file in the same directory:

GOOGLE_API_KEY=your_gemini_key_here
FIRECRAWL_API_KEY=your_firecrawl_key_here

Creating the App

Let's break down the agent system. Create a new file agent.py (or use the provided one) and follow along:

1. Define Output Schemas with Pydantic:

from pydantic import BaseModel, Field
from typing import List, Optional

class HeadingItem(BaseModel):
    tag: str = Field(..., description="Heading tag such as h1, h2, h3.")
    text: str = Field(..., description="Text content of the heading.")

class AuditResults(BaseModel):
    title_tag: str
    meta_description: str
    primary_heading: str
    secondary_headings: List[HeadingItem]
    word_count: Optional[int]
    content_summary: str
    link_counts: LinkCounts
    technical_findings: List[str]
    content_opportunities: List[str]

class PageAuditOutput(BaseModel):
    audit_results: AuditResults
    target_keywords: TargetKeywords

2. Set up Firecrawl MCP:

from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters
import os

firecrawl_toolset = MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=[
            "-y",  # Auto-confirm npm package installation
            "firecrawl-mcp",  # The Firecrawl MCP server package
        ],
        env={
            "FIRECRAWL_API_KEY": os.getenv("FIRECRAWL_API_KEY", "")
        }
    ),
    tool_filter=['firecrawl_scrape']  # Use only the scrape tool
)

3. Create the Page Auditor Agent:

from google.adk.agents import LlmAgent

page_auditor_agent = LlmAgent(
    name="PageAuditorAgent",
    model="gemini-2.5-flash",
    instruction="""You are Agent 1 in a sequential SEO workflow.

STEP 1: Extract the URL from the user's message
STEP 2: Call firecrawl_scrape with parameters:
  - url: <extracted URL>
  - formats: ["markdown", "html", "links"]
  - onlyMainContent: true
  - timeout: 90000

STEP 3: Analyze scraped data (title, headings, word count, links, technical issues)
STEP 4: Infer primary and secondary keywords, search intent, supporting topics
STEP 5: Return structured JSON matching PageAuditOutput schema""",
    tools=[firecrawl_toolset],
    output_schema=PageAuditOutput,
    output_key="page_audit"
)

The output_key tells ADK to store results in state['page_audit'] for downstream agents.

4. Create a Helper Agent for Google Search:

‼️ This is an important workaround - A known limitation of ADK is that it does not support built-in tool use along with function calls within agent flows, particularly when sub-agents are involved. This is a workaround where we wrapped the search in a dedicated agent and exposed it through AgentTool.

from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

search_executor_agent = LlmAgent(
    name="perform_google_search",
    model="gemini-2.5-flash",
    instruction="""Execute Google searches for the provided keyword.
- Return JSON with query and array of results (title, url, snippet).
- No extra commentary—JSON text only.""",
    tools=[google_search]
)

google_search_tool = AgentTool(search_executor_agent)

5. Create the SERP Analyst Agent:

serp_analyst_agent = LlmAgent(
    name="SerpAnalystAgent",
    model="gemini-2.5-flash",
    instruction="""You are Agent 2 in the workflow.

STEP 1: Read primary keyword from state['page_audit']['target_keywords']['primary_keyword']
STEP 2: Call perform_google_search tool with the keyword
STEP 3: Parse search results (rank, title, URL, snippet, content_type)
STEP 4: Analyze patterns (title patterns, content formats, key themes)
STEP 5: Return structured JSON matching SerpAnalysis schema""",
    tools=[google_search_tool],
    output_schema=SerpAnalysis,
    output_key="serp_analysis"
)

6. Create the Optimization Advisor Agent:

optimization_advisor_agent = LlmAgent(
    name="OptimizationAdvisorAgent",
    model="gemini-2.5-flash",
    instruction="""You are Agent 3 and the final expert in the workflow.

STEP 1: Review state['page_audit'] and state['serp_analysis']
STEP 2: Create a Markdown report with:
  - Executive summary
  - Technical & on-page findings
  - Keyword analysis
  - Competitive SERP analysis
  - Prioritized recommendations (P0/P1/P2)
  - Next steps

STEP 3: Return ONLY Markdown (no JSON, no preamble)
Start directly with "# SEO Audit Report"."""
)

7. Orchestrate the Sequential Workflow:

from google.adk.agents import SequentialAgent

seo_audit_team = SequentialAgent(
    name="SeoAuditTeam",
    description="Three-agent pipeline: audit → SERP → optimization report",
    sub_agents=[
        page_auditor_agent,
        serp_analyst_agent,
        optimization_advisor_agent
    ]
)

root_agent = seo_audit_team

8. ‼️ Critical Setup: The root_agent must be exported in __init__.py for ADK to discover it:

# __init__.py
from .agent import root_agent
__all__ = ["root_agent"]

Without this export, adk web cannot load your app.

Running the App

With our code in place, it's time to launch the app.

1. Go to the agent_teams folder and start ADK Web:

cd advanced_ai_agents/multi_agent_apps/agent_teams
adk web

2. Open your browser to the URL provided (typically http://localhost:8000)

3. Select "ai_seo_audit_team" from the app list

4. Enter a target URL when prompted (e.g., https://www.theunwindai.com/) and hit Enter to start the workflow.

Working Application Demo

Conclusion

You've just built a production-ready AI SEO Audit Team that automates tedious manual work - scraping, competitive research, and report generation - in a single workflow. With Google ADK handling orchestration and tracing, and Gemini 2.5 Flash powering the analysis, you have a system that scales from quick audits to comprehensive SEO analysis.

For further enhancements, consider:

1. Integrating Notification Systems: Hook the Markdown report into Slack, email, or ticketing tools (Jira, Linear) for automatic handoffs.

2. Expanding the Workflow: Add agents for schema markup generation, content brief creation, or A/B test planning using the shared session state.

3. Supporting Bulk Audits: Firecrawl supports Batch Scraping so you can audit multiple websites at once.

4. Building Content Creation Agents: Take the pipeline to the next level by adding content generation agents that transform recommendations into ready-to-publish content.

Keep experimenting with different configurations and features to build more sophisticated AI applications.

We share hands-on tutorials like this 2-3 times a week, to help you stay ahead in the world of AI. If you're serious about leveling up your AI skills and staying ahead of the curve, subscribe now and be the first to access our latest tutorials.

Don’t forget to share this tutorial on your social channels and tag Unwind AI (X, LinkedIn, Threads) to support us!