updated naming & example

Author: thomas-lab-openai

examples/basic/max_turns_resume.py

@@ -0,0 +1,41 @@
+from typing import Annotated
+
+from agents import Agent, MaxTurnsExceeded, Runner, function_tool
+
+
+@function_tool
+def gather_facts(topic: Annotated[str, "The topic to investigate"]) -> str:
+    """Return placeholder research that simulates a tool lookup."""
+    return (
+        f"Key facts about {topic}: it moves through evaporation, condensation, "
+        "precipitation, and collection."
+    )
+
+
+def main():
+    agent = Agent(
+        name="Researcher",
+        instructions=(
+            "You must call the gather_facts tool before answering. "
+            "Once you have the tool output, summarize it in your own words."
+        ),
+        tools=[gather_facts],
+    )
+
+    try:
+        Runner.run_sync(
+            agent,
+            input="Give me the main stages of the water cycle.",
+            max_turns=1,
+        )
+    except MaxTurnsExceeded as exc:
+        print("Reached the max turn limit. Asking the agent to finalize without tools...\n")
+        result = exc.resume_sync(
+            "Finish the answer using the gathered information without calling tools again."
+        )
+        print(result.final_output)
+        # The water cycle proceeds through evaporation, condensation, precipitation, and collection.
+
+
+if __name__ == "__main__":
+    main()

src/agents/exceptions.py

@@ -61,8 +61,13 @@ def __init__(self, message: str):
         self.message = message
         super().__init__(message)
 
-    def resume(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) -> RunResult:
-        """Resume the failed run synchronously with a final, tool-free turn.
+    async def resume(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) -> RunResult:
+        """Resume the failed run asynchronously with a final, tool-free turn.
+
+        Note:
+            This helper does not automatically reuse the original session object.
+            If you need the resumed turn to be persisted in the session,
+            run the follow-up turn manually with that information.
 
         Args:
             prompt: Optional user instruction to append before rerunning the final turn.
@@ -74,16 +79,21 @@ def resume(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) -> RunResult:
 
         from .run import Runner
 
-        return Runner.run_sync(
+        return await Runner.run(
             starting_agent=run_data.last_agent,
             input=inputs,
             context=run_data.context_wrapper.context,
             max_turns=1,
             run_config=run_config,
         )
 
-    async def resume_async(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) -> RunResult:
-        """Resume the failed run asynchronously with a final, tool-free turn.
+    def resume_sync(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) -> RunResult:
+        """Resume the failed run synchronously with a final, tool-free turn.
+
+        Note:
+            This helper does not automatically reuse the original session object.
+            If you need the resumed turn to be persisted in the session,
+            run the follow-up turn manually with that information.
 
         Args:
             prompt: Optional user instruction to append before rerunning the final turn.
@@ -95,7 +105,7 @@ async def resume_async(self, prompt: Optional[str] = _DEFAULT_RESUME_PROMPT) ->
 
         from .run import Runner
 
-        return await Runner.run(
+        return Runner.run_sync(
             starting_agent=run_data.last_agent,
             input=inputs,
             context=run_data.context_wrapper.context,

tests/test_max_turns.py

@@ -76,7 +76,7 @@ async def test_streamed_max_turns():
 
 
 @pytest.mark.asyncio
-async def test_max_turns_resume_async_runs_final_turn():
+async def test_max_turns_resume_runs_final_turn():
     model = FakeModel()
     agent = Agent(
         name="test_1",
@@ -98,7 +98,7 @@ async def test_max_turns_resume_async_runs_final_turn():
     with pytest.raises(MaxTurnsExceeded) as exc_info:
         await Runner.run(agent, input="user_message", max_turns=2)
 
-    result = await exc_info.value.resume_async("Finish without tools.")
+    result = await exc_info.value.resume("Finish without tools.")
 
     assert result.final_output == final_answer
     resume_input = model.last_turn_args["input"]
@@ -130,7 +130,7 @@ def test_max_turns_resume_sync_uses_default_prompt():
     with pytest.raises(MaxTurnsExceeded) as exc_info:
         Runner.run_sync(agent, input="user_message", max_turns=2)
 
-    result = exc_info.value.resume()
+    result = exc_info.value.resume_sync()
 
     assert result.final_output == final_answer
     resume_input = model.last_turn_args["input"]
@@ -167,7 +167,7 @@ async def test_resume_preserves_run_config_settings():
     with pytest.raises(MaxTurnsExceeded) as exc_info:
         await Runner.run(agent, input="user_message", max_turns=2, run_config=run_config)
 
-    await exc_info.value.resume_async("Finish without tools.")
+    await exc_info.value.resume("Finish without tools.")
 
     final_settings = model.last_turn_args["model_settings"]
     assert final_settings.temperature == 0.25