Get structured output from agents changedagent-sdk/structured-outputs
Nearest release: v2.1.306, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 21 Oct 2026 02:01 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 21 Oct 2026 02:07 UTC.
Upstream edited
Recorded here
Lines+11added
Lines−0removed
From line
364
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits8to this page, all time
## Recognize the StructuredOutput tool call
The whole hunk
from line 364, old and new numbered
/
from line 364
364364asyncio.run(main())
365365```
366366
367## Recognize the StructuredOutput tool call
368
369When you set `outputFormat` in TypeScript or `output_format` in Python, your message stream carries a tool call named `StructuredOutput` that you never defined. Claude Code adds this tool to the session, and the agent calls it to return its answer. The [system init message](/docs/en/agent-sdk/typescript#sdksystemmessage) lists it in the `tools` array, and each call arrives as two blocks:
370
371* A `tool_use` block named `StructuredOutput`, whose input is the object the agent produced for your schema
372* A `tool_result` block reading `Structured output provided successfully`
373
374When that object doesn't match your schema, the `tool_result` carries `is_error: true` instead and the agent calls `StructuredOutput` again, so your stream can hold several calls for one query. Read the validated data from `structured_output` on the result message rather than from a `tool_use` block, and see [Error handling](#error-handling) for the result you get when no attempt succeeds.
375
376If your application shows or logs tool calls, skip the ones named `StructuredOutput` so the mechanism doesn't appear as a step the agent chose. A `tool_result` block carries no tool name, only the `tool_use_id` of the call it answers, so match that against the `id` of each call you skipped.
377
367378## Error handling
368379
369380Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/docs/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` list on the error result message to tell the two causes apart before debugging your schema.
No line in this hunk matches that.