A retry is another attempt after an operation fails or produces an unacceptable result. For an agent, that might mean calling a tool again after a transient error or asking an agent to revise an output rejected by a guardrail. A retry is a recovery path, not permission to loop indefinitely. section 1.1.3 section 4.4.3
Use a small recovery loop:
- Detect the failure. A tool can return an error; an output guardrail can reject a plan that is not detailed enough. section 1.1.3 section 4.4.3
- Give the next attempt useful information. Feed the previous error or guardrail feedback back to the agent rather than blindly repeating the same input. section 9.6 section 4.4.3
- Set a maximum number of attempts and a clear failure outcome. Track completed, failed, and pending work when retrying items in a task queue. section 4.4.3 section 9.6
Listing 4.11 10_agent_guardrails_retry.py
# only relevant code shown
print("Running...", goal)
research_agent.mcp_servers = [research_srv]
result = await Runner.run(research_agent, goal)
thinking_agent.mcp_servers = [thinking_srv]
final_output = result.final_output #1
max_retries = 3
for attempt in range(max_retries): #2
try:
result = await Runner.run(thinking_agent, final_output)
final_output = result.final_output.research_plan #2
break
except OutputGuardrailTripwireTriggered as output_tripped: #3
final_output = output_tripped.guardrail_result.output.output_info
if attempt == max_retries - 1:
final_output = "A research plan was not generated. Please try again #4
with a different goal." #4
filesystem_agent.mcp_servers = [fs_srv]
result = await Runner.run(filesystem_agent, final_output)
print(result.final_output)
The guarded planning flow allows three attempts. On a guardrail exception, it replaces the next input with the guardrail’s output information; after the last failed attempt, it sets a failure message. Notice that the listing still passes the resulting string to the filesystem agent, so a production flow should distinguish a failed plan from a usable one before that handoff. section 4.4.3
Retrying a batch of tasks
Give five text-transformation items to a tool that randomly fails 30% of the time. Allow up to three attempts per item, then print the completion rate and permanently failed items. This makes a transient failure visible without letting one item stall the whole batch. section 9.5
Choose recovery to fit the failure. For rate limits or network failures, use exponential backoff with jitter instead of immediate retries. For an answer that fails a grounding guardrail, either retry with the guardrail’s feedback or return a safe fallback. Retries cost tokens and time and may still fail; pair them with timeouts, fallbacks, and clear user-facing errors where appropriate. section 4.4.3 section 7.3.3 section 11.2
