claude-agent-sdk-python icon indicating copy to clipboard operation
claude-agent-sdk-python copied to clipboard

Published 20 hours ago • verified publisher icon anthropics

Structured (JSON) outputs

Open tinvaan opened this issue 2 months ago • 9 comments

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 avatar Sep 25 '25 09:09 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

tinvaan avatar Sep 29 '25 06:09 tinvaan

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.

Image

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

https://github.com/anthropics/claude-agent-sdk-python/blob/2a9693e2585228e956ab240c1fad557d4eb510d4/src/claude_agent_sdk/types.py#L320-L322

anand-kamble avatar Oct 01 '25 04:10 anand-kamble

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.

tinvaan avatar Oct 01 '25 13:10 tinvaan

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

shreyas-shinde avatar Oct 02 '25 11:10 shreyas-shinde

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.

tinvaan avatar Oct 02 '25 11:10 tinvaan

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

anand-kamble avatar Oct 03 '25 03:10 anand-kamble

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".

tinvaan avatar Oct 03 '25 04:10 tinvaan

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.

noamta-gloat avatar Oct 12 '25 14:10 noamta-gloat

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

asselinpaul avatar Nov 05 '25 23:11 asselinpaul