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

Structured outputs seems to be flaky

Open 8lank opened this issue 1 month ago • 1 comments

After working for a while with the Claude Agent SDK, I've noticed some flakiness around structured outputs:

In many cases, when working with large data outputs, it seems that Claude is sometimes calling its internal tool StructuredOutput with a string that contains the object instead of the actual object. It then keeps looping to try to understand why the tool call is failing.

Example of StructuredOutput tool calls with different values for a same query:

Valid:

input={
  'description': "A 3-4 day family backpacking adventure ...",
  'plan': [
    {'title': 'Research and select trail options', ...},
    {'title': 'Apply for permits and finalize route', ...},
    ...
  ],
  'status': 'open',
  'summary': 'A transformative family backpacking journey...',
  'title': 'Pacific Northwest Family Backpacking Adventure'
}

Invalid:

input={
  'description': '{\n  "title": "Pacific Northwest Family Backpacking Adventure",\n  "summary": "...",\n  "description": "...",\n  "status": "open",\n  "plan": [ ... ]\n}'
}

Is this something that has been seen internally as well? Is there any plan to improve this?

8lank avatar Nov 27 '25 05:11 8lank

Seems that structured outputs are still in Beta in the API (https://platform.claude.com/docs/en/build-with-claude/structured-outputs), any guidance to enable it in the SDK?

8lank avatar Nov 27 '25 05:11 8lank

Faced the same thing. In my case, it wraps the expected valid json object around a {"properties" : {}}, or a {"paramaters" : {}} block, when calling the StructuredOutput tool - eventually ending with a error_max_structured_output_retries response. This happens when the conversation has been a long one. For smaller ones, it seems to be working fine consistently.

anujhydrabadi avatar Dec 22 '25 07:12 anujhydrabadi