Problem 8 of 15 in the Harnessing Agentic AI Systems series — read the index for the framing. Previous: State Snapshot & Rollback Pattern · Next: Asynchronous Tool Worker Queue Pattern.
The Problem — Typing tool output and keeping errors legible
Model output is text; tools and downstream systems need types. Malformed values fail far from their cause, and swallowed errors become hallucinated successes. The boundary must be typed, and failures must stay legible.
| Field | P9 — Schema Enforcement & Self-Correction (pattern) | A7 — The Silent Crash (anti-pattern) | A9 — The Schema Free-for-All (anti-pattern) |
|---|---|---|---|
| Forces / Smell | Free text vs types; bounded retries vs bad data; append-only corrections. | Errors caught in the background; blank strings returned; no stderr, no verdict. | Complex arguments as raw strings; parsing deferred; "the model formats it." |
| Solution / Anti-solution | Force raw LLM text into JSON Schema, catching parsing failures and feeding structural fixes back internally. | Catch-and-continue: "the agent doesn't need to know." | Trust the model's output format. |
| Consequences / Failure | A typed contract at the harness boundary — the same contract as --json and exit codes; corrections are appends, not rewrites. |
A real error becomes a hallucinated success; destroys the stdout/stderr/exit-code contract. | Parsing moves downstream where no model can correct it; errors surface far from their cause. |
| Tradeoffs / Refactoring | Retries cost tokens — the retry budget is part of the pattern; the error message must name the field. | P9 with errors surfaced and bounded; layered checks: "the planner chose the wrong tool," not "the agent failed." | P9 at the boundary with feedback while the model is still in the loop. |
| Evidence | Instructor — Pydantic validation with max_retries and token_budget (docs, retry logic). |
Instructor's retry mechanics (retrying). | Pydantic — core validation (docs). |
| Related | Refactoring for A9 and A7; composes with the frozen-request pattern. | Is the absence of P9; feeds A9. | Is the absence of P9; feeds A7's downstream. |
Discussion
The schema is the grammar of the contract: output is converted from text to structure at the boundary where the model is still in the loop to fix it, and the correction is an append, not a rewrite (DeepSeek teardown). The two anti-patterns are the boundary's two failure directions — the silent crash hides the error (a hallucinated success), and the free-for-all defers parsing until no model is present to correct it. Both are fixed by enforcement at the boundary with legible feedback.
Key Insight
The schema is the grammar of the contract. Malformed output is fixed while the model is still in the loop, the retry budget is part of the pattern (unbounded self-correction is the schema version of the vortex), and swallowed errors become hallucinated successes.
References
Instructor (docs, retry logic); Pydantic (docs); archive: Agentic-First CLI, harness canon, DeepSeek teardown.