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.

When to Use

• Wiring a node's output into another node, a graph write, or a tool call
• Deciding whether a node's output needs a schema or a grammar, or can stay prose
• Designing the contract for a hypothesis / remediation / reasoning / validation node
• Justifying "this seam is reliable by construction" in a design doc

Phrases: "structured output", "output contract", "constrained decoding", "Outlines schema", "grammar-constrained", "node output format", "internode contract", "make this seam parseable".

When NOT to Use

• Choosing which pipeline shape to run (sequential / tree / loop) — that is pipeline-architecture selection, a different axis.
• Terminal human-facing prose. If the only reader is a human and nothing downstream parses it, a schema is latency for no reliability gain.
• Picking a model or a graph model class. This designs the output contract at a seam, not the model behind it or the store under it.
• A seam that already has an enforced contract. If the interface is fixed and validated upstream, adopt it.

Process

Rationalizations

Red Flags

• A node-to-node or graph-write seam recommended FREE_TEXT. The profile is wrong — a machine seam is not a human terminal reader. Re-check consumed_by.
• GRAMMAR_CONSTRAINED chosen but no closed vocabulary or node-type exists. You are paying grammar cost for a plain structured hand-off; JSON_SCHEMA suffices unless a formal grammar is genuinely required.
• validate_against_contract returns valid on a payload missing a required field. The contract's required list drifted from the node type — the seam is not actually verified.
• Every node routes to the same enforcement level. The seam profiles are not discriminating; a terminal human summary and a graph-write node should not share a level.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report 11/11:
   • graph-write / next-node / tool-call seams route to JSON_SCHEMA or stricter
   • a fixed vocabulary / node-type target routes to GRAMMAR_CONSTRAINED
   • FREE_TEXT only for a non-critical human terminal reader; a critical human seam is not FREE_TEXT
   • validation catches a missing required field, a type mismatch, and a closed-vocabulary violation; a well-formed payload validates clean
   • reliability_gain reports the correct seam delta
2. Run the scenario. python cli.py scenario shows a hypothesis node's hand-off: the recommended enforcement, the contract, a passing and a failing payload, and the reliability delta from constraining the seam.
3. Verify CLI help. python cli.py --help exits 0 and prints this SKILL.md description (so any harness can discover the skill from --help).

Security Posture

• Prompt injection. Seam profiles and payloads are untrusted input handled as data - validation is deterministic key/type/enum checking, nothing is executed. Note the limit: a contract constrains SHAPE, not content. A schema-valid payload can still carry injected text in its string fields; contract validation is not sanitization.
• Data exfiltration. No network calls, no file writes. Payloads under validation stay in-process and appear only in the stdout violations report the caller owns.
• Privilege escalation. No shell invocation, no eval. Contracts are a security boundary: a closed vocabulary bounds what a node can emit into a tool call or graph write, so loosening an enum or dropping a required field widens the downstream attack surface - treat contract edits as privileged changes.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch5 — Reasoning & Planning, section "Structured Generation: The Keystone of Reliable Communication". The constrained-decoding mechanism (a finite-state machine over valid token sequences that zeros out invalid tokens) is the Outlines library; the insurance-claims example (enumerated determination, non-negative amount, pattern-matched explanation code, mandatory appeal-rights language, valid by construction) is the chapter's real-world impact case. Structured output is a cross-chapter pillar: Ch5 constrains node output, and Ch6 applies the same grammar-constrained decoding to MCP tool calls so the seam is reliable on both sides.