Structured Data Agents
A structured data agent is text-to-SQL that gets to try again. It runs its query, reads the error or the empty result, and rewrites the query until the database confirms the answer.
Why Does This Exist?
Ask a single-shot text-to-SQL setup "How many customers are in California?" and it writes one query, runs it once, and believes whatever comes back. If the table stores two-letter codes, the query says state = 'California', the database returns 0 rows, and the model tells you there are no customers in California. Confident. Wrong.
That is the failure this page is about. Not broken SQL grammar, but a correct-looking query against values the model never checked. Real tables are full of these traps. Codes instead of names. Dates stored day-first. A column called dept_name where you guessed department. One guess can't survive that.
A structured data agent survives it by refusing to guess once. It inspects the schema, samples a few rows, runs a query, reads what the database sends back, and rewrites. Every database reply is evidence, including the empty ones.
The one idea you need first: the loop it runs is Thought, Action, Observation. The model thinks out loud, takes one database action, reads the result, then thinks again. That loop is the ReAct pattern, and this page is what happens when you point that loop at a database. The single-shot baseline it replaces is text-to-SQL.
Think of It Like This
The shopkeeper who checks the shelf
You ask a shopkeeper for California oranges. A lazy one shouts "none" without looking. A good one walks to the shelf, finds nothing under that sign, reads the nearby labels, spots a crate marked CA, and comes back with your oranges.
The walk is the schema inspection. Reading nearby labels is sampling rows. The empty spot where you expected oranges is the 0-row result, and the good shopkeeper treats it as a clue instead of an answer.
Where it stops: the shopkeeper knows the shop. Your agent knows nothing except what its tools return. Point it at a stale copy of the table and it retries its way to a confident wrong answer, same as the lazy one, just slower and more expensive.
How It Actually Works
Three tools, one loop. The agent can inspect the schema (which columns exist), sample rows (what the values look like), and execute SQL (what a query returns). At each step t it produces a Thought, takes one Action through a tool, and reads back an Observation. In plain words: t is the attempt number, the Action is one tool call, and the Observation is whatever the database sent back, error text and empty results included. The loop stops when an Observation confirms an answer or a stop rule fires.
The loop in four moves
- Question in: "How many customers are in California?"
- Look before querying: inspect
customers, then sample 5 rows. - Try, then read the reply: run the SQL and treat whatever returns as evidence.
- Retry with what you learned, or stop: rewrite once the reply exposes the mistake, and never report an unchecked 0.
Worked example
The customers table holds 200 rows: 142 with state = 'CA', 40 with 'TX', 18 with 'NY'. Check the total: 142 + 40 + 18 = 200.
Try 1 runs WHERE state = 'California'. Nothing matches that literal, so the Observation is 0 rows. A single-shot pipeline answers "zero" right here. The agent doesn't.
It samples 5 rows and sees CA, TX, CA, NY, CA. Three of the five are CA. The column holds two-letter codes, so 'California' could never match. That diagnosis comes straight from the data, not from the model's memory.
Try 2 runs WHERE state = 'CA' and gets 142 rows. Share check: , so about 71% of customers. Final answer: 142 customers in California.
The diagram above carries these same numbers: 0 rows, the five-row sample, 142 rows.
Why this costs more, and when to skip it
Every retry is another model call plus another query, so an agent turn costs several times a single shot. That is the trade. When a question gets asked daily against a known table, save the corrected query behind a button and skip the agent entirely. A dashboard is cheaper, faster, and deterministic. The agent is worth it on questions nobody saved yet.
It also rests on two assumptions: read-only access and a stable schema during the turn. Break the first and a curious agent can write as well as read, so hand it credentials that can't. Break the second and a mid-turn schema change silently invalidates everything it learned.
Code
What follows replays the worked example with no model involved: 200 in-memory rows, the same miss, the same five-row sample, the same fix. Read it as the skeleton of the loop.
CODES = {"california": "CA", "texas": "TX", "new york": "NY"}
customers: list[str] = ( ["CA", "TX", "CA", "NY", "CA"] + ["CA"] * 139 + ["TX"] * 39 + ["NY"] * 17)
def count_where(state: str) -> int: return sum(1 for s in customers if s == state)
def answer(state_word: str) -> int: got = count_where(state_word) if got == 0: # an empty result is evidence, not an answer got = count_where(CODES[state_word.strip().lower()]) return got
print(len(customers)) # -> 200print(count_where("California")) # -> 0print(customers[:5]) # -> ['CA', 'TX', 'CA', 'NY', 'CA']print(answer("California")) # -> 142print(round(100 * count_where("CA") / len(customers), 1)) # -> 71.0The retry rule is three lines: never answer from an unchecked empty result, look at the values, then query the code you actually saw. Everything else in a production agent is scaffolding around that rule.
Watch Out For
Reporting 0 rows as the answer
Symptom: the agent says there are 0 customers in California and stops after a single tool call. The trace shows one WHERE state = 'California' with no schema or sample call before it.
The model treated an empty result as a fact instead of a clue. Fix it in the instructions: an empty result must trigger a value check, sampling the column's distinct values, before any answer. Cap retries at two or three attempts, then the agent must ask you instead of guessing again.
Fetching the whole table into the prompt
Symptom: one unfiltered SELECT drags thousands of rows into the Observation, and the turn dies on context limits or crawls. You will spot it as a giant Observation in the trace, dwarfing everything else.
Fix it with tool result curation: cap previews to a small number of rows, reach for COUNT(*) before reading values, and require a LIMIT on every exploratory query. If the agent wants specifics, it writes a tighter WHERE, not a wider net.
The Quick Version
- A structured data agent queries in a loop: inspect the schema, sample rows, run SQL, read the reply, rewrite.
- An empty result is evidence, not an answer. The classic miss is
state = 'California'returning 0 rows when the column holdsCA. - Five sampled rows can diagnose the miss:
CA, TX, CA, NY, CAshows the column holds codes, so the retry targetsCAand returns 142. - Each retry costs another model call, so save repeated questions as fixed queries and keep the agent for the new ones.
- Hand it read-only credentials and cap its result sizes, or its curiosity becomes your incident.