Structured (JSON) outputs

[tinvaan]

Hey, is there a way to get structured outputs from the ClaudeSDKClient. Asking since Claude Code CLI seems to have an --output-format flag which isn't super useful for what I'm looking to do. I'm looking for something that's roughly equivalent to https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview

Is this supported already? If not, are there any possible workarounds using MCP's or SdkMcpTools etc?

[tinvaan]

hi, just bumping this up in case anyone knows any workarounds for this? or if indeed I'm missing something obvious.

/cc @dicksontsai @ashwin-ant

[anand-kamble]

On the CLI reference page, the --output-format accepts text, json, stream-json, which I believe is different from what we refer to as Structured outputs.

There is an option to pass arbitrary flags in ClaudeAgentOptions, have you tried that?

claude-agent-sdk-python/src/claude_agent_sdk/types.py

Lines 320 to 322 in 2a9693e

	extra_args: dict[str, str | None] = field(
	default_factory=dict
	) # Pass arbitrary CLI flags

[tinvaan]

Thanks for the suggestion. You're right I'm specifically looking to extract structured outputs. Using the --output-format flag with json simply returns a bunch of meta attributes but keeps the result field unstructured, as is.

One obvious workaround I can think of at this point is to use an API that supports tool calling and plug it to Claude Code's Hooks. Something like this: https://gist.github.com/tinvaan/8b7b6d1829b96e0bf5896d64578ddd3f

This ofcourse incurs and additional cost just to convert your response to a structured output. I'm guessing you can trade that for local compute by using something like ollama in that example. See https://python.useinstructor.com/examples/ollama/#patching

Sharing in case it's of use to anyone else who wanders here.

[shreyas-shinde]

Having the same issue. For now just prompting it return my structured output as a final response but it is sometimes unstable.

[tinvaan]

Using a tool calling API (OpenAI / Anthropic) is working well for me so far -- albeit with a slight marginal cost. I've tried the same with llama3 via Ollama which was okay too.

[anand-kamble]

Please correct me if I am wrong, since claude-agent-sdk-python uses the node module @anthropic-ai/claude-code underneath. This issue is better suited for the node project rather than this one.

cc: @jackdempsey @dicksontsai

[tinvaan]

I would agree. It looks like upstream support for structured outputs with Claude Code is lacking at present. Awaiting confirmation from the Anthropic folks on if there is a plan for that and if there are any recommended workarounds in the meantime.

This issue was meant to serve more as a question but got auto-labelled as an "enhancement".

[noamta-gloat]

The best mitigation I found for it is asking Claude to write the JSON to a file. The Write tool will send pure JSON because it knows it's writing directly to whatever.json.
Alternatively, since we're in Agent SDK context - create a Custom Tool and tell Claude to call that tool with the result. Again - since it's a tool, Claude must be exact.

[asselinpaul]

would also like a better solution for this — presently enforcing json validation with a JSON schema using a Write hook