Add a parser to an agent and it answers with JSON that follows a schema you define, instead of free text. Use a parser whenever code reads the answer: a function in a workflow, a database insert, your application.
A parser
The model sees every field’s description, so write descriptions as instructions: what the field holds, its format, and what to return when the value is not there.
Field types
Choosing from a fixed set: enum or literal
Use enum when the values speak for themselves:
Use literal when each value needs explaining. The descriptions are added to the field’s instructions, which noticeably improves accuracy for judgement calls:
literal values must be {value, description} objects. A plain list such as values: [SAME, DIFFERENT] is rejected with a validation error. Use enum for plain values.
Objects and lists
An array describes one element in items. An element can be a primitive (type: str) or an object with its own fields, and objects can nest further.
Missing values
Every field is requested. Tell the model what to return when a value is absent, in the field description or in the agent’s instructions: “Use null if the invoice has no due date”, or “Use an empty list if there are no line items”. Otherwise models tend to guess.
Designing a schema code can trust
- Return evidence, then decide in code. Ask for
matching_features and differing_features, not just is_same: bool. A function can then apply your rule, and the reasons are on record.
- Use
enum or literal for anything code branches on. A field_match router or a function can switch on a closed set of values; free text breaks that.
- Ask for a confidence only if you will use it, and say what the scale means (for example “0.0–1.0, how sure you are of the verdict”).
- Include an
assessed flag and a reason for agents that may not be able to do their job (a missing or unreadable file). Downstream code can then tell “said no” apart from “could not look”.
- Keep names stable. Code depends on field names; change them as you would change an API.
How the output arrives
- Agent run through the API:
result is the parsed object (unless you set "output_json_enabled": false).
- Inside a workflow: the JSON becomes the agent node’s output. Downstream function nodes receive its fields directly; see Passing data between nodes.
