Structured outputs: making agents return clean JSON every time

The day the booking bot broke. Picture a small hair salon. The owner built an agent that reads booking requests from WhatsApp and adds them to a spreadsheet. For two weeks it worked beautifully. Then one evening the model got chatty. Instead of clean data, its chat bubble said, sure, here's the booking, followed by a friendly paragraph. The next step expected neat fields, got a story instead, and stopped. Three clients sent requests that night and none of them landed in the spreadsheet. Nobody noticed until they showed up. This lesson is about making sure that never happens to you. We'll make the agent return clean, predictable data every single time.

What you will learn. By the end of this lesson you'll be able to do three things. First, explain what JSON is and why every automation tool prefers it over normal sentences. Second, write a schema, which is a description of the exact fields you expect, and pair it with prompt rules the model actually follows. Third, add a safety net: switch on your tool's strict output mode, check every reply, and when one is broken, send it back to the agent with the error so it can fix itself. These three pieces together turn a chatty assistant into a reliable worker inside your business.

JSON is a form, not a letter. JSON stands for JavaScript Object Notation, but you can forget the name. Think of the difference between a letter and a form. A letter says, hi, I'm Sara, and I'd love a haircut on Thursday afternoon. A person can read that, but a machine struggles. A form has labelled boxes: name, Sara; service, haircut; date, the eighth. JSON is that form written as text. Each field has a name in quotes, a colon, and a value. Because the structure is always the same, the next step in your workflow can grab the date field without guessing where it is in a sentence.

Why models drift from the format. Why does a model wander off format at all? A language model predicts the most likely next words, one after another. After a customer message, polite chatter is very likely, so the model sometimes wraps your data in extra paper, like a robot gift-wrapping a box. You'll see four kinds of breakage. Extra sentences before or after the data. Code fences, those triple backticks that look nice in chat but break a parser, the step that reads the JSON into separate fields. Missing fields. And the worst one, invented values, where the model guesses a time the customer never gave. Each of these has a fix, and we'll go through them in order.

Step one: write the schema. The first fix is a schema, a precise description of the reply you want. Here's one for our salon. Name is plain text. Service must be one of three choices. Date uses year, month, day with dashes, so the eighth of October twenty twenty-six becomes twenty twenty-six, ten, zero eight. Time uses hours and minutes in twenty-four hour form. Intent is one of four fixed words, which we call an enum, short for enumeration, simply a closed list of allowed values. Closed lists are powerful. Your next workflow step can route on intent with four clean branches instead of trying to understand free text.

Step two: rules in the system prompt. The schema goes into the system prompt, along with a few blunt rules. Return only JSON that matches the schema. No greetings, no explanations, no code fences. If a value is not in the message, use null, which is JSON's word for empty or unknown. That one rule stops invented appointment times. Next, tell the agent today's date. Why does that matter? Customers write next Thursday, not a calendar date. Even then, said on a Friday, next Thursday could mean the eighth or the fifteenth. So the prompt also fixes the meaning: next Thursday is the first Thursday after today. If the prompt says today is Friday the second of October, the model turns next Thursday into the eighth. Without these rules, the model simply guesses.

Worked example: Sara's message. Let's try it. Sara writes, hi, can I get a haircut next Thursday around four p m. The agent returns this reply. Notice the name is just Sara. She gave no surname, so the agent did not invent one. Now we check the reply, and you need no code for this. First, can it be read as JSON at all, with no chatter around it? In n8n, the Structured Output Parser does that step for you. Then three plain checks. Are all five fields present? Is intent one of our four allowed words? Are the date and time in the exact formats? An IF node or a Filter node does each check in n8n, Make or Zapier. Everything passes, so we get a clean booking: Sara on the eighth of October at sixteen hundred. That line is ready for the spreadsheet or the calendar.

Step three: validate and retry. Rules reduce errors, but never to zero, so we add a loop. The customer message goes to the agent. Its reply is parsed and checked, exactly like the checklist we just used. If it's valid, it goes to the booking sheet. If not, we send it back to the agent with the precise problem, for example, field time is missing, or intent was confirmed, which is not allowed. Models fix a named error very well. Cap it at two retries, because each retry costs money. If it still fails, don't loop forever. Send the message to a person and let them book it by hand.

Let the tool enforce the format. Here's a shortcut. Many model providers now offer a structured output mode, where you hand them the schema and the model is forced to produce matching JSON. In n8n you connect a Structured Output Parser to the AI Agent node and paste your schema or an example. Make and Zapier have similar options in their AI modules. Turn these on whenever you can, because they remove most formatting failures before they happen. But keep your validation step. A strict mode guarantees the shape, not the sense. It can still give you a perfectly formatted date in the wrong week.

Common mistake: loose fields. The most common mistake is a field that's named but not described. The schema says date, and the agent returns next Tuesday, or Tuesday at four, like a sticky note on the calendar. It's valid JSON, so the parser is happy, but your calendar step can't book next Tuesday. The same happens with prices written as forty dollars instead of forty, or a status of yes please instead of true. The fix is boring and reliable. Give every field an exact format, give the agent today's date, use closed lists wherever choices are limited, and allow null for anything unknown.

Recap. Let's pull it together. First, JSON is a form, not a letter: labelled fields that the next step in your automation reads without guessing. Second, you shape the reply with a clear schema and a few blunt prompt rules: only JSON, exact formats, closed lists, null when unknown, and today's date for relative dates. Third, you never trust a reply blindly. Parse it, check it, send errors back for at most two retries, and hand anything still broken to a human. Use your tool's strict output mode on top of all that, and your agents will stay quiet and reliable.

Your exercise. Now it's your turn. Build a lead qualifier, an agent that reads inquiries from potential clients and decides who's worth a call. Write a schema with five fields: name, email, budget as a plain number or null, urgency from a closed list of now, this month or later, and qualified as true or false. Add the prompt rules from this lesson. Then test it on five inquiries, including one with no budget and one that's vague about timing. Check every reply with the validation steps we used. Bring your results next time, because we'll start measuring what each of those runs costs.