From 8c516916ed6705dfd24a9bff8df900d03b4db519 Mon Sep 17 00:00:00 2001
From: Patrick Gray <pgrayy@amazon.com>
Date: Mon, 14 Jul 2025 17:42:01 +0000
Subject: [PATCH] structured output async

---
 docs/examples/python/structured_output.md     | 23 +++++++++++++++++
 docs/examples/python/structured_output.py     | 22 ++++++++++++++++
 .../concepts/agents/structured-output.md      | 25 +++++++++++++++++++
 3 files changed, 70 insertions(+)

diff --git a/docs/examples/python/structured_output.md b/docs/examples/python/structured_output.md
index ac5326e9..afb7460a 100644
--- a/docs/examples/python/structured_output.md
+++ b/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,6 +154,26 @@ 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")
 
@@ -160,6 +181,7 @@ if __name__ == "__main__":
     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.
diff --git a/docs/examples/python/structured_output.py b/docs/examples/python/structured_output.py
index 951a613f..933a4d2b 100644
--- a/docs/examples/python/structured_output.py
+++ b/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,6 +135,26 @@ 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")
 
@@ -141,5 +162,6 @@ class Person(BaseModel):
     multimodal_example()
     conversation_history_example()
     complex_nested_model_example()
+    asyncio.run(async_example())
 
     print("\nExamples completed.")
diff --git a/docs/user-guide/concepts/agents/structured-output.md b/docs/user-guide/concepts/agents/structured-output.md
index 7c08b104..4f4ccfe4 100644
--- a/docs/user-guide/concepts/agents/structured-output.md
+++ b/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