structured-output

# structured-output If a downstream step (code, a tool, another agent) will parse the answer, decide the shape FIRST and conform to it. Free-form text that you later regex is where parse errors and bad tool-args come from. ## Why this exists (evidence) - Malformed tool calls / wrong arguments are a leading cause of agent failure (~31% of production failures). A declared schema removes a whole class of these: missing fields, wrong types, prose where JSON was expected. - Constrained / schema-guided decoding is the reliable fix: output that is validated against a schema is machine-consumable by construction, instead of "usually parseable". ## When to use - Tool / function arguments and API request bodies. - Extraction & classification (pull fields from text -> typed object). - Agent-to-agent handoffs in a Workflow (one stage's output is the next stage's input). - NOT for human-facing prose; this is for machine-consumed output. ## The method 1. **Define the schema first:** the exact fields, types, required vs optional, allowed enums. Keep it minimal, only what the consumer needs. 2. **Emit only the structure:** no prose around it, no markdown fences if the consumer wants raw JSON. 3. **Validate before use:** parse + check against the schema. On mismatch, do not "best-effort" it, regenerate to conform or surface the error. 4. **Constrain when you can:** in the API, pass a JSON schema / tool definition so the model is forced to the shape; in a Workflow, use the agent `schema` option so output is validated and retried automatically. ## How to run it - API / SDK: define a tool or response JSON schema and let the platform enforce it. - Workflow: pass a JSON Schema to `agent(prompt, { schema })`, the runtime forces a structured tool call and validates, so the returned object is typed, no parsing. - Extraction: give the target object shape up front; assert every required field is present and typed before acting. ## Composes with - `tool-guard`: structured-output prevents bad args at generation time; tool-guard validates at call time. Belt and suspenders. - `orchestrate` / multi-stage Workflows: typed handoffs between stages so stage N+1 never parses stage N's prose. ## Honest limits - A schema guarantees SHAPE, not correctness: a well-formed object can still hold wrong values. Pair with verification for the values that matter. - Over-schematizing human-facing answers makes them robotic; scope to machine-consumed output.