How to Build a Simple AI Agent for SEO (Step by Step)

When people hear “build an AI agent,” many picture a team of engineers, a big budget and months of work. A lot of business owners tell me, “That is for big companies, not for a small marketing team like ours.”

That belief was fair two years ago. Today it is mostly wrong. You can build a small, useful SEO agent in an afternoon, often without writing code, as long as you keep the job narrow and give it good data and clear rules.

In this guide I will walk you through the whole build, step by step. We will build one real example together: an agent that finds “almost ranking” keywords in Google Search Console every week and drafts a short action list. Along the way I will explain each choice in plain words, so you can reuse the same method for other SEO tasks.

What we are building: a weekly “almost ranking” agent

Before any tools, let me define the agent clearly. An SEO agent is software that does SEO work in several steps, not just answers a question. Louise Linehan puts it neatly in the Ahrefs guide AI Agents for SEO (May 2026):

“An AI SEO agent is software that actually does the SEO work, as opposed to just describing it.”

— Louise Linehan, AI Agents for SEO (Ahrefs)

Our agent will do five things every Monday:

1. Pull the last 28 days of queries and pages from Search Console.
2. Find queries where a page ranks in positions 5–15 with real impressions.
3. Group those queries by page.
4. For the top 10 pages, check whether the page already uses the query in its title or headings.
5. Send a short report with a suggested fix for each page.

It will not edit your website. It finds and suggests; a person decides. If you want the bigger picture of where this fits, my guide to agentic SEO explains the concept and other starter workflows.

Step 1: choose one narrow, repeatable task

The most common mistake I see is trying to build “an SEO agent” that does everything. That agent never works well. The Ahrefs guide gives the right advice: start with the highest-repetition task your team does by hand.

A good first task passes these tests:

• It repeats at least weekly.
• The data is available through an API or export.
• The output is easy to check. You can tell in five minutes if the agent got it right.
• Mistakes are cheap. A wrong suggestion in a report costs nothing. A wrong redirect costs traffic.

Here is how common SEO tasks score against those tests:

Task	Repeats often?	Data via API?	Easy to check?	Safe if wrong?	Good first agent?
“Almost ranking” keyword report	Yes	Yes (Search Console)	Yes	Yes	Yes
Weekly traffic-drop alert	Yes	Yes	Yes	Yes	Yes
Internal link suggestions	Yes	Partly (crawler)	Yes	Yes, if suggestions only	Yes, second
Writing and publishing blog posts	Yes	Yes	No, slow to review	No	No
Fixing redirects on the live site	Rarely	Yes	Hard	No	No

No-code or code: picking the platform for your SEO agent

You have three realistic routes. None is “best.” It depends on your comfort level and how much control you need.

Route	Examples	Good for	Watch out for
Chat app + connectors	Claude or ChatGPT with MCP connectors	Fastest start, very flexible, low cost	Local setups stop when your computer is off; harder to schedule
Visual workflow builder	n8n, Gumloop	Scheduling, clear steps you can see, no code	You build each step; less “thinking” between steps
Code	Python script with an AI model API, or Claude Code	Full control, big data, custom scoring	Needs someone comfortable with code and API keys

The Ahrefs guide also describes purpose-built SEO agents from tool vendors, which come with their own data and ready-made skills. Those are worth a look if you already pay for that tool.

For this tutorial, I will describe the steps in a way that works on any route. Where code helps, I will show a short snippet. If you are curious about the code route, my guide on using Claude Code for SEO goes deeper, and Python for SEO covers the basics.

Step 2: connect Search Console and your other data

An agent is only as good as its data. If it can’t see real numbers, it will guess, and guesses look convincing in AI output. So the next step is to connect real sources.

Option A: an MCP connector

MCP (Model Context Protocol) is a standard way to plug data and tools into AI apps. The official MCP site describes it as an open-source standard for connecting AI applications to external systems. There are community MCP servers for Search Console, such as mcp-gsc on GitHub, which the Ahrefs guide mentions. Once connected, you can ask your chat app for Search Console data in plain words. I explain how connectors work in MCP for marketers.

A word of caution: community connectors are written by individuals, not Google. Read what access they ask for, and use a Google account with read-only (“Restricted”) access to the property where possible.

Option B: the Search Console API directly

If you go the code or n8n route, you will call the Search Analytics API. Here is the request body our agent uses (the dates are examples):

{
  "startDate": "2026-09-14",
  "endDate": "2026-10-11",
  "dimensions": ["page", "query"],
  "rowLimit": 25000,
  "startRow": 0
}

