docs: improve examples for auto runs

Author: seratch

examples/agent_patterns/forcing_tool_use.py

@@ -15,6 +15,7 @@
     ToolsToFinalOutputResult,
     function_tool,
 )
+from examples.auto_mode import is_auto_mode
 
 """
 This example shows how to force the agent to use a tool. It uses `ModelSettings(tool_choice="required")`
@@ -81,6 +82,13 @@ async def main(tool_use_behavior: Literal["default", "first_tool", "custom"] = "
     print(result.final_output)
 
 
+async def auto_demo() -> None:
+    for behavior in ("default", "first_tool", "custom"):
+        print(f"=== {behavior} ===")
+        await main(behavior)
+        print()
+
+
 if __name__ == "__main__":
     import argparse
 
@@ -98,4 +106,7 @@ async def main(tool_use_behavior: Literal["default", "first_tool", "custom"] = "
         ),
     )
     args = parser.parse_args()
-    asyncio.run(main(args.tool_use_behavior))
+    if is_auto_mode():
+        asyncio.run(auto_demo())
+    else:
+        asyncio.run(main(args.tool_use_behavior))

examples/agent_patterns/human_in_the_loop_custom_rejection.py

@@ -4,6 +4,7 @@
 1. A single sensitive tool requires human approval.
 2. The first turn always issues that tool call.
 3. Rejection uses a custom message via ``tool_error_formatter``.
+4. The example prints both the formatter output and the assistant's final reply.
 """
 
 import asyncio
@@ -23,7 +24,7 @@ async def tool_error_formatter(args: ToolErrorFormatterArgs[None]) -> str | None
     """Build a simple output message for rejected tool calls."""
     if args.kind != "approval_rejected":
         return None
-    # The defualt one is "Tool execution was not approved."
+    # The default message is "Tool execution was not approved."
     return "Publish action was canceled because approval was rejected."
 
 
@@ -33,12 +34,27 @@ async def publish_announcement(title: str, body: str) -> str:
     return f"Published announcement '{title}' with body: {body}"
 
 
+def _find_formatter_output(result: object) -> str | None:
+    items = getattr(result, "new_items", None)
+    if not isinstance(items, list):
+        return None
+
+    for item in items:
+        if getattr(item, "type", None) != "tool_call_output_item":
+            continue
+        output = getattr(item, "output", None)
+        if isinstance(output, str):
+            return output
+    return None
+
+
 async def main() -> None:
     agent = Agent(
         name="Operations Assistant",
         instructions=(
             "When a user asks to publish an announcement, call the publish_announcement tool directly. "
-            "Do not ask the user for approval in plain text; runtime approvals handle that."
+            "Do not ask the user for approval in plain text; runtime approvals handle that. "
+            "If the tool call is rejected, respond with the exact rejection message and nothing else."
         ),
         model_settings=ModelSettings(tool_choice="publish_announcement"),
         tools=[publish_announcement],
@@ -69,6 +85,11 @@ async def main() -> None:
 
         result = await Runner.run(agent, state, run_config=run_config)
 
+    formatter_output = _find_formatter_output(result)
+    if formatter_output:
+        print("\nFormatter output:")
+        print(formatter_output)
+
     print("\nFinal output:")
     print(result.final_output)
 

examples/agent_patterns/input_guardrails.py

@@ -70,12 +70,22 @@ async def main():
 
     input_data: list[TResponseInputItem] = []
     auto_mode = is_auto_mode()
+    scripted_inputs = [
+        "What's the capital of California?",
+        "Can you help me solve for x: 2x + 5 = 11",
+    ]
 
     while True:
-        user_input = input_with_fallback(
-            "Enter a message: ",
-            "What's the capital of California?",
-        )
+        if auto_mode:
+            if not scripted_inputs:
+                break
+            user_input = scripted_inputs.pop(0)
+            print(f"[auto-input] Enter a message: -> {user_input}")
+        else:
+            user_input = input_with_fallback(
+                "Enter a message: ",
+                "What's the capital of California?",
+            )
         input_data.append(
             {
                 "role": "user",
@@ -98,7 +108,7 @@ async def main():
                     "content": message,
                 }
             )
-        if auto_mode:
+        if auto_mode and not scripted_inputs:
             break
 
     # Sample run:

examples/basic/agent_lifecycle_example.py

@@ -13,7 +13,7 @@
     Tool,
     function_tool,
 )
