Build an SEO Content-Brief Agent, Step by Step

An SEO content-brief agent turns raw search data into the document a writer actually needs — target queries, intent classification, heading skeleton, entity coverage, mandated links — without a strategist spending an afternoon assembling it by hand. Most tutorials on this topic hand you a prompt template and skip the question that decides whether the agent works at all: where does the input data come from?

That question has three different answers, because a useful brief needs three structurally different inputs. Your own site's performance data comes free from an official Google API. Competitor SERP composition has no official API at any price — you buy it from a third-party vendor operating in a legal gray zone that, since December 2025, includes active federal litigation. And your internal-link candidates come from a registry only you can build.

This guide walks through the full build: the 14-field brief schema the agent must output, each of the three data inputs with real access mechanics and vendor-stated pricing, the prompt design that turns data into a draft brief, and the six QA gates that run before a human writer sees anything. No invented time-savings percentages — the case for this agent is consistency and coverage, and we will make it qualitatively.

The single most common failure in brief automation is asking a model to “write a content brief” with no output contract. You get a different document every run, writers stop trusting it, and the agent quietly becomes shelfware. The fix is to give the agent a fixed schema and score every run against it.

We published that schema in June 2026 as the 14-field content brief this agent automates. The fields: primary query, secondary queries (2–4), search intent type, answer intent target, primary entity, secondary entities, heading skeleton (H1/H2/H3), a word-count target expressed as a range, mandated internal links (3+), mandated external sources (5–7), required E-E-A-T signals, schema markup type(s), a writer/AI handoff checklist, and a named quality-gate approver.

Two of those fields matter more than the rest for agent design. The framework deliberately separates search intent — the SERP-competition classification, read from the content type, format, and angle of what currently ranks — from answer intent — the single extractable declarative sentence written to win a featured snippet or an AI citation. Most legacy templates collapse these into one "intent" field. They have different data sources: search intent is derived from reading the top-10 SERP; answer intent is authored. An agent that conflates them will automate the wrong one.

The first input answers “what does this page already rank for, and where is the opportunity?” — and it is the easy one, because Google provides an official API. The Search Analytics endpoint is a POST to https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query, per Google's API reference. It accepts startDate and endDate (YYYY-MM-DD), a dimensions array — country, device, page, query, searchAppearance, date, hour — plus dimension filter groups, an aggregation type, and a search type covering web, image, video, news, Discover, and Google News.

Response rows carry keys (the dimension values), clicks, impressions, ctr (expressed 0–1.0), and position — the average result position. For a brief agent, the core call filters by the target page and groups by query: the queries where the page earns impressions at positions 5–20 with weak CTR are your primary- and secondary-query candidates. One important scoping note: GSC's position is the average ranking of your own pages. It tells you nothing about who occupies the other nine results — that is a different data type from a different source, covered in the next section.

Quotas, row caps, and error handling

Three operating constraints shape the agent's fetch code. First, the rowLimit parameter accepts 1–25,000 rows per call (default 1,000), paginated via a startRow offset — and Google's docs are explicit that the API does not guarantee returning all data rows, only the top ones. Second, per Google's published usage limits, Search Analytics allows 1,200 queries per minute per site and per user, with project-level ceilings of 40,000 QPM and 30 million queries per day, plus separate short-term and long-term load quotas layered on top. A single brief run will never touch these numbers; a poorly-throttled bulk run generating dozens of briefs can trip the load quota. Third, quota errors surface as HTTP 429 responses with a quotaExceeded reason, and the documented remediation is exponential backoff — your fetch step should retry with increasing delays, not hammer or hard-fail.

The second input answers “what does the current top-10 look like — who ranks, what content types, what headings, what entities?” This is where honest tutorials diverge from the rest: Google offers no API for SERP composition at any price. GSC reports only your own property's metrics; query-level competitor visibility is structurally outside its documented surface. So every content-brief agent that classifies search intent from the live SERP is buying that data from a third-party vendor — or scraping, which we will address squarely in the next section.

Two representative vendors illustrate the two commercial models. All figures below are vendor-stated pricing, retrieved July 2026 — verify current rates before budgeting.

