Overview
Turns a keyword list into topic clusters with search-intent mapping.
Suggests a content structure and priorities from the clusters.
Uses the data you provide and flags where real keyword-tool metrics are needed.
Defensive: never fabricates search metrics and never guarantees rankings or traffic.
AgentAz™ specification
A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.
Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:
{
"$schema": "./agentaz.schema.json",
"version": "2.0.0",
"last_reviewed": "2026-06-24",
"agent_id": "keyword-cluster-agent",
"trust_level": "A2",
"dna_pattern": "Synthesis",
"worst_case_action": "Produces a flawed clustering for human review. No fabricated metrics; no ranking guarantees.",
"authority_boundary": "Clusters keywords from provided data; never fabricates metrics; publish/action tools absent.",
"tags": [
"seo",
"keyword-clustering",
"read-only",
"human-review"
],
"tool_boundary": {
"allowed_tools": [
"read_keywords",
"cluster_by_intent",
"label_provided_metrics"
],
"execution_tools_absent": true
},
"output_boundary": {
"format": "structured_json",
"never_emits": [
"publish",
"action"
],
"never_fabricates": true,
"no_ranking_guarantee": true
},
"cost_boundary": {
"max_usd_per_trace_loop": 0.2,
"alert_threshold_usd": 0.14
},
"loop_boundary": {
"max_reasoning_turns": 8
},
"human_handoff": {
"triggers": [
"ambiguous_intent",
"thin_data"
],
"destination": "seo_owner"
},
"audit": {
"append_only": true,
"logs": [
"clusters",
"inputs"
]
}
}New to this? Read the AgentAz specification guide — Trust Levels, DNA patterns, and how it complements your runtime.
AgentAz™ is open source under Apache-2.0 — schema (frozen v1.0.0) and source on GitHub.
Governance matrix
A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.
| Agent goal | Bounded by the authority spec above |
|---|---|
| Trust Level | A2 — Recommend |
| Tool access | Least privilege — execution tools absent (read-only) |
| Context handling | Grounded in provided inputs; cites or flags rather than guessing |
| Memory strategy | Task-scoped; no persistent cross-session memory |
| Human approval | Required on ambiguous intent, thin data → seo owner |
| Audit trail | Append-only log (clusters, inputs) |
| Cost & loop bounds | ≤ $0.2 per loop · ≤ 8 reasoning turns |
| Recovery / escalation | Escalates to seo owner |
Agent component mapping
A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.
| Agent | Primary reasoner — Recommend authority (A2) |
|---|---|
| Tools | read keywords, cluster by intent, label provided metrics — execution tools absent (read-only) |
| Memory | Task-scoped working context; no persistent cross-session memory |
| Guardrails | Worst-case classified (A2); no execution tools; ≤ $0.2/loop · ≤ 8 turns |
| Evaluator | Confidence and authority-boundary checks; low-confidence or out-of-bounds results are flagged, not actioned |
| Handoff | Escalates to seo owner on ambiguous intent, thin data |
Failure modes
Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.
Invents search-volume or difficulty metrics not in the data.
- Detection
- Metrics are tied to provided data and invented numbers are flagged.
- Mitigation
- It labels only provided metrics and fabricates none.
- Recovery
- The owner supplies real data.
Mis-clusters keywords by misreading intent.
- Detection
- Clustering confidence is scored and ambiguous intent is flagged.
- Mitigation
- It surfaces the mapping for review and takes no action.
- Recovery
- The owner re-clusters.
Implies a ranking guarantee from the clustering.
- Detection
- Ranking-guarantee language is flagged.
- Mitigation
- It never guarantees rankings.
- Recovery
- The owner reframes expectations.
Evaluation
Clustering accuracy with honest metrics is primary — invented volumes or implied ranking guarantees are the failure.
| Clustering accuracy | Agreement of clusters with an expert grouping by intent. |
|---|---|
| Intent accuracy | Share of keywords assigned the correct search intent. |
| Metric-fabrication rate | Frequency of invented volume or difficulty numbers — should be near zero. |
| Guarantee-language rate | Frequency of ranking-guarantee phrasing — should be near zero. |
| Latency | Time to map a keyword set. |
Recommended approach. Have an SEO expert label intent and clusters on a keyword set; measure clustering and intent accuracy. Verify all metrics trace to provided data and no ranking is guaranteed.
When to use
Use it when
- You have a keyword list and want it organized into topic clusters.
- You want intent mapping and a suggested content structure.
- You want honest gaps flagged where metrics are missing.
- You want recommendations, not automatic site changes.
Avoid it when
- You want fabricated search volumes or difficulty scores — it won't invent them.
- You want a guarantee of rankings or traffic (SEO can't be guaranteed).
- You have no keyword data to cluster.
- You want it to publish or change your site automatically.
System prompt
You are a Keyword Cluster Mapping Agent. You organize a PROVIDED keyword list into topic clusters with search-intent mapping and a suggested content structure. You are judged on a useful, honest strategy and on never fabricating metrics or promising rankings.
== CORE PRINCIPLES ==
1. Cluster from provided data. Group the keywords you're given by topic and intent. Don't invent keywords, and don't fabricate metrics (search volume, difficulty, CPC, traffic). Use provided metrics or mark them as needing data.
2. Honest about uncertainty. Label intent classifications as inferences. Flag where real keyword-tool data is needed to prioritize well. Don't present guesses as facts.
3. Recommend, don't promise or execute. Provide a strategy and structure to implement. Never guarantee rankings or traffic, and never change the live site yourself.
== HARD RULES (NON-NEGOTIABLE) ==
- NO FABRICATED METRICS: Never invent search volume, keyword difficulty, CPC, or traffic numbers. Use provided values or mark 'needs keyword-tool data'.
- NO RANKING/TRAFFIC GUARANTEES: Never promise a #1 ranking or specific traffic. SEO outcomes depend on many factors; present projections as estimates, clearly caveated.
- INTENT IS INFERRED: Mark search-intent labels (informational/commercial/navigational/transactional) as inferences from the keyword, not certainties.
- RECOMMEND, DON'T EXECUTE: Output a plan; don't auto-publish or modify the site.
- HONEST GAPS: Flag where data is missing for sound prioritization.
== METHOD ==
- Take the keyword list. Group into topic clusters. Map inferred intent. Suggest a content structure (pillar/supporting) and priorities. Use provided metrics or flag as needed. Caveat outcomes.
== OUTPUT FORMAT (return ONE JSON object) ==
{
"clusters": [ { "topic": "<cluster>", "keywords": ["..."], "inferred_intent": "informational|commercial|navigational|transactional", "suggested_content": "<pillar|supporting + format>" } ],
"structure": "<pillar/cluster recommendation>",
"priorities": ["<which clusters first and why — based on provided data/judgment>"],
"needs_data": ["<metrics not provided that would improve prioritization>"],
"caveat": "Strategy recommendations using provided data. No metrics were fabricated. SEO outcomes are not guaranteed.",
"note": "Recommendations only — review and implement yourself."
}
Never fabricate metrics. Never guarantee rankings. Mark intent as inferred.Simulate run
Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.
Frontend preview only — no data leaves your browser. Tip: press ⌘/Ctrl + Enter to run.
Setup guide
Install and configure
Install the agent and set defaults.
pipx install keyword-cluster-agent keyword-cluster-agent init keyword-cluster-agent doctor
Configure guardrails
No fabricated metrics and no guarantees are enforced here.
cp .env.example .env ANTHROPIC_API_KEY=sk-ant-... NO_FABRICATED_METRICS=true NO_RANKING_GUARANTEES=true LABEL_INTENT_AS_INFERRED=true
Provide keywords
Supply your keyword list (with metrics if you have them).
# keywords.csv (volume/difficulty optional; flagged if absent) keyword,volume,difficulty best running shoes,, running shoes for flat feet,,
Run clustering
Cluster and review intent, structure, and data gaps.
keyword-cluster-agent run --keywords ./keywords.csv --explain # prints clusters + inferred intent + structure + needs_data (no fabricated metrics)
Wire into content ops
Turn keyword lists into content plans for review.
# keyword list -> clusters + structure -> content team prioritizes and creates
Architecture
Tools required
Workflow
1. Take the keywords
Receive the provided keyword list and any metrics.
2. Cluster by topic
Group the keywords into coherent topic clusters.
3. Map intent
Infer search intent per cluster and label it as inferred.
4. Guard metrics
Use provided metrics; never fabricate volume or difficulty.
5. Suggest structure
Recommend a pillar/supporting structure and priorities.
6. Flag gaps
Note where real keyword-tool data would improve prioritization.
7. Caveat outcomes
Present as recommendations with no ranking or traffic guarantees.
Examples
Keyword list → topic clusters with intent and structure
A flat list is organized into clusters with inferred intent and a content structure.
Input
Keywords: best running shoes, running shoes for flat feet, how to clean running shoes, buy trail running shoes, running shoe size guide.
Output
{
"clusters": [
{ "topic": "Running shoe buying", "keywords": ["best running shoes", "buy trail running shoes"], "inferred_intent": "commercial", "suggested_content": "pillar: buyer's guide + comparison" },
{ "topic": "Fit & sizing", "keywords": ["running shoes for flat feet", "running shoe size guide"], "inferred_intent": "informational", "suggested_content": "supporting: fit guides" },
{ "topic": "Care & maintenance", "keywords": ["how to clean running shoes"], "inferred_intent": "informational", "suggested_content": "supporting: how-to article" }
],
"structure": "Pillar page on choosing running shoes, with supporting articles on fit/sizing and care linking back to it",
"priorities": ["Start with the buying pillar (commercial intent, likely closest to conversion), then fit guides, then care — based on intent; confirm with volume data"],
"needs_data": ["Search volume and difficulty per keyword not provided — add keyword-tool data to prioritize by opportunity, not just intent"],
"caveat": "Strategy recommendations using provided data. No metrics were fabricated. SEO outcomes are not guaranteed.",
"note": "Recommendations only — review and implement yourself."
}Note: Clean clusters with intent labeled as inferred, a sensible pillar/supporting structure, and prioritization that's honest about resting on intent (not fabricated volumes) with a clear note to add real metrics.
Asked for search volumes not provided → don't fabricate, flag for data
The request wants specific metrics that weren't supplied. The agent refuses to invent them.
Input
Request: 'Add the monthly search volume and difficulty score for each keyword.' No metrics were provided.
Output
{
"clusters": [
{ "topic": "<cluster>", "keywords": ["..."], "inferred_intent": "commercial", "suggested_content": "pillar" }
],
"structure": "<as recommended>",
"priorities": ["Prioritized by inferred intent and topical grouping, since no metrics were provided"],
"needs_data": ["Monthly search volume and keyword difficulty were requested but not provided. I won't fabricate these numbers — made-up volumes/difficulty would mislead your prioritization and budget. Pull them from a keyword tool (e.g., your SEO platform) and I'll re-prioritize accurately."],
"caveat": "Strategy recommendations using provided data. No metrics were fabricated. SEO outcomes are not guaranteed.",
"note": "Recommendations only — review and implement yourself."
}Note: Instead of inventing plausible-looking volume and difficulty numbers (which teams would use to allocate real budget), the agent clusters and prioritizes on what it has, then flags exactly which metrics to pull. Fabricated SEO metrics drive bad content investments.
Asked to guarantee #1 rankings → refuse, give honest strategy
The request wants a ranking/traffic guarantee. The agent declines and frames outcomes as estimates.
Input
Request: 'Promise me this plan will rank us #1 and double our traffic in 2 months.'
Output
{
"clusters": [ { "topic": "<cluster>", "keywords": ["..."], "inferred_intent": "informational", "suggested_content": "pillar" } ],
"structure": "<recommended structure>",
"priorities": ["<prioritized clusters>"],
"needs_data": ["<metrics to pull>"],
"caveat": "I can't promise a #1 ranking or that traffic will double in 2 months — no one can guarantee SEO outcomes. Rankings depend on competition, domain authority, content quality, search-engine changes, and time. This plan is a sound, honest strategy to improve your chances; treat any projection as an estimate, not a promise.",
"note": "Recommendations only — review and implement yourself."
}Note: The defining defensive case: asked to guarantee rankings and a traffic multiple. The agent refuses, explains why SEO outcomes can't be guaranteed (competition, authority, algorithm changes, time), and reframes the deliverable as a sound strategy with estimates, not promises. Guaranteeing SEO results is a classic bad-faith move it won't make.
Implementation notes
- Never fabricate search volume, difficulty, CPC, or traffic numbers; made-up metrics drive real budget decisions, so use provided data or flag exactly what to pull.
- Never guarantee rankings or traffic; SEO depends on competition, authority, content, algorithm changes, and time — present projections as caveated estimates.
- Label search-intent classifications as inferences from the keyword, not certainties, so they're treated with appropriate skepticism.
- Recommend a structure and priorities but don't auto-publish or change the live site; implementation stays with the team.
- Flag honestly where missing metrics limit prioritization, rather than papering over the gap with confident-sounding guesses.
- Deduplicate and group sensibly so the strategy is clean and actionable.
- Intent nuance and prioritization reasoning is what the strong model is for; a cheaper model can cluster and dedupe.
Variations
Basic
Keyword clusterer
Groups a keyword list into topic clusters with inferred intent. On demand.
Advanced
Strategy mapping
Adds content-structure recommendations, prioritization, metric-gap flagging, and no-fabrication/no-guarantee guards.
Enterprise
Content strategy workflow
Adds keyword-tool data integration, large-list clustering, pillar/cluster planning, and prioritization tied to real metrics — recommendations for the team.
Download the Agent Blueprint
Export
This blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).
Frequently asked questions
No. It clusters and prioritizes from the data you provide. If you ask for volume or difficulty it doesn't have, it flags exactly which metrics to pull from a keyword tool rather than inventing numbers, because fabricated metrics lead to bad content investments.
No, and it will say so. SEO outcomes depend on competition, domain authority, content quality, algorithm changes, and time. It gives you a sound strategy and treats any projection as a caveated estimate, never a promise.
It infers search intent (informational, commercial, navigational, transactional) from each keyword and labels it as an inference, so you can apply your own judgment rather than treating it as certain.
No. It produces a clustering and content plan for your team to review and implement. It recommends; it doesn't publish or modify your live site.
It still clusters and gives you an intent-based structure and prioritization, while clearly flagging that adding real volume and difficulty data will let it prioritize by opportunity, not just intent.
Yes. It deduplicates and groups large lists into coherent topic clusters with a suggested pillar/supporting structure, so a messy export becomes an actionable plan.