[BUG] Circular reference when structured_output detects 0 required fields

[zastrowm]

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

Strands Version

1.4.0

Python Version

3.12

Operating System

MacOS

Installation Method

git clone

Steps to Reproduce

from typing import List
from pydantic import BaseModel, Field
from strands import tool, Agent

class ExampleFailure(BaseModel):
    ages: List[str] = Field(default_factory = list)
    names: List[str] = Field(default_factory = list)

agent = Agent(system_prompt="You excel at structured output")
agent.structured_output(AntiPatternOutput, "Name=Joe, age=88")

Expected Behavior

It works

Actual Behavior

Error message:

File structured_output.py:80, in _flatten_schema(schema)
     78     flattened["required"] = required_props
     79 else:
---> 80     raise ValueError("Circular reference detected and not supported")
     82 return flattened

ValueError: Circular reference detected and not supported

Additional Context

No response

Possible Solution

No response

Related Issues

No response

[afarntrog]

Looked a bit deeper and see it's related to when we provide a default value to the Pydantic model which causes the field to be marked as optional which in turn causes the strands sdk to throw an error when required_props is empty. See the following:

Working:

from typing import List
from pydantic import BaseModel, Field
from strands import tool, Agent

class ExampleFailure(BaseModel):
    ages: List[str]
    names: List[str]

agent = Agent(system_prompt="You excel at structured output")
agent.structured_output(ExampleFailure, "John Smith is a 30-year-old software engineer")

Not working:

from typing import List
from pydantic import BaseModel, Field
from strands import tool, Agent

class ExampleFailure(BaseModel):
    ages: List[str] = Field(default_factory = list)
    names: List[str] = Field(default_factory = list)

agent = Agent(system_prompt="You excel at structured output")
agent.structured_output(ExampleFailure, "John Smith is a 30-year-old software engineer")

Source of failure:
https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/structured_output.py#L71-L80

            # Track which properties are actually required after processing
            if is_required and "null" not in str(processed_prop.get("type", "")):
                required_props.append(prop_name)

    # Add required fields if any (only those that are truly required after processing)
    # Check if required props are empty, if so, raise an error because it means there is a circular reference

    if len(required_props) > 0:
        flattened["required"] = required_props
    else:
        raise ValueError("Circular reference detected and not supported")