-from examples.auto_mode import input_with_fallback
+from examples.auto_mode import input_with_fallback, is_auto_mode
 
 
 class CustomAgentHooks(AgentHooks):
@@ -67,6 +67,15 @@ def random_number(max: int) -> int:
     """
     Generate a random number from 0 to max (inclusive).
     """
+    if is_auto_mode():
+        if max <= 0:
+            print("[debug] auto mode returning deterministic value 0")
+            return 0
+        value = min(max, 37)
+        if value % 2 == 0:
+            value = value - 1 if value > 1 else 1
+        print(f"[debug] auto mode returning deterministic odd number {value}")
+        return value
     return random.randint(0, max)
 
 

examples/basic/previous_response_id.py

@@ -1,7 +1,7 @@
 import asyncio
 
 from agents import Agent, Runner
-from examples.auto_mode import input_with_fallback
+from examples.auto_mode import input_with_fallback, is_auto_mode
 
 """This demonstrates usage of the `previous_response_id` parameter to continue a conversation.
 The second run passes the previous response ID to the model, which allows it to continue the
@@ -16,6 +16,7 @@
 
 
 async def main():
+    print("=== Non-streaming Example ===")
     agent = Agent(
         name="Assistant",
         instructions="You are a helpful assistant. be VERY concise.",
@@ -35,6 +36,7 @@ async def main():
 
 
 async def main_stream():
+    print("=== Streaming Example ===")
     agent = Agent(
         name="Assistant",
         instructions="You are a helpful assistant. be VERY concise.",
@@ -60,8 +62,13 @@ async def main_stream():
 
 
 if __name__ == "__main__":
-    is_stream = input_with_fallback("Run in stream mode? (y/n): ", "n")
-    if is_stream == "y":
+    if is_auto_mode():
+        asyncio.run(main())
+        print()
         asyncio.run(main_stream())
     else:
-        asyncio.run(main())
+        is_stream = input_with_fallback("Run in stream mode? (y/n): ", "n")
+        if is_stream == "y":
+            asyncio.run(main_stream())
+        else:
+            asyncio.run(main())

examples/financial_research_agent/manager.py

@@ -77,15 +77,27 @@ async def _perform_searches(self, search_plan: FinancialSearchPlan) -> Sequence[
             tasks = [asyncio.create_task(self._search(item)) for item in search_plan.searches]
             results: list[str] = []
             num_completed = 0
+            num_succeeded = 0
+            num_failed = 0
             for task in asyncio.as_completed(tasks):
                 result = await task
                 if result is not None:
                     results.append(result)
+                    num_succeeded += 1
+                else:
+                    num_failed += 1
                 num_completed += 1
+                status = f"Searching... {num_completed}/{len(tasks)} finished"
+                if num_failed:
+                    status += f" ({num_succeeded} succeeded, {num_failed} failed)"
                 self.printer.update_item(
-                    "searching", f"Searching... {num_completed}/{len(tasks)} completed"
+                    "searching",
+                    status,
                 )
-            self.printer.mark_item_done("searching")
+            summary = f"Searches finished: {num_succeeded}/{len(tasks)} succeeded"
+            if num_failed:
+                summary += f", {num_failed} failed"
+            self.printer.update_item("searching", summary, is_done=True)
             return results
 
     async def _search(self, item: FinancialSearchItem) -> str | None:

examples/mcp/filesystem_example/main.py

@@ -20,13 +20,13 @@ async def run(mcp_server: MCPServer):
     print(result.final_output)
 
     # Ask about books
-    message = "What is my #1 favorite book?"
+    message = "Read favorite_books.txt and tell me my #1 favorite book."
     print(f"\n\nRunning: {message}")
     result = await Runner.run(starting_agent=agent, input=message)
     print(result.final_output)
 
     # Ask a question that reads then reasons.
-    message = "Look at my favorite songs. Suggest one new song that I might like."
+    message = "Read favorite_songs.txt and suggest one new song that I might like."
     print(f"\n\nRunning: {message}")
     result = await Runner.run(starting_agent=agent, input=message)
     print(result.final_output)

examples/memory/advanced_sqlite_session_example.py

@@ -146,7 +146,7 @@ async def main():
 
     # === PART 3: Conversation Branching ===
     print("\n=== PART 3: Conversation Branching ===")
-    print("Let's explore a different path from turn 2...")
+    print("Let's explore a different path starting before turn 2...")
 
     # Show available turns for branching
     print("\nAvailable turns for branching:")
@@ -159,10 +159,10 @@ async def main():
     branch_id = await session.create_branch_from_turn(2)
     print(f"Created branch: {branch_id}")
 
-    # Show what's in the new branch (should have conversation up to turn 2)
+    # Show what's in the new branch (it should contain items created before turn 2)
     branch_items = await session.get_items()
     print(f"Items copied to new branch: {len(branch_items)}")
-    print("New branch contains:")
+    print("New branch starts before turn 2 and contains:")
     for i, item in enumerate(branch_items, 1):  # type: ignore[assignment]
         role = str(item.get("role", item.get("type", "unknown")))
         if item.get("type") == "function_call":

examples/reasoning_content/main.py

@@ -1,8 +1,9 @@
 """
