Whetstone.
Output handling and debuggingStructured outputs, effort and streaming
Module 3, Lesson 125 min

Structured outputs, effort and streaming

Output handling is 2.6% of the exam, which is small, but it is dense with exactly the kind of fact that multiple choice loves: field names, defaults, and availability lines.

Structured outputs are GA from 4.5

Structured outputs are generally available for Claude 4.5 and later. That is the boundary. It matters because “structured output” as a phrase has meant several different things over the last couple of years, including “prompt hard and parse hopefully” and “abuse a tool definition as a schema”.

Those hand-rolled approaches still work. They are just no longer the answer, and if you have a retry loop that strips markdown fences and re-parses, that is code you are maintaining to compensate for a feature that now exists. Deleting it is a genuine win on your own systems, and it is the sort of deletion that only happens if somebody notices the boundary moved.

The field name, and the one that is on the way out

This is a naming question and it is worth being exact.

output_config.format is the current field. output_format is transitional.

Current vs transitional
// current
output_config: {
  format: { /* schema goes here */ },
}

// transitional: you will meet this in existing code
output_format: { /* schema goes here */ }

The exam trap here is that the transitional name is shorter and more memorable, so it is what people recall. Reach for the nested one.

effort defaults to high

output_config.effort defaults to high, and the docs are explicit that passing high yourself behaves identically to omitting the field.

The value set is documented, so learn it rather than planning to look it up: low, medium, high, xhigh, max. Two caveats that are worth more than the list. First, xhigh is newer than max, so support is not a clean ladder: some models that accept max reject xhigh (Opus 4.6 and Sonnet 4.6 are the ones to remember; Opus 4.7 and later and Sonnet 5 take all five). Second, adaptive is a thinking mode and not an effort level, and passing it here is a documented mistake.

Now the implication, which is the part people get backwards in both directions. The default is high, so most people’s instinct (turn it up for hard tasks) is usually unnecessary. But high is not the ceiling: xhigh and max sit above it, and on current models xhigh is the recommended starting point for coding and agentic work. So a request that never touches the field is not “paying for maximum effort”, it is sitting one rung below the top with real headroom in both directions.

That makes the field a genuine two-way lever. Down to medium or low when the task does not need the ceiling and you want speed and cost back; up to xhigh or max when it does. The one thing that is not true is that leaving it alone is either the cheapest or the strongest option.

Streaming is GA

Streaming is generally available. Nothing exotic to say about it, which is itself the point: it is not a beta you need to gate behind a flag or a header, and treating it as experimental is out of date.

The practical note is that streaming and structured output are not in tension. You can stream a response that is constrained to a schema. What you cannot do is parse a partial JSON document as though it were complete, which is a client-side problem and always has been.

The combination that hard-fails

One thing to hold onto here and we go deeper on it next lesson: citations plus structured outputs returns a 400.

Not a degraded response. Not citations silently dropped. A rejected request.

That is worth flagging now because it is the shape of the whole next lesson. The current generation of models has moved a set of behaviours from “quietly does something reasonable” to “refuses”. That is better engineering and worse for anyone whose integration was relying on the quiet reasonable thing.

Practice

Try it yourself

Quiz

Which field is current

You are writing new code that asks for a JSON-shaped response. Two field names appear in material you have read. Which do you write?

  1. Aoutput_format, because it is shorter and appears in more examples
  2. BEither, they are aliases with identical semantics and neither is preferred
  3. CNeither; you constrain the shape with a tool definition instead
  4. Doutput_config.format, with output_format understood as transitional
Show answer

Correct answer: D — output_config.format, with output_format understood as transitional

output_config.format is the current field. output_format is transitional, which means it is the older spelling you will meet in existing code rather than the one to reach for in new code. Option 1 is the tempting answer precisely because the shorter name is what circulates in blog posts and older samples, so it looks like the well-known idiom. Write the current one and recognise the transitional one when you inherit it.

Quiz

The effort default

You never set output_config.effort. What value is in play?

  1. AThere is no default; effort only applies if you set it
  2. Bhigh
  3. Cmedium, as a balanced starting point
  4. DIt inherits from the model tier you selected
Show answer

Correct answer: B — high

output_config.effort defaults to high, and setting high explicitly is documented as behaving exactly the same as omitting the parameter. Option 3 is the tempting wrong answer because a middle default is the conventional API design choice and it is what most people assume without checking. The thing to hold precisely: high is the default but it is not the ceiling. The documented ladder is low, medium, high, xhigh, max, so the default sits second from the top and there is genuine headroom above it as well as room to opt down.

Quiz

Modernise this call site

An inherited call site, now pointing at a current model. The schema itself is fine; the code around it has two problems.

Inherited, targeting Claude 4.6
const res = await client.messages.create({
  model: CURRENT_MODEL,
  output_format: ticketSchema,
  messages: [
    { role: "user", content: prompt },
    { role: "assistant", content: "{" },
  ],
})

Which change list is correct?

  1. AMove output_format to output_config.format, and remove the prefilled assistant turn
  2. BMove output_format to output_config.format; the prefilled assistant turn is still a supported technique
  3. CKeep output_format, which is the current field, and remove the prefilled assistant turn
  4. DNo changes are needed; both forms are current
Show answer

Correct answer: A — Move output_format to output_config.format, and remove the prefilled assistant turn

Two defects. output_format is transitional and output_config.format is current, and the trailing assistant message containing an opening brace is prefill on the final assistant turn, which returns a 400 on Claude 4.6 and later. Option 2 is the genuinely tempting one, and it is tempting for a reason worth knowing: two live documentation pages still recommend prefill with worked examples, so a careful reader who checked the docs this morning would come away believing that half is fine. It is not, and the next lesson is about exactly that disagreement.

Recall

Where structured outputs are GA

There is a version boundary here, and the useful form of this fact is the boundary rather than a list of models. Anything that moves you across the line changes what the feature guarantees.

For which models are structured outputs generally available?

Reveal answer

Structured outputs are GA for Claude 4.5 and later. Anything earlier than 4.5 is outside the GA line, so a model choice below that boundary changes what the feature guarantees you.

Recall

The one combination that 400s

Both features work perfectly well on their own, which is what makes this pairing worth committing to memory rather than deriving. It also previews the whole of the next lesson.

Which feature conflicts with structured outputs, and what is the failure mode?

Reveal answer

Citations. Requesting citations together with structured outputs returns a 400. It is a hard rejection rather than a degradation, so the combination is not something you can ship and monitor; it simply does not run.

Sign in to track your progress →