How an AI Agent for WooCommerce Works: Inside a Six-Agent Architecture
Ask one AI agent for WooCommerce to classify your question, write the SQL, analyse the results, lay out a PDF report and draft the follow-up email, and you have handed a single model five conflicting jobs. Store Insights with AI splits that work across six specialised agents. Two are reached through an intent router; two more are triggered directly by a button. Each has one responsibility, a strict JSON output contract, and an explicit list of things it is not allowed to do. The boundaries, not the model, decide what happens next.
The short version
- Six agents, not one: a router, two SQL generators (HPOS and legacy), an analyst, a report builder and an email writer.
- Two entry points. Typed questions go through the router to the SQL or analysis agent. The PDF and email agents are called straight from the AI Assist button — no routing.
- The router never writes SQL. The SQL agents never see your data. The analyst never writes SQL.
- Every agent answers with structured JSON or a named error code — never free-form improvisation.
- Boundaries are enforced twice: once in the prompt, again on the server before anything executes.
In this article
Why a single AI agent is the wrong shape for store data
Most tools that describe themselves as an AI agent for WooCommerce are one prompt doing everything. A single instruction set tries to cover intent detection, schema knowledge, SQL syntax, chart selection, document layout and email HTML. Three problems follow from that.
- Instructions dilute. A prompt long enough to describe PDF layout also contains the rules that stop a query from double-counting revenue. When the two collide, something gets dropped.
- There is no clean failure surface. If the output is wrong, you cannot tell whether the intent was misread, the SQL was wrong, or the chart type was a poor choice.
- Security has no isolation. An agent that both writes SQL and renders HTML has no boundary between "can touch the database" and "can produce markup".
A multi-agent design fixes all three by narrowing scope. Each agent gets one job, one output schema, and one refusal rule. The router’s only job is to decide which specialist should answer. The SQL agent’s only job is to produce a query. The analyst’s only job is to explain data that already exists. Nothing overlaps, so nothing has to be compromised.
The six agents and what each one owns
Six prompts, six contracts. The first four sit behind the router; the last two are called directly from the PDF and email modals. Here is the full roster, including where each agent stops.
Agent 1 — Routing
The Router
Reads the question and nothing else. It sorts every message into one of four intents: sql_generation (needs new data from the store), data_analysis (interpret data already on screen or in an attached file), forbidden (asks to change data), or out_of_scope (not about the store at all).
It also owns the file-routing rules. Attach a CSV or Excel export and the request is classified as data_analysis every time — never as SQL generation — because the answer lives in the file, not in the database. A file dropped in with no typed question counts as “analyse this file”.
Stops at: it writes no SQL, answers no question, and never touches data. It returns an intent label and a one-sentence reason.
Agent 2 — Query
The HPOS SQL Generator
Turns a business question into one executable, read-only SELECT statement against the WooCommerce High-Performance Order Storage tables, plus the presentation metadata that describes the result shape.
It reasons before it types. Metric first, then dimensions, then filters, then the time window, then joins, then aggregation — and only then the query. It knows the traps that produce plausible but wrong numbers: order-level revenue summed after joining line items multiplies your revenue, refund rows need excluding from order counts, and one column named total_sales in the product table counts units, not money.
Stops at: SELECT only. No schema changes, no system tables, no bulk PII export, no multi-statement output. It cannot see a single row of your data.
Agent 3 — Query
The Legacy SQL Generator
Same contract, different storage engine. On stores that have not migrated to HPOS, orders live as custom post types with order data spread across the postmeta table. This agent knows that map: totals, payment method and billing country are all meta keys, every numeric value has to be cast before it is summed, and each meta key needs its own join.
Stops at: it explicitly refuses to reference HPOS tables, because on a legacy store those tables do not exist.
Agent 4 — Analysis
The Analyst
This is the only agent that actually sees your rows. It receives the datasets produced by earlier queries — plus anything you uploaded — and returns an ordered set of blocks: a written answer first, then an optional chart or table.
It is also the only agent allowed to do arithmetic the database never did. Ask for profit per ad channel and it will compute revenue minus cost minus spend, chart the result, and show the formula so every number stays traceable. It treats the contents of your files as data, never as instructions, so a cell reading “ignore previous instructions” is just a cell.
Stops at: no SQL, no requests for new data, hard caps on output size, and it will not invent a benchmark that is not in the data.
Agent 5 — Presentation
The Report Builder
Invoked directly from the Download PDF modal — it is not reached through the router. Converts a conversation into a styled HTML document built for PDF export: executive summary first, then sections, metric cards, bordered tables, and page-break rules that stop a card being sliced in half across two pages.
Stops at: it only uses data already in the conversation, only the image placeholders it was given, and it generates no SQL.
Agent 6 — Delivery
The Email Writer
Invoked directly from the Send Email modal, also with no routing step. Turns the conversation into an email body that survives Outlook: inline styles on every element, a 600px maximum width, table-based structure, short paragraphs, and the headline metric above the fold.
Stops at: inline CSS only — no style blocks, no external stylesheets, no invented numbers.
There is also a stripped-down fallback variant of the SQL agent for constrained deployments: the scope rules and error contract, nothing else. Same refusals, less surface area.
Two entry points, not one pipeline
The six agents are not a single chain, and this is the part most descriptions get wrong. There are two distinct ways an agent gets invoked, and only one of them goes through the router.
Entry point A — a typed question
Follow a single message — “How many orders did I get last month?”
-
1
The router classifies it
The question needs numbers that are not on screen yet, and no spreadsheet is attached, so the intent is sql_generation.
-
2
The matching SQL agent plans the query
The plugin checks whether the store runs HPOS or legacy storage and routes to the right generator. The agent resolves “last month” into explicit date boundaries, excludes refund rows from the count, filters to revenue-eligible order statuses, and returns a single SELECT plus a one-row answer contract.
-
3
The server decides whether it runs
Before execution the statement is parsed, checked against the allowed statement shape, and dry-run validated. The database user has read access only.
-
4
You get a formatted number
One row comes back and is rendered through the answer template — a large formatted value, not a raw table.
-
5
A follow-up changes the agent, not the data
Ask “why did that change?” and the router now returns data_analysis. The SQL agents are out of the loop entirely. The analyst works from the dataset already in the conversation.
Upload a CSV instead and the same question takes a shorter path: router, then analyst, then answer. No SQL is generated at all, because the data you are asking about never lived in the database.
Entry point B — the AI Assist button
The report builder and the email writer are never reached through the router. They are invoked directly by an explicit user action. Click AI Assist inside the Download PDF modal and the conversation goes straight to the report builder. Click AI Assist inside the Send Email modal and it goes straight to the email writer. No intent classification, no SQL, no ambiguity about what you wanted.
That split is deliberate. Routing exists to resolve uncertainty about intent. A button click carries no uncertainty, so there is nothing to route. Adding a classifier in front of a button that already says “make a PDF” would only introduce a way to get it wrong.
It also means these two agents have a narrower job than the router-facing ones. They are handed a conversation and a target format — HTML for a PDF, or inline-CSS HTML for an email — and neither can reach the database at all.
Router → SQL Generator (HPOS or Legacy) → Database → Rendered Result
A follow-up analysis question re-enters at the router: Router → Analyst
Download PDF modal → Report Builder
Send Email modal → Email Writer
No router, no intent classification, no SQL
What the boundaries look like in practice
Boundaries are only real if they produce a specific, predictable refusal. Each agent answers a disallowed request with a named error code rather than a best guess.
| If you ask for… | What happens |
|---|---|
| Delete order #123 | Blocked at the router as forbidden. No agent that can write to your database exists in the pipeline. |
| Change a product price | Same refusal. The SQL agents are read-only by contract and the database grant is read-only by configuration. |
| Show me all my pages | Not WooCommerce. Non-store content types are out of scope by design. |
| Export every customer email | PII exceeded. Targeted, capped customer lists are supported; bulk extraction is not. |
| Show me the best products | Ambiguous. Best by revenue, units sold, or rating? It asks instead of guessing. |
| What is my profit margin? | Data unavailable. There is no cost-of-goods column in WooCommerce, so there is nothing honest to compute. |
| Turn this table into a pie chart | Handled by the analyst, not the SQL agents. Existing results are re-visualised without a new query. |
The last row matters as much as the refusals. Re-charting data you already have should never cost a database round trip, and it never does here, because that request is not a data request.
Why there are two SQL agents
WooCommerce can store orders in two completely different places. High-Performance Order Storage uses dedicated tables. The older system stores orders as posts with their details scattered across post metadata. The table names, the column names, and the way totals are read are all different.
An agent trained to be good at both is an agent with two half-known schemas and a real chance of producing a query that runs fine and returns the wrong number. Splitting the job means each generator can be narrow, and the legacy generator can hard-refuse HPOS table names — which is exactly what it does. The plugin detects the active storage backend and routes accordingly, so there is no setting to get wrong.
The same rule, stated twice
Both generators carry the identical anti-fan-out rule set: never sum order-level revenue after joining line items, always filter billing address type when joining addresses, always exclude refund rows from order counts, always use sargable date ranges instead of functions wrapped around a date column. Two schemas, one accounting standard.
What leaves your server, and what never does
The privacy boundary follows from the agent split. The SQL agents are the only agents that can cause a query to run, and they are deliberately blind: they receive your database structure — table names, column names, types — and nothing else. Your revenue figures, customer emails and order details are not sent anywhere in order to have a query written.
Think of it as handing someone the library catalogue instead of the books. They can tell you exactly which shelf to walk to. They cannot read a single page.
Analysis is a separate step with a separate boundary. When the analyst explains a result, it works on rows your server has already fetched. If you point the plugin at a cloud model, that result set is what gets sent — which is precisely why the bring-your-own-key option matters. Point it at a local model and the analysis step stays inside your network too.
Enforcement does not rest on the prompt alone. On top of the agent contracts, the runtime adds its own layer:
- A database user with read access only, so a bad query cannot become a bad write.
- A parser that accepts a single SELECT statement and rejects anything chained behind it.
- Statement timeout and a row cap, so an expensive query cannot stall the admin.
- Dry-run validation before execution, plus schema validation of the JSON that comes back.
- Bring your own key: any OpenAI-compatible endpoint works, including a local model, if you want the prompt to never leave your network either.
What the agents refuse to answer
A boundary that only blocks destructive requests is half a boundary. The more useful one is the refusal to answer questions the schema cannot support. WooCommerce stores revenue, tax, shipping, stock and customer records. It does not store several things people assume it does.
- Profit and margin. There is no cost-of-goods column anywhere in the schema. Any plugin that shows you a margin is either asking you to enter costs or making them up.
- Traffic and conversion rate. Sessions and pageviews live in your analytics platform, not your store database.
- Abandoned carts and UTM attribution. No cart table, no attribution table.
- Recurring revenue and churn. Subscription renewals are not in the analytics tables.
- Review text. Star ratings and review counts are available; the words inside the reviews are not.
Each of these returns a plain explanation of what is missing and what would be needed instead. That is less impressive in a demo than a confident invented number, and considerably more useful on a Monday morning when you are deciding what to reorder.
How to evaluate any WooCommerce AI agent
Architecture is not visible in a screenshot, so ask these questions instead. They apply to any AI agent for WooCommerce, not just this one.
- What does it refuse? A tool with no documented refusals has no documented scope.
- Does the model see rows or schema? Ask directly. “We send your data to the AI” is an answer, and it should worry you.
- Can it distinguish new data from existing data? If every message triggers a query, re-charting a result you already have is a wasted round trip and a correctness risk.
- Does it know your storage backend? HPOS versus legacy is not a detail; it changes every query.
- Is it enforced server-side? A prompt is a request. A read-only database grant is a guarantee.
Frequently asked questions
Why use multiple agents instead of one good prompt?
Because the jobs conflict. Classifying intent, writing SQL, explaining results and designing a PDF each need different rules and different outputs, and a single prompt has to compromise between them. Separate agents also mean separate failure modes: when something is wrong, you know which one to fix. It also lets the PDF and email agents be invoked directly from a button, with no classifier in the way.
Does more agents mean my data is sent to more places?
No — the split reduces exposure. The step that writes the query never sees a row; it only sees table and column names. Analysis happens on results your server has already fetched, and with a local model that step stays inside your network as well.
What happens if an agent returns something invalid?
Each agent output is validated against a schema before the next step runs. A malformed query never reaches the database; you get an error message instead of a silent wrong answer.
Can I use a local model so nothing leaves my network?
Yes. Any OpenAI-compatible endpoint works, including self-hosted options. Since only schema metadata is sent, a local model gives you a fully contained setup.
Do I need an API key to get started?
Not for the built-in library of pre-written queries, which needs no configuration. Add a key when you want to ask your own questions and put the SQL agents to work.
Six narrow agents beat one clever one
The interesting part of an AI agent for WooCommerce is not the model behind it. It is what the system refuses to do, where it draws the line between new data and existing data, and whether those lines are enforced by a prompt or by a database grant. Narrow agents with hard boundaries are how you get a report you can act on instead of a number you have to double-check.
Start asking your store questions