A few facts from Google’s documentation that shape the design:

• 25,000 rows per request. Google’s guide to getting all your data uses 25,000 as the maximum response size. For more rows, you repeat the call and raise startRow by 25,000 until you get zero rows back.
• Data lags. The same page says data is typically available after 2–3 days. So I end the date range three days before today.
• Daily ceiling. The same guide says the Search Analytics method exposes a maximum of 50,000 rows per day per search type, sorted by clicks. On very large sites, long-tail queries will be missing. That is fine for our use case.
• Rate limits. Google’s usage limits page lists 1,200 queries per minute per site for Search Analytics, and 2,000 URL inspections per day per site. A weekly agent will never come close.

Optional extra data

To check titles and headings, the agent needs to see the page. The simplest way is to let it fetch the live URL. On larger sites, I prefer a crawler export (title, H1, H2s per URL) saved to a Google Sheet, so the agent isn’t hammering your server.

Step 3: write the agent’s instructions like a job description

This is the step that decides whether your agent is useful or annoying. Write instructions the way you would brief a new junior hire: the goal, the steps, the rules and what “done” looks like.

The Ahrefs guide suggests splitting instructions into short, single-purpose “skill” files instead of one long prompt. Anthropic publishes examples of this format in its skills repository on GitHub. Here is a shortened version of the instruction file for our agent:

# Skill: weekly almost-ranking report

Goal: find queries where our pages rank 5-15 and suggest
quick on-page fixes. Do not edit the website.

Steps:
1. Pull page + query data for the last 28 days,
   ending 3 days ago.
2. Keep rows where position is 5.0-15.0 and
   impressions >= 100.
3. Group by page. Score each page:
   score = sum of impressions for kept queries.
4. Take the top 10 pages by score.
5. For each page, fetch title, H1 and H2s.
   Note which top queries are missing from them.
6. Suggest one fix per page (title tweak, new H2,
   new FAQ answer, internal link). One line each.

Rules:
- Use only numbers from the data. Never estimate.
- If a tool call fails, retry once, then report it.
- Show the raw rows for every page you list.
- Stop after 30 tool calls.

Output: a table (page, score, top 3 queries,
missing from title/H1?, suggested fix).

Notice three things. The thresholds are exact numbers, not “high impressions.” There is a hard stop. And the agent must show raw rows, so you can check its work in seconds.

If you want ready-made prompt wording for SEO tasks, my list of ChatGPT and Claude prompts for SEO is a good starting point.

Step 4: add tools and limits, and keep them tight

Tools are what turn a chatbot into an agent: the ability to fetch data, read a page or send a message. Each tool also adds risk. Anthropic’s engineering team makes this point about tools:

“It is therefore crucial to design toolsets and their documentation clearly and thoughtfully.”

— Anthropic, Building Effective AI Agents

For our agent, I would give exactly four tools:

• Search Console: read (search analytics query).
• Web fetch: read (only for your own domain).
• Google Sheets: write (only to one “agent output” sheet).
• Slack or email: send (only to one channel or address).

No WordPress access. No access to your CMS, DNS or Google Ads. If it can’t touch those, it can’t break them.

The Ahrefs guide adds a practical tip I agree with: give the agent the actual API documentation for each tool, so it doesn’t invent parameters that don’t exist. In an MCP setup this is often built in. In a custom setup, paste the relevant doc section into the instructions.

Step 5: test the agent on last month’s data

Never schedule an agent you haven’t tested by hand. Run it on data where you already know the answer, and compare.

Here is my test routine:

1. Run it once manually for last month.
2. Check 10 rows against Search Console in your browser. Are the clicks, impressions and positions the same?
3. Check the logic. Did it really filter positions 5–15? Did it skip pages with fewer than 100 impressions?
4. Check the suggestions. Are they specific (“add ‘tankless water heater cost’ to the H1”) or vague (“improve content”)?
5. Break it on purpose. Give it a property with no data, or a URL that returns 404. Does it report the problem or make something up?
6. Fix the instructions and run again until it passes.

Example: reading the first test run

Here is a hypothetical first report for a small ecommerce site, to show what “good” looks like:

Page	Score (impressions)	Top query	Avg position	In title/H1?	Suggested fix
/merino-wool-socks/	8,400	merino hiking socks	7.2	No	Add “hiking” to the H1 and a short section on hiking use
/blog/how-to-wash-wool/	5,100	can you put wool in the dryer	9.8	No	Add an H2 that answers the dryer question directly
/gift-sets/	2,900	sock gift box	11.4	Partly	Link to this page from the 3 top sock product pages

Expect the first run to include at least one weak suggestion. That is normal. The fix is to tighten the instruction, for example: “Each suggestion must name the exact query and where to add it.”

Also watch for made-up numbers. If a row in the report doesn’t exist in the raw data, the agent is guessing. Add the rule “use only numbers from the data” in capital letters if you must, and keep the raw-rows requirement.

Step 6: schedule it and decide who gets the alert

Once the agent passes your tests twice in a row, schedule it. How you do this depends on the route:

• n8n or similar: add a schedule trigger (for example, Mondays at 8:00) at the start of the workflow.
• Code: a scheduled job on a server or a cloud scheduler. Avoid running it on a laptop that may be closed.
• Chat apps: some now offer scheduled tasks. Check what your plan includes, because features vary.

Then decide who receives the report and what they do with it. A report nobody owns is just noise. I suggest one named person who reviews it on Monday and moves the best two or three suggestions into the week’s task list.

Two alert rules I find useful:

• Quiet weeks stay quiet. If nothing passes the thresholds, send one line: “No new opportunities this week.”
• Failures are loud. If a tool fails twice, the message starts with “FAILED” so nobody mistakes an empty report for good news.

Step 7: maintain the agent like any other tool

Agents drift. APIs change, your site changes, and your goals change. Plan a short check every month.

Check	How often	What to do
Spot-check 10 rows against Search Console	Monthly	If accuracy drops, review the data connection first
Review suggestions acted on	Monthly	If nobody uses a type of suggestion, remove it from the instructions
Review thresholds	Quarterly	Raise the 100-impression floor if the report is too long
Check connector updates and permissions	Quarterly	Remove access the agent no longer needs
Measure results	Quarterly	Did pages you fixed move from positions 5–15 into the top 5?

The Ahrefs guide also suggests keeping a simple “memory” file where you note lessons, such as “ignore branded queries” or “the /old-blog/ folder is being retired.” The agent reads it on every run. It is a small habit that saves a lot of repeated corrections.

Once this first agent is stable, you can reuse the same seven steps for a second one. Good next candidates are a content refresh queue or internal link suggestions. For the writing side, my post on content engineering shows how to connect agents to a review process without flooding your site with AI text, which Google’s generative AI content guidance warns against.

Questions people ask before building an SEO agent

How much does a simple SEO agent cost to run?

For a weekly report like this, the main costs are your AI subscription or API usage and any workflow tool plan. The Search Console API itself is free within Google’s limits. Costs rise with data size and how often it runs, so start weekly.

Which AI model should I use?

The Ahrefs guide suggests prototyping with cheaper models first. For a report that filters numbers and writes short suggestions, a mid-range model is usually enough. Use a stronger model only if the suggestions are weak after you improve the instructions.

Is it safe to connect Search Console to an AI tool?

It can be, with care. Use read-only access, check what a connector requests, and prefer official or well-reviewed connectors. Never give an agent owner-level access to a Search Console property.

Can the agent just make the fixes for me?

Technically yes, if you connect your CMS. I don’t recommend it for a first agent. Keep it to suggestions until you trust its accuracy for several months, and even then keep a human approval step.

How is this different from an AI marketing assistant?

An assistant answers questions when you ask. An agent runs a task on its own schedule. My guide to building an AI marketing assistant covers the assistant side.

Build your first SEO agent this week, then expand slowly

In brief: pick one boring, weekly task. Connect real data with read-only access. Write instructions like a job description with exact numbers. Test on last month’s data. Schedule it, give the report an owner, and check it monthly.

That is all an SEO agent really is at the start. The value comes from running it every week without fail, so small problems and quick wins never slip through.

If you would rather have a team set this up for you, or you want the fixes it finds implemented properly, our SEO services team can help. You can also request a free quote and tell us which task you want to automate first.

Further reading on AI agent for SEO

• Google's Knowledge Graph: How It Works and How to Check Your Brand
• AI-Proof Keywords: Finding Queries AI Answers Can't Fully Satisfy
• Agentic AI vs Generative AI: The Difference for Marketers

Sources for this SEO agent tutorial

1. Ahrefs — AI Agents for SEO (Louise Linehan, May 2026)
2. Anthropic — Building Effective AI Agents
3. Google for Developers — Getting all your performance data
4. Google for Developers — Search Console API Usage Limits
5. Model Context Protocol — What is MCP?
6. GitHub — mcp-gsc (Search Console MCP server)
7. GitHub — Anthropic skills repository
8. Google Search Central — Guidance on Generative AI Content