How an SEO agent works
An interactive guide. Six small models you can play with, from the evidence an agent can see to the measurement that closes the loop.
An SEO agent is an AI agent doing SEO work with real evidence. You ask a question in plain language. It pulls what it needs from a crawl of your site, Search Console, your analytics, and live search results, then finds problems and opportunities, proposes changes, and measures what shipped.
This guide shows how that works without assuming you use a terminal. Each section explains one idea, gives you one small model to play with, and says what it means. Most demos use example data from a made-up outdoor gear store, so the numbers hold still while you poke them. Section three is the exception: it replays a real audit of a live site.
What an SEO agent can see
An agent is only as good as the evidence it can reach. Four sources cover most SEO questions, and they answer different things. A crawl reads your pages the way a search engine would. Search Console says what people searched and clicked. Analytics says what visitors did after arriving. Live results say who ranks today.
None of them can answer for another, which is the first thing worth feeling for yourself.
01 / The evidence
Every claim names its source
One question, four sources. Disconnect a source and watch which parts of the answer the agent can no longer make.
Why did clicks fall on the pricing page this month?
Observed · Crawl
The pricing page loads, returns 200, and nothing on it blocks search engines. The problem is not technical.
Observed · Search Console
Clicks fell from 480 to 210 in four weeks while impressions held. The page lost position, not demand.
Observed · Analytics
The visitors who still arrive behave the same as before. The drop is in arrivals, not on the page.
Observed · Live results
A competitor comparison page now sits above yours for the main query. That is where the clicks went.
- With nothing connected, the agent can still write plausible advice. So can any chatbot. The evidence is the difference.
All four sources connected. Every claim below names the evidence behind it.
Interactive demo: one question, "Why did clicks fall on the pricing page this month?", answered from four separate evidence sources. The crawl shows the page is technically fine. Search Console shows clicks fell while impressions held, so the page lost position, not demand. Analytics shows visitor behavior is unchanged, so the drop is in arrivals. Live results show a competitor page now ranks above it. Disconnecting a source removes the claims that depend on it, because one source cannot prove another's facts.
This is why "is my SEO good" has no one-source answer. The crawl can be clean while the demand quietly moves to a competitor. Keeping the sources separate is what makes the answer checkable later, when you want to know whether a fix worked.
An SEO agent works in a loop
A chatbot answers and stops. An agent keeps going, and SEO work has a natural shape for it to follow: find something worth acting on, inspect the evidence, propose a change, verify it went live, and measure what happened.
The trigger differs. Sometimes it is a problem, like pages that broke in a release. Sometimes it is an opportunity, like search demand with no page answering it. The stages do not change.
02 / The loop
Find, inspect, propose, verify, measure
An SEO agent runs the same five stages on repeat. Press play and watch the loop go round, then switch what it is chasing.
Press play, or step through. The five stages are the same whether the trigger is a problem or an opportunity.
Interactive demo: the five stages drawn as a closed circuit that an orange line travels around while it plays. Find (a crawl flags broken canonical tags, or Search Console shows unanswered demand), inspect the evidence, propose a change a human can judge, verify the live result after the deploy, and measure equal windows of final data either side of the change. The measurement feeds the next find. That return edge is what makes it a loop rather than a checklist.
The last stage is the one people skip, and it is the one that makes the loop worth running. What you measure this month decides what is worth finding next month.
Watch one investigation
Here is the loop run for real. On 10 August 2026 an agent audited ilo.so, an X analytics site I run, picked what to build from the query evidence, and the work shipped the same day. Press play and keep an eye on the right panel. The question at every step is the same. What can the agent point to?
03 / One investigation
From plain question to scheduled measurement
A real audit of ilo.so, run on 10 August 2026. Conversation on the left. On the right, the evidence the agent can actually point to at each step.
Step 8 / 8
Real evidence recorded from the ilo.so audit on 10 August 2026
Conversation
What is worth building on ilo next?
Read 180 days of final Search Console query and page evidence
There is real demand around X analytics. The profile-analytics page gets impressions at positions 11 to 24 with almost no clicks, and nothing on the site ranks posts by engagement.
Proposal: build a top-posts ranking tool, expand the profile-analytics and follower-count pages, and write guides for the impression questions people already ask.
Approved. Ship it.
Shipped the changes, then crawled the live site
Recorded the baseline before any post-change search data can exist
Scheduled the comparison for 10 September
Evidence the agent can point to
Search Console
/twitter-follower-count already earns clicks. "x follower count" shows 376 impressions at position 5.0, and "twitter follower tracker" 245 impressions at position 9.9.
Search Console
/twitter-profile-analytics: "twitter profile checker" earns 52 impressions at position 11.3, "twitter profile analytics" 61 impressions at position 23.9. Retained rows: 3 clicks in 180 days.
Search Console
/blog/twitter-impressions: "impressions on x meaning" earns 73 impressions at position 7.5, with no clicks yet.
Crawl
115 of 115 pages return 200 and are indexable. No failed or skipped pages. The new URLs are live.
Baseline
Site totals for the 28 final days to 7 August: 10,881 clicks, 228,237 impressions. The new URLs have no query rows yet, which is expected for new pages, not zero interest.
Scheduled
First clean 28-day post-change window: 11 August to 7 September. Compare once final data covers the whole window.
Press play to watch the audit that shipped on 10 August.
Interactive demo: a step-through of the real audit that ran against ilo.so on 10 August 2026. The owner asks what is worth building. The agent reads 180 days of final Search Console evidence and finds measured demand around X analytics: the follower-count page already earns clicks ("x follower count", 376 impressions at position 5.0), the profile-analytics page earns impressions at positions 11 to 24 with almost no clicks, and no page ranks posts by engagement. It proposes a top-posts ranking tool and expanded tool pages, backed by guides for the impression questions people already search. Two pull requests merge the same day. A post-deploy crawl verifies 115 of 115 pages return 200 and are indexable. The recorded baseline (10,881 clicks and 228,237 impressions for the 28 final days to 7 August) claims nothing about results, because final data cannot yet reflect the changes. The comparison is scheduled for 10 September, and the result gets published either way.
Notice what never happens. The agent does not claim the new pages will rank, and it does not mark the job done when the pull requests merge. The baseline records that the new URLs have no search data yet, because none can exist. The check is scheduled for 10 September, and the result becomes a public case study either way. Pointing at evidence, step after step, is what separates an SEO agent from a chatbot with opinions about SEO.
Evidence changes the answer
Data about your site is rarely complete. Search Console finalizes days late. Exports stop at row limits. Crawls go stale while you are busy shipping. A trustworthy agent does not paper over any of this. It changes its wording.
04 / Data states
The wording follows the evidence
The same question in five states of data. Click a state and watch the answer move from claim, to caveat, to request.
Clicks · tent footprint sizing
28 of 28 days final
Week 1
310
Week 2
298
Week 3
172
Week 4
121
Clicks fell 61% across the month, and the fall starts the day after the template release. Investigate that release first.
Clicks · tent footprint sizing
21 of 28 days final
Week 1
310
Week 2
298
Week 3
172
Week 4
121still settling
Clicks look well down, but the last week can still change. I would wait four days, then rerun this before calling it real.
Clicks · tent footprint sizing
Row limit reached
Week 1
310
Week 2
298
Week 3
172
Week 4
121
Row 1,000 of 1,000. The provider stops here.
The export stops at the row cap, so everything past row 1,000 is unknown, not zero. I will rank what I can see and say what I cannot.
Clicks · tent footprint sizing
No data
Search Console is not connected for this project.
I have no click data for this site, so I will not invent any. Connect Search Console or hand me an export, and this becomes answerable.
Clicks · tent footprint sizing
Export dated 14 March, 150 days old
Week 1
310
Week 2
298
Week 3
172
Week 4
121
This data predates the release you are asking about. Anything I conclude from it may already be fixed, or already worse. Refresh it first.
Zero, missing, capped, and stale are four different facts. Blur them and you will fix the wrong thing.
Interactive demo: the same click question shown in five data states. Complete data earns a direct claim: clicks fell 61% starting the day after a template release. Partial data earns a caveat, since the last week is still settling. A capped export makes the agent say that rows past the limit are unknown rather than zero. Missing data turns the answer into a request to connect Search Console. A stale export makes the agent ask for fresh data before blaming the release. The state of the evidence changes the wording, not just the numbers.
The wording is the tell. A tool that returns the same confident sentence in all five of those states is filling in a template, not reading your data.
You decide what ships
An agent that publishes whatever it likes is a liability. The workable shape is a queue. The agent proposes changes with the evidence attached, and you approve, narrow, or skip each one.
05 / The approval queue
The agent proposes. You decide.
Work the queue like it is Monday morning. Inspect the evidence, narrow anything too broad, approve what earns it, and skip what does not.
Add meta descriptions to 8 posts that have none
8 pages
Crawl: 8 posts return no description tag. Search Console: all 8 earn impressions, so search engines are writing their snippets for them.
Rewrite 12 page titles to match the queries they earnRewrite the 3 titles whose clicks fell while impressions held
12 pages3 pages
Search Console: 12 pages where the top query is missing from the title. Only 3 of them are losing clicks. The other 9 are working fine.
Redirect 4 retired product pages to their categories
4 redirects
Crawl: the 4 pages return 404. Search Console: they still earn clicks from old links, and those visits currently dead-end.
Rewrite the homepage headline to include more keywords
1 page
None. No query, page, or crawl row connects the headline to a search problem. This one deserves the skip.
Four proposed changes are waiting on you. The agent works through the approved list only.
Interactive demo: a queue of four proposed changes with Inspect, Narrow, Approve, and Skip actions. Adding missing meta descriptions and fixing dead product pages carry crawl and Search Console evidence. A broad 12-title rewrite can be narrowed to the 3 pages that are actually losing clicks. A keyword-stuffed homepage headline rewrite carries no evidence at all, and skipping it is the point. The agent acts on the approved list only, so nothing ships without a human decision.
The queue only works if you use all four buttons. Narrowing a broad change and skipping an unevidenced one are the decisions that keep the site yours. (The keyword headline was in the queue on purpose. Every SEO tool has one of those ideas. You are allowed to say no.)
Measure the change
The loop ends with a comparison: clicks before the change against clicks after. Two rules keep it honest. The windows on either side must be the same length, and the newest days must stay out of the comparison, because search data is not final for several days.
06 / Measurement
Equal windows, final data only
Drag the change date. The before and after windows stay the same length, and the newest days stay out of the comparison because they are not final yet.
- Before window
- After window
- Not final yet
- Outside the comparison
Before: 760 clicks. After: 1,003 clicks. Observed change: +32%.
Interactive demo: 84 days of example daily clicks with a real step change at day 42. A slider moves the comparison date. The before and after windows stay 21 days each, and the newest 3 days are excluded because Search Console data is not final yet. With the windows around the real change the observed difference is about +30%. Move the date away from the change and the observed difference shrinks, which is the point: the windows show an observed movement, not proof of what caused it.
One thing the demo cannot show is causation. The windows show an observed movement. Rankings also move for reasons that have nothing to do with you, which is why the loop verifies the change went live and reports the result either way, up or down.
Jobs an SEO agent can do
The same loop covers most of the SEO work a site needs:
- Diagnose a site that lost traffic, and say which evidence supports each suspected cause.
- Find queries with real demand and no page answering them.
- Improve an existing page against the queries it already earns.
- Watch for technical regressions after releases.
- Investigate local search results for a place, kept separate from national rankings.
- Check how ready pages are for AI search, as observations rather than promises.
- Measure a shipped change with equal windows of final data.
The reports guide lists every report behind those jobs, and what each one can and cannot prove.
Try it on your own site
Everything in this guide runs locally from one command. Install it, sign in to Search Console during setup, and the first report on your own site is a few minutes away.
Runafter install
Install the SEO CLI globally.
npm i -g seoRun setup after installation.
seo startThe getting started guide walks through setup, and the skill page covers giving your own agent the same reports through Claude, Codex, and other tools.
SEO has always been evidence work. An agent just never gets bored of checking.