-Example demonstrating how to use the reasoning content feature with models that support it.
+Example demonstrating how to access reasoning summaries when a model returns them.
 
 Some models, like gpt-5, provide a reasoning_content field in addition to the regular content.
-This example shows how to access and use this reasoning content from both streaming and non-streaming responses.
+This example shows how to access that content from both streaming and non-streaming responses,
+and how to handle responses that do not include a reasoning summary.
 
 To run this example, you need to:
 1. Set your OPENAI_API_KEY environment variable
@@ -61,6 +62,8 @@ async def stream_with_reasoning_content():
             # Green for regular content
             print(f"\033[32m{event.delta}\033[0m", end="", flush=True)
             regular_content += event.delta
+    if not reasoning_content:
+        print("\n(No reasoning summary deltas were returned.)")
     print("\n")
 
 

examples/research_bot/manager.py

@@ -66,17 +66,29 @@ async def _perform_searches(self, search_plan: WebSearchPlan) -> list[str]:
         with custom_span("Search the web"):
             self.printer.update_item("searching", "Searching...")
             num_completed = 0
+            num_succeeded = 0
+            num_failed = 0
             tasks = [asyncio.create_task(self._search(item)) for item in search_plan.searches]
             results = []
             for task in asyncio.as_completed(tasks):
                 result = await task
                 if result is not None:
                     results.append(result)
+                    num_succeeded += 1
+                else:
+                    num_failed += 1
                 num_completed += 1
+                status = f"Searching... {num_completed}/{len(tasks)} finished"
+                if num_failed:
+                    status += f" ({num_succeeded} succeeded, {num_failed} failed)"
                 self.printer.update_item(
-                    "searching", f"Searching... {num_completed}/{len(tasks)} completed"
+                    "searching",
+                    status,
                 )
-            self.printer.mark_item_done("searching")
+            summary = f"Searches finished: {num_succeeded}/{len(tasks)} succeeded"
+            if num_failed:
+                summary += f", {num_failed} failed"
+            self.printer.update_item("searching", summary, is_done=True)
             return results
 
     async def _search(self, item: WebSearchItem) -> str | None: