diff --git a/agents/usage/agent-with-structured-output.mdx b/agents/usage/agent-with-structured-output.mdx index b17eb3c64..89b0f608a 100644 --- a/agents/usage/agent-with-structured-output.mdx +++ b/agents/usage/agent-with-structured-output.mdx @@ -80,3 +80,14 @@ Use `output_schema` to get structured, typed responses you can trust. The agent + +## Key Concepts + +- **Pydantic `BaseModel`:** Defines the output structure with typed fields +- **`output_schema=MyModel`:** Pass the Pydantic model class (not instance) to constrain agent output +- **`response.content`:** Returns a typed Pydantic object, not a string +- **Field names = JSON keys:** Field names like `ticker` become keys in the output JSON +- **`Field.description`:** Guides the LLM on what to generate for that field (not a key) +- **Field types → JSON Schema:** Python types (`str`, `float`, `List[str]`) are converted to JSON Schema types (`"string"`, `"number"`, `"array"`) +- **Conversion flow:** Pydantic model → JSON schema → Structured Output API → Validated Pydantic object +- **Works with tools:** Agent calls tools during execution, then formats the final response according to the schema