structured output async (#145)

Author: pgrayy

docs/examples/python/structured_output.md

@@ -25,6 +25,7 @@ Structured Output Example
 This example demonstrates how to use structured output with Strands Agents to
 get type-safe, validated responses using Pydantic models.
 """
+import asyncio
 import tempfile
 from typing import List, Optional
 from pydantic import BaseModel, Field
@@ -153,13 +154,34 @@ def complex_nested_model_example():
     print(f"Skills: {result.skills}")                # ["systems admin"]
 
 
+async def async_example():
+    """Basic example extracting structured information from text asynchronously."""
+    print("\n--- Async Example ---")
+
+    class PersonInfo(BaseModel):
+        name: str
+        age: int
+        occupation: str
+
+    agent = Agent()
+    result = await agent.structured_output_async(
+        PersonInfo,
+        "John Smith is a 30-year-old software engineer"
+    )
+
+    print(f"Name: {result.name}")      # "John Smith"
+    print(f"Age: {result.age}")        # 30
+    print(f"Job: {result.occupation}") # "software engineer"
+
+
 if __name__ == "__main__":
     print("Structured Output Examples\n")
 
     basic_example()
     multimodal_example()
     conversation_history_example()
     complex_nested_model_example()
+    asyncio.run(async_example())
 
     print("\nExamples completed.")
 ```
@@ -168,6 +190,7 @@ if __name__ == "__main__":
 
 1. **Define a Schema**: Create a Pydantic model that defines the structure you want
 2. **Call structured_output()**: Pass your model and optionally a prompt to the agent
+   - If running async, call `structured_output_async()` instead.
 3. **Get Validated Results**: Receive a properly typed Python object matching your schema
 
 The `structured_output()` method ensures that the language model generates a response that conforms to your specified schema. It handles converting your Pydantic model into a format the model understands and validates the response.

docs/examples/python/structured_output.py

@@ -5,6 +5,7 @@
 This example demonstrates how to use structured output with Strands Agents to
 get type-safe, validated responses using Pydantic models.
 """
+import asyncio
 import tempfile
 
 from typing import List, Optional
@@ -134,12 +135,33 @@ class Person(BaseModel):
     print(f"Skills: {result.skills}")                # ["systems admin"]
 
 
+async def async_example():
+    """Basic example extracting structured information from text asynchronously."""
+    print("\n--- Async Example ---")
+
+    class PersonInfo(BaseModel):
+        name: str
+        age: int
+        occupation: str
+
+    agent = Agent()
+    result = await agent.structured_output_async(
+        PersonInfo,
+        "John Smith is a 30-year-old software engineer"
+    )
+
+    print(f"Name: {result.name}")      # "John Smith"
+    print(f"Age: {result.age}")        # 30
+    print(f"Job: {result.occupation}") # "software engineer"
+
+
 if __name__ == "__main__":
     print("Structured Output Examples\n")
 
     basic_example()
     multimodal_example()
     conversation_history_example()
     complex_nested_model_example()
+    asyncio.run(async_example())
 
     print("\nExamples completed.")

docs/user-guide/concepts/agents/structured-output.md

@@ -193,6 +193,31 @@ except ValidationError as e:
     # 3. Extract partial information from the error
 ```
 
+### Async
+
+Strands also supports obtaining structured output asynchronously through [`structured_output_async`](../../../api-reference/agent.md#strands.agent.agent.Agent.structured_output_async):
+
+```python
+import asyncio
+from pydantic import BaseModel
+from strands import Agent
+
+class PersonInfo(BaseModel):
+    name: str
+    age: int
+    occupation: str
+
+async def structured_output():
+    agent = Agent()
+    return await agent.structured_output_async(
+        PersonInfo,
+        "John Smith is a 30-year-old software engineer"
+    )
+
+result = asyncio.run(structured_output())
+```
+
+
 ## Best Practices
 
 - **Keep models focused**: Define specific models for clear purposes