Repository navigation
Description
Checks
- I have updated to the lastest minor and patch version of Strands
- I have checked the documentation and this is not expected behavior
- I have searched ./issues and there are no duplicates of my issue
SDK Language
Python
Strands Version
1.55.1 — checkout of main at 08ed4cfd3eb42ae9f668595e675d5f196eee7e44 (git describe = python/v1.55.1-20-g08ed4cfd).
I re-checked the current main (e7fd22b6, which contains python/v1.56.0): strands-py/src/strands/tools/structured_output/ is byte-identical between the two revisions, so the bug is still present on the latest main.
Language Runtime Version
Python 3.12.14 (pydantic 2.13.5)
Operating System
macOS 26.6.2 (arm64)
Installation Method
git clone
Steps to Reproduce
from pydantic import BaseModel
from strands.tools.structured_output.structured_output_utils import convert_pydantic_to_tool_spec
class Inner(BaseModel):
"""Inner."""
a: int
b: str = "default" # optional, declared last
class Outer(BaseModel):
"""Outer."""
inner: Inner # required nested model
produced = convert_pydantic_to_tool_spec(Outer)["inputSchema"]["json"]
print("produced required :", produced.get("required"))
print("expected required :", ["inner"])
# Same model, only the declaration order inside Inner differs.
class Inner2(BaseModel):
"""Inner."""
b: str = "default" # optional, declared first
a: int
class Outer2(BaseModel):
"""Outer."""
inner: Inner2
produced2 = convert_pydantic_to_tool_spec(Outer2)["inputSchema"]["json"]
print("reordered required :", produced2.get("required"))Run against main at 08ed4cfd with a checkout of strands-py/ on PYTHONPATH.
Expected Behavior
Outer.inner is a required field (inner: Inner, no default), so the emitted tool inputSchema.json should carry "required": ["inner"], matching what the same model produces when the last field declared inside Inner happens to be required.
Basis:
- JSON Schema semantics:
requiredlists the properties that must be present, andinneris required onOuterregardless of whatInnerdeclares internally. - The function's own docstring says "Handles required vs. optional fields properly", and the comment at
structured_output_utils.py:70says "Track which properties are actually required after processing". - The sibling function
_process_schema_objectin the same file (line 206) computesis_required = prop_name in required_fieldsper property and emitsresult["required"] = required_props— the correct behaviour for the same situation. - The repo's own test
strands-py/tests/strands/tools/test_structured_output.py::test_convert_pydantic_with_refs(line 374) asserts top-level"required": ["contact"]for a required nested modelContact.
Actual Behavior
The key required is omitted from the top-level schema entirely, so the model is told inner is optional. The nested Inner schema itself is emitted correctly.
Reproduction output (verbatim):
produced required : None
expected required : ['inner']
reordered required : ['inner']
full Outer spec: {
"type": "object",
"properties": {
"inner": {
"type": "object",
"description": "The inner",
"properties": {
"a": {
"title": "A",
"type": "integer"
},
"b": {
"default": "default",
"title": "B",
"type": [
"string",
"null"
]
}
},
"required": [
"a"
]
}
},
"title": "Outer",
"description": "Outer."
}
Only the declaration order of the fields inside Inner differs between the first and third lines of that output, and it flips required between absent and ["inner"].
An independent verifier reproduced the same behaviour across a matrix of shapes (verbatim):
$ strands_venv/bin/python /tmp/verify_so_matrix.py
nested last=optional -> required = None
nested last=required -> required = ['inner']
two nested (opt,req) -> required = ['b']
leaf only -> required = ['x']
$ /tmp/verify_so_e2e.py (Agent path, tool_specs handed to model.stream)
tool_specs handed to model.stream -> Outer.required = []
(full spec ends: "title": "Outer", "description": "Outer.", "required": [])
A second independent verifier (verbatim):
produced required : None
expected required : ['inner']
reordered required : ['inner']
The same wrong behaviour is reachable through the public StructuredOutputTool path:
convert_pydantic_to_tool_spec -> None
StructuredOutputTool.tool_spec.required = None
full: {"type": "object", "properties": {"inner": {"type": "object", "description": "The inner", "properties": {"a": {"title": "A", "type": "integer"}, "b": {"default": "default", "title": "B", "type": ["string", "null"]}}, "required": ["a"]}}, "title": "Outer", "description": "Outer."}
A contract probe over the existing repo test model shows the regression boundary: test_convert_pydantic_with_refs' shape asserts as the test expects, and the same model with one optional field appended to Contact (declared last) flips to no required at all:
repo test shape -> ['contact']
appended optional on Contact -> None
Additional Context
Reachability: convert_pydantic_to_tool_spec is exported from strands.tools (strands/tools/__init__.py:17). It is called by StructuredOutputTool.__init__ -> _get_tool_spec, and directly by the structured-output configs for Bedrock (strands/models/bedrock.py:1711), Anthropic (strands/models/anthropic.py:802) and LiteLLM (strands/models/litellm.py:443). The malformed schema is what is sent to the model as the structured-output tool's input schema, so the model is told a field the caller declared as required may be omitted.
Possible Solution
In _flatten_schema, the nested-property loop should not reuse the outer is_required. Compute the nested sub-property's required-ness into a separate local (e.g. nested_is_required) and pass that to _process_property, leaving the outer is_required from line 44 intact for the check at line 71. A regression test that declares a required nested model whose last field is optional would cover it.
I'm happy to open a small PR with that change plus the test if that's welcome, or happy to be assigned.
Related Issues
None found. I searched the open and closed issues for this repo for "structured output required", "required field dropped", "convert_pydantic_to_tool_spec" and the internal helper names, and found no existing report or fix.
Metadata
Metadata
Assignees
Labels
Type
Fields
Language
Activity
BlueX888 commentedon Sep 17, 2026
Reproduced this. Root cause: strands-py/src/strands/tools/structured_output/structured_output_utils.py:57 — the nested-property loop reuses the outer is_required local, so after the loop it holds the required-ness of the last nested sub-property, and the check at line 71 emits no top-level required list.
Minimal reproduction:
Observed output:
Happy to open a PR with this fix, or to be assigned if you prefer to take it.