Structured data organizes information according to an explicit format or schema, making its contents easier for software and people to evaluate. In agent systems, that usually means returning JSON that matches a typed model instead of relying on free-form prose. section 2.2.1 section 11.1.1
The practical contrast is fragile text parsing versus inspectable fields. A loop controller can directly read findings, sources, follow-up questions, confidence, and goal satisfaction, then use those values to update state or stop. section 9.2.3 section 9.6
Useful design rules include:
- Define a schema with typed fields such as strings, lists, booleans, and numeric confidence scores. section 9.2.3
- Let the SDK manage the output format when supported, rather than duplicating schema instructions in the agent prompt. section 9.2.3
- Validate strictness early: replacing an unsupported dictionary type with a TypedDict can resolve strict-JSON errors. section 2.5
- Prefer repeatable structured outputs when downstream code depends on stable formatting. section 2.3.2
A typed research iteration
A ResearchIteration model can require summary_of_findings, sources_used, follow_up_questions, goal_satisfied, confidence, and reasoning, while allowing plan_updates and new_sub_topics as nested typed records. The controller can then decide whether another iteration is needed without interpreting prose. section 9.2.3
Listing 9.3 03_iteration_output.py (iteration body)
class SubTopicUpdate(BaseModel): #1
"""An update to a single sub-topic in the plan."""
name: str
status: str # pending | in_progress | complete
notes: str = ""
class ResearchIteration(BaseModel): #1
"""Output from a single research iteration."""
summary_of_findings: str #2
sources_used: list[str] #2
follow_up_questions: list[str] #2
goal_satisfied: bool #2
confidence: float #2
reasoning: str #2
plan_updates: list[SubTopicUpdate] = [] #3
new_sub_topics: list[SubTopicUpdate] = [] #4
strategy_notes: str = ""
Inspect the complete typed iteration model, including field types, defaults, and nested subtopic updates. section 9.2.3
