Structured Outputs for AI Agents: Schemas a Harness Can Validate
Learn how to define output schemas for AI agents so a harness can validate results and reject malformed data before it reaches billing, email or systems.

A structured output is an agent result with a fixed shape: named fields, declared types, required values and closed lists of allowed options, written so a machine can check it before any other system reads it. To make that check useful, define one schema for each action the agent may produce, have the harness reject any result that does not match, and send rejected results to a retry or a person instead of downstream. The sections below explain how to write those schemas and what the harness should do when one fails.
Key takeaways
- Define one output schema per action the agent can take, not one loose format for everything.
- Check types, required fields and allowed values in the harness before any system receives the result.
- Treat a failed validation as a stop with a logged reason, never as text to repair silently.
- Version each schema and test it against real past cases, including the ones that went wrong.
- Start with the action whose damage would be largest if one field were wrong.
Why free text becomes a risk once software depends on the answer
When an agent answers in prose, a person can read the reply and fill in small gaps. A billing system, a calendar, a CRM or an email sender cannot. It needs an amount in the right field, a customer identifier that exists, a date in one declared format and a status taken from a known list. If the agent writes around the second week or places a customer name where an identifier belongs, the next step either fails in a confusing way or succeeds against the wrong record.
Language models produce plausible text, so a result can look correct and still be unusable. The OWASP Top 10 for LLM Applications lists improper output handling as a risk category for this reason: model output passed onward without checks can trigger actions in other systems. A schema is the simplest place to start closing that gap, because it turns a vague hope that the answer is right into a test that runs every time.
Design the schema around the action, not the model
Start from what the downstream system will do with the result. It might send a message, create or update a record, book a slot, change a status or write a file. Each of these has its own required inputs. A reminder action needs a recipient reference, a template code, a send window and a reason code. A status update needs the record identifier, the previous status, the new status and a reference to the evidence the agent used.
Write one schema per action. Avoid a single result object that carries every possible field marked optional, because optional fields hide missing information. A small schema is easier to test, easier to review and easier to version when the business changes. Anthropic's engineering notes on writing tools for agents make a similar point about tool definitions: the clearer the parameters and their purpose, the fewer wrong calls the agent makes.
Field rules that catch real errors
Most useful validation comes from a short set of rules applied field by field:
- Type: a quantity is a number, a date is a date in one declared format, and an identifier is a string that matches a known pattern.
- Required: mark a field required when the downstream action cannot run without it, and forbid the agent from inventing a placeholder to fill it.
- Allowed values: use a closed list for statuses, channels and reason codes, so a new or misspelled label fails loudly.
- Limits: set minimum and maximum values, and a maximum length for any free text that will reach a customer.
- References: require an identifier the harness can look up, so the action targets a real record instead of a name the agent remembered.
- Evidence: for every change, include the source reference the agent relied on, so a reviewer can check the basis.
A schema does not decide whether content is wise. A well-formed message can still be the wrong message, and those judgments belong in approval rules and recurring evaluations. The AI agent guardrails for business guide explains which controls to add first.
A step-by-step plan to write and test a schema
Work through this sequence for one action before you move on to the next:
- Name the action, the trigger that starts it and the system that receives the result.
- List the minimum fields that system needs, with the type, format and whether each one is required.
- Replace every free-text field that drives a decision with a closed list of values.
- Assemble a set of past cases, deliberately including several that were handled badly before.
- Run the agent against those cases and record which outputs fail validation and the rule each one broke.
- Confirm that every failure maps to a schema rule, and have a person review the outputs that pass to confirm they are also correct for the business.
- Version the schema, write a short release note and test the new version in a staging copy before production.
The last two steps matter most. A schema that passes the tests but lets through a wrong customer is only partly finished. The AI task contract guide shows how to turn the same cases into a contract your team can run again after every change.
What the harness does when validation fails
Rejection needs a defined path. A failed result should never reach the downstream system, and it should never be quietly edited until it passes. A common pattern is one retry in which the harness sends the validation error back to the agent with the original request. This often fixes a missing field or a wrong format. If the retry also fails, the task goes to a review queue with the original output, the schema version, the rule that failed and the input that produced it.
Repeated failures on the same action are a signal to change the prompt, the tool or the schema, not to loosen the check. Retries also need care with side effects. If a result passes but the send fails halfway, a retry must not send twice. Stripe's documentation on idempotent requests describes one provider's approach to making repeated calls safe, and the same principle applies to any action an agent triggers: the receiving system should be able to recognize a duplicate.
Illustrative scenario: a reminder agent that nearly sent the wrong message
The following is an illustrative scenario, not a description of a real client. A small accounts team lets an agent draft and queue payment reminders. In the first version, the agent returned a sentence containing the customer name, the overdue invoice and a suggested send day. A person copied that sentence into the sender, and the customer name was close enough to another customer's name that the wrong reminder could have gone out.
In the revised version, the agent returns a customer identifier, an invoice identifier, a template code from a closed list and a send window. The harness rejects any result where the invoice does not belong to the customer, and it rejects any result whose template code is not on the list. In testing, the schema exposed a case where the lookup tool returned an invoice from a closed account. The fix was in the lookup tool, and the schema is what made that mismatch visible before a message was queued.
Where Be Human's managed approach fits
Be Human designs, implements and operates this layer as part of personalized AI infrastructure. A first engagement starts by choosing one useful role, then defining the output schema for each action that role can take, the approval boundary for actions that need a person and the success criterion the harness can observe. Managed operations keep those schemas working over time: monitoring validation failures, running recurring evaluations against past cases, maintaining the integrations that receive results, reviewing permissions when a schema changes and handling incidents when a bad output comes close to a live system. Changes ship as controlled, versioned updates, so each one can be reviewed and reversed. Teams weighing whether to run this themselves can compare the ongoing work in managed AI services or your IT provider.
If you are not sure which of your agent tasks should get a strict schema first, take the free Be Human AI diagnostic to find the first task worth handing to an agent.
Frequently asked questions
What is a structured output for an AI agent? It is a result that follows a fixed format with named fields, declared types and allowed values, so software can read it without guessing. A harness checks each result against the schema before any downstream system acts on it. The purpose is to make wrong or incomplete results visible at the boundary, where they are cheap to catch.
If the model already returns JSON, do I still need a schema? Yes. Valid JSON only proves the syntax is correct, not that the values make sense. A schema adds required fields, allowed values, ranges and references to records that must exist, and those checks catch errors that a syntax check cannot.
Which schema should I write first? Begin with the action where a wrong field would do the most harm, usually one that changes money, customer records, outbound communication or access permissions. Get that schema tested against real past cases before writing the others. The first one teaches your team how to write the rest.
Who should own the schemas? The operations owner should define what each field means and which values are allowed, while the technical owner enforces the checks and manages versions. Both should review any change before it reaches production. Be Human's managed operations can maintain these schemas, monitor failures and review changes as the business evolves.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