For comparison, the chart below normalizes both vendors to an effective cost per 1,000 SERPs. The subscription figures are derived by dividing each plan's monthly price by its search allowance — they hold only if you use the full allowance, since SerpApi searches expire without rollover — and the models are not perfectly comparable on other axes (queue latency versus real-time, hourly throughput ceilings). The spread is still instructive.

For a brief agent's actual consumption — call it 10 to 30 SERP fetches per brief for the primary query, secondary queries, and a handful of intent-check variants — either model costs very little per brief at these vendor-stated rates. Price is not the deciding factor. The deciding factor is the next section.

Google's terms of service prohibit accessing its services through automated means such as robots, spiders, or scrapers without express advance permission (the terms are revised periodically — read the live text at policies.google.com/terms before relying on any summary, including this one). Third-party SERP-data vendors operate anyway, typically on the argument that the data is publicly viewable in any browser — not that Google has authorized the access method. That gray zone held for years. In late 2025 it stopped being theoretical.

On December 19, 2025, Google filed a federal DMCA lawsuit against SerpApi in the U.S. District Court for the Northern District of California, alleging that SerpApi's automated scraping circumvents “SearchGuard,” a technological protection measure Google deployed in January 2025. Google's complaint alleges SerpApi's scraping volume grew by as much as 25,000% over two years, to hundreds of millions of requests per day — figures worth repeating with their label attached: these are Google's litigation allegations, not independently audited numbers.

SerpApi filed a motion to dismiss in February 2026, arguing — per The Register's reporting on the filing — that it has provided access to public search data for more than eight years and that the data it returns is the same information anyone can view in a browser without signing in. As of this writing the case is active and unresolved. Do not read either side as having won; do check the case's status before you sign a vendor contract, because the outcome could reshape SERP-data-vendor viability in either direction.

The subtler point most buying guides skip: even vendors not named in any lawsuit push the compliance risk downstream. DataForSEO — which is not a defendant in the Google suit — publishes terms that bar using its SERP data to compete with or adversely affect the search engines it collects from, and that require customers to indemnify the vendor against claims arising from violations (verify the current clause wording on its terms page). Read that carefully: the contractual risk of the gray zone lands on you, the customer, not on the vendor selling you the data.

Projecting forward, the pattern this lawsuit fits is bigger than SERP tools: as AI agents industrialize data collection, publicly viewable no longer implies freely harvestable, and platforms are reaching for technological protection measures plus the DMCA rather than relying on terms-of-service claims alone. Architect accordingly — the sane engineering response is to isolate SERP retrieval behind a single interface in your agent so the vendor is swappable in an afternoon, and to keep the GSC and internal-registry stages fully functional even if the SERP stage goes dark. A brief with honest own-site data and mandated links but a thinner competitive section still beats no brief.

The third input fills the brief's “mandated internal links (3+)” field, and it is the one no vendor sells: a machine-readable index of your own published URLs with their titles, topic clusters, and preferred anchor patterns. Without it, the agent either skips the field or — worse — hallucinates plausible-looking internal URLs that 404. With it, link selection becomes a deterministic lookup: filter the registry by the brief's primary entity and topic cluster, rank by relevance, emit the top three-plus with suggested anchors.

The registry can start embarrassingly simple: a JSON or database export of slug, title, category, and tags from your CMS, regenerated on every publish. The stronger version adds what a crawl of your own site reveals — which pages already link to which, where the orphans are, which clusters are thin. We covered that build in an agentic SEO crawler built the same way — the crawler's output is precisely the registry this agent consumes, which is the general pattern worth internalizing: small single-purpose agents that feed each other artifacts beat one monolithic do-everything agent.

Note what this input costs: no vendor fees, no quota, no terms-of- service exposure. First-party data is the only input in this pipeline that gets more valuable and less risky as you scale it — which is an argument for investing here first if you are sequencing the build.

