Output Format Control and Structured Outputs

An agent that produces free-form prose is difficult to integrate with downstream systems. A pipeline that extracts fields from a response needs a predictable structure. A coordinator that reads specialist results needs JSON it can parse without a fragile regex. This lesson covers the techniques that move Claude from “usually returns JSON” to “always returns JSON.” By the end of this lesson, we will be able to:

• Write system prompt instructions that consistently produce structured output

• Use assistant turn prefilling to force a specific output opening

• Use stop sequences to bound structured output without trailing commentary

• Identify the three most common format failures and how to prevent each

Why “return JSON” in the system prompt is not enough

A system prompt instruction like “Return your answer as a JSON object” works most of the time. It fails in three specific situations:

• Situation 1: Claude adds a preamble. Instead of starting with {, Claude writes “Here is the JSON object you requested:” followed by the JSON. The response is valid if you strip the first line, but it breaks any parser that calls json.loads() on the raw string.

• Situation 2: Claude wraps JSON in a markdown code block. Claude returns ```json\n{...}\n``` instead of {...}. This is syntactically correct markdown but not directly parseable as JSON.

• Situation 3: Claude adds an explanation after the JSON. The JSON is valid but is followed by “Note: the status field will be null if the order has not shipped yet.” The parser sees ...