docs: add documentation for the new structured output approach #295
Conversation
| ``` | ||
|
|
||
| ### Multi-Modal Input | ||
| ### Structured Output agent with Auto Retries |
There was a problem hiding this comment.
Can we make the basic usage just have a tool. I'm not sure how much we're gainging from
-
Structured Output agent with Auto Retries
-
Structured Output agent with other tools
vs just in the basic usage having a calculator tool, then mentioning that it is superior because failures will auto recover.
There was a problem hiding this comment.
Was thinking that we start with the absolute most simple use case so it's abundantly clear how to use it. Then we progressively add more examples further down the page as the reader becomes more familiar.
There was a problem hiding this comment.
It feels more like llms running through use cases rather than a curated guide to me (again the existing bar is very low) I just want to be deliberate with what we are asking people to read - with the bar being things like https://docs.stripe.com/ where there isn't excess
There was a problem hiding this comment.
I hear that. However, I've always considered bloat in docs to be 'rambling'. Like these huge paragraphs of text that take the reader on a journey just to get around the block. The documentation in this PR is really a collection of examples that get progressively more advanced. The reader can immediately stop at the top of the page if their use case is satisfied. There is no obligation to read through each example to the bottom. I also think that it'll be beneficial for an LLM that is reading the docs and providing guidance to a user.
| Since this is on the agent init level, not the invocation level, the expectation is that the agent will attempt structured output for each invocation. | ||
|
|
||
|
|
||
| ### Overriding Agent Default |
There was a problem hiding this comment.
can we just combine ths with the section above like. Just feels like a lot of content added thats very similar
// Override the agent's default structured output model for specific invocations that require different schemas:
agent = Agent(structured_output_model=PersonInfo)
There was a problem hiding this comment.
Similar response to the other two comments :)
| ``` | ||
|
|
||
|
|
||
| ### Using Conversation History |
There was a problem hiding this comment.
is this section relevant now? aren't we making it clear that the conversation is used above?
There was a problem hiding this comment.
Yeah, it's not strictly needed. Just outlines how it's not necessary to use structured output right away. One can invoke a few times and use it at the end etc. Was applying 'the more the merrier' strategy regarding the examples here :)
There was a problem hiding this comment.
I want to be efficient and refined with our docs (they are not now lol) so readers aren't forced to read content that is not likely useful or could be expressed more efficiently
| The structured output system converts your Pydantic models into tool specifications that guide the language model to produce correctly formatted responses. All of the model providers supported in Strands can work with Structured Output. | ||
|
|
||
| Strands handles this through the [`Agent.structured_output()`](../../../api-reference/agent.md#strands.agent.agent.Agent.structured_output) method, which manages the conversion, validation, and response processing automatically. | ||
| Strands handles this by accepting the `structured_output_model` parameter to agent invocations, which manages the conversion, validation, and response processing automatically. The validated result is available in the `AgentResult.structured_output` field. |
There was a problem hiding this comment.
Should we deep link structured_output?
| ``` | ||
|
|
||
| ### Complex Nested Models | ||
| ### Nested Models |
There was a problem hiding this comment.
I'd argue to remove this or keep this as one of the examples before; having this as a separate example is just bloat IMHO
| ``` | ||
|
|
||
| ### Async | ||
| ### Async Support |
There was a problem hiding this comment.
Let's merge this into one of the earlier examples showing support - repeating this just to show that agent() and agent.invoke_async() work the same is a bit much
| # Structured Output | ||
|
|
||
| Structured output enables you to get type-safe, validated responses from language models using Pydantic models. Instead of receiving raw text that you need to parse, you can define the exact structure you want and receive a validated Python object that matches your schema. This transforms unstructured LLM outputs into reliable, program-friendly data structures that integrate seamlessly with your application's type system and validation rules. | ||
| Structured output enables you to get type-safe, validated responses from language models using [Pydantic](https://docs.pydantic.dev/latest/concepts/models/) models. Instead of receiving raw text that you need to parse, you can define the exact structure you want and receive a validated Python object that matches your schema. This transforms unstructured LLM outputs into reliable, program-friendly data structures that integrate seamlessly with your application's type system and validation rules. |
There was a problem hiding this comment.
Let's add a top-level block of "!!! New" - folks who used the new method and come here should be more aware that this has been revamped
|
|
||
|
|
||
|
|
||
| Refer to Pydantic documentation for details on: |
There was a problem hiding this comment.
Why is this section here? It seems applicable to all examples.
Per the overall feel, how would we feel about restructuring to be:
- Introduce concept
- Basic examples/usage
- More information/details
- Cookbook/Additional examples
I think the latter (cookbook/additional examples) is something we need, but right now it the structure doesn't really match the rest of our docs. By putting it at the end, we can se the convention (until we have the website revamp) while still preserving the existing structure
Description
Add documentation for the revamped structured output feature strands-agents/sdk-python#943
Type of Change
Motivation and Context
We updated our approach for structured output. We therefore need to communicate these API changes to Strands users.
Areas Affected
docs/user-guide/concepts/agents/structured-output.mdScreenshots
Checklist
mkdocs serveAdditional Notes
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.