This table is the build spec: every field the brief must contain, where the agent gets it, and how automatable it honestly is. Two fetch passes deserve a design note. The framework separates entity-coverage targets (Clearscope-style breadth — importance-scored entities from an NLP pass across top-ranking pages) from structural targets (Surfer-style — word-count range, heading and paragraph counts derived from ranking competitors). Build those as two distinct steps over the SERP-sourced page set, not one merged “content optimization” call — merging them reproduces the over-optimization failure mode the framework post warns against.

Read the automation column honestly: five fields are fully automatable, six need a human to confirm or trim what the agent proposes, and three are human judgment with at most an agent-drafted candidate. That ratio is the trend worth interpreting — brief automation in 2026 is an assembly problem, not a generation problem. The agent's value is that no field arrives empty, no internal link is invented, and no run skips the SERP read; the strategist's value concentrates in exactly the three fields where it always lived.

With the data layer settled, the prompt layer is straightforward — and deliberately boring. The agent runs as a sequence of scoped steps, each with its own small prompt and its own structured output, rather than one mega-prompt that ingests everything and emits a brief.

Step prompts, in pipeline order

• Query selection (no LLM needed). The GSC fetch plus a ranking heuristic picks the primary and secondary queries. Keep this deterministic — it makes runs reproducible and debuggable.
• Intent classification. Feed the model the top-10 SERP snapshot (titles, URLs, result types) and ask for the search intent as content type, format, and angle — the three-Cs framing — returned as structured output with a one-sentence justification per C. The justification is what your human reviewer sanity-checks.
• Entity pass. Over the fetched top-ranking pages, extract and importance-score entities and concepts. Output: primary entity candidate plus a scored secondary list.
• Structural pass. Separately, compute the word-count range and heading landscape from the same page set, and draft the H1/H2/H3 skeleton — shared headings first, gap headings flagged as differentiators.
• Assembly. A final prompt receives all prior structured outputs plus the registry's link candidates and fills the 14-field schema — with explicit instructions that missing data yields an empty field plus a warning, never a guessed value.

Two design rules keep the output trustworthy. First, force the schema: use structured output so the brief is machine-checkable, and validate it in code after generation. Second, resist the urge to make the agent over-specify. As Semrush's content-brief guidance puts it: “Don't get too granular or rigid with your briefs...give them the broad strokes of what your content absolutely needs to have. And then trust them to do the rest.” The agent assembles mandatory fields; it does not micromanage sentence-level phrasing — that is the writer's craft, and briefs that try to script it get ignored.

This is the same agent discipline we apply in client builds through our agentic SEO service: deterministic where possible, model-assisted where classification or extraction genuinely needs language understanding, and human-owned where the field is judgment.

The final stage is the one that makes the agent trustworthy enough to put in front of a content team. The framework's six-gate handoff checklist was written for humans reviewing briefs; here it becomes the agent's final validation pass, encoded as code that runs after assembly and before anything is surfaced. In priority order:

1. Answer intent satisfied — the brief contains a single, extractable declarative sentence as its answer-intent target (agent checks presence and format; a human authored or approved the sentence itself).
2. Entity coverage met — the primary entity and the scored secondary entities from the NLP pass all appear in the brief's skeleton or coverage notes.
3. Sources cited — five to seven external sources are listed, each with a URL that resolves.
4. Internal links placed — three or more links, every one verified against the registry so nothing invented ships.
5. E-E-A-T signals present — the required-signals field is filled and matches expertise the team actually has.
6. Schema specified — at least one markup type is named and consistent with the classified content type.

A brief that fails any gate never reaches the writer — it loops back with the failure attached, or lands in a review queue with the gap flagged. That failure behavior is the entire point. We will not claim a percentage time saving here, because we have no defensible number to cite and this agent's benefits are qualitative: every brief arrives complete against the same 14-field contract, internal links stop being invented, the SERP actually gets read on every run, and the strategist's review shrinks to the three judgment fields instead of the whole document. Downstream, the briefs this agent emits are what a production pipeline like our content engine consumes — and if you later want to measure whether the published pages earn AI-search visibility, that is a separate measurement problem we covered in an AI-search-visibility agent using the same MCP pattern.