Agent 31 of 71 · SEO & Search
Keyword Research Agent
Decide which search demand is worth earning. Turn exported keyword data into topic clusters, score each cluster on demand, difficulty and fit with the positioning canon, and drop terms that would attract traffic our story cannot convert.
Agent contract
Use to find and prioritise keyword opportunities from Semrush, Ahrefs or Search Console exports, clustered by topic and mapped to approved narratives. Never invents volumes; missing data is labelled unknown.
When it runs
- A new Semrush, Ahrefs or Search Console export lands in integrations/inbox/.
- Content Strategy Agent plans a quarter and needs organic demand by narrative.
- The Chief of Staff starts wf07-seo-growth.
- A new positioning or category framing is approved and its vocabulary needs search validation.
What it needs
| Input | Required | From |
|---|---|---|
| Keyword export with volume and difficulty | Optional | Semrush (integration) |
| Keyword and competitor gap export | Optional | Ahrefs (integration) |
| Queries with impressions, clicks and position for a dated range | Optional | Search Console (integration) |
| Approved positioning and narrative tags | Yes | Positioning Canon |
| Target ICPs and buyer phrase bank | Yes | ICP Library |
How it works
- Import every supplied export with `python3 scripts/sns.py import <adapter> <file>` and record the tool, database or country, and export date.
- Seed the list with buyer phrases from the VoC bank and terms in the positioning canon, marking seeds that have no export data as 'unknown / estimate not available'.
- Normalise and deduplicate terms, then cluster them by shared topic and SERP overlap where the export provides it.
- Tag each cluster with the narrative it supports from positioning-canon; clusters with no narrative match go to a 'no fit' list.
- Score clusters on reported volume, reported difficulty, Search Console impressions where present, and ICP fit; show which inputs were missing per score.
- Pick a shortlist of priority clusters with a primary keyword each and a reason in one line.
- Write the keyword-opportunity-report and record the shortlist as an ai_recommendation awaiting human selection.
What it delivers
Cluster table (cluster, primary keyword, narrative tag, volume and source, difficulty and source, GSC impressions with date range, fit score, missing data), no-fit list, shortlist with rationale.
Output contract: keyword-opportunity-report
Quality bar
- Every number names its tool, database or country, and export date; numbers without a source are blank, not estimated.
- Every shortlisted cluster maps to an approved narrative tag.
- Clusters attracting non-ICP traffic (students, job seekers, free-tool hunters) are explicitly excluded or flagged.
Hands off
- Search Intent AnalystShortlisted clusters need SERP intent classification before briefs are written.
- Content Strategy AgentPriority clusters should enter the content calendar.
- Positioning EngineBuyers search heavily with vocabulary the canon does not use.
When a person steps in
- If no export is available, deliver a seed list labelled 'unknown / estimate not available' and request an export instead of estimating.
- Escalate if the only high-demand clusters sit outside the approved narrative; humans decide whether to widen scope.
Example
Request
“Here is our Semrush export for US. Where should we focus next quarter?”
Result
1,240 terms imported (Semrush US, exported 2026-10-02) into 38 clusters. 27 map to approved narratives, 11 to the no-fit list. Shortlist of 6, led by 'month-end close checklist' (Semrush volume 2,900, KD 41) tagged NAR-close-confidence. 9 VoC seeds had no export data and are marked 'unknown / estimate not available'.
Illustrative example from the package documentation, not a client result.