structured-output-contract-designer

Structured Output Contract Designer

Overview

After the graph architecture is in place, one failure dominates production: even with perfect reasoning and validated retrieval, the system collapses when nodes cannot parse each other's outputs. The chapter is blunt — most graph-agent failures are internode COMMUNICATION breakdowns, not bad reasoning. A workflow graph is useless when output formats vary unpredictably.

Structured output is the keystone that fixes this. Instead of hoping a node produces a parseable format, you constrain generation so producing anything else is impossible. Outlines builds a finite-state machine over the valid token sequences of your schema/grammar and zeros out any token that would leave the valid set, so the output is valid by construction, not by post-hoc validation that can be bypassed or fail silently.

The designer chooses an enforcement level per node seam:

• FREE_TEXT — terminal, human-facing prose with no downstream parser. A schema would only add latency. Admissible only when the reader is human and the output is not reliability-critical.
• JSON_SCHEMA — the default for any machine seam: node-to-node hand-off, a graph write, or a tool call. The next node relies on the shape instead of defensively parsing prose.
• GRAMMAR_CONSTRAINED — the output must match a formal grammar, draw from a closed vocabulary, or land on a specific graph node-type. The grammar makes every out-of-vocabulary / off-type sequence physically ungenerable.

It also emits minimal contracts for common DevOps-investigation node types (hypothesis, remediation, reasoning, validation) and validates a payload against a contract deterministically — required fields present, types match, closed vocabularies honored. That validation is the concrete form of the chapter's claim that structured output makes the seam verifiable. Because structure compounds with the graph, this same primitive carries into Ch6, where grammar-constrained decoding makes MCP tool calls syntactically valid too.