Exceptions & Retries

Handle tool errors with exceptions and automatic retries.

If after a tool call you need to provide feedback to the model to change its behavior or exit the tool call loop, you can raise one of the following exceptions:

• RetryAgentRun: Use this exception when you want to provide instructions to the model for how to change its behavior and have the model retry the tool call. The exception message will be passed to the model as a tool call error, allowing the model to retry or adjust its approach in the next iteration of the LLM loop.

This does not retry the full agent run—it only provides feedback to the model within the current run.

• StopAgentRun: Use this exception when you want to exit the model execution loop and end the agent run. When raised from a tool function, the agent exits the tool call loop, and the run status is set to COMPLETED. All session state, messages, tool calls, and tool results up to that point are stored in the database.

This does not cancel the agent run. It completes the run after exiting the tool call loop.

Using RetryAgentRun

This example shows how to use the RetryAgentRun exception to provide feedback to the model, allowing it to adjust its behavior:

retry_in_tool_call.py

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.exceptions import RetryAgentRun
from agno.models.openai import OpenAIResponses
from agno.utils.log import logger
from agno.run import RunContext


def add_item(run_context: RunContext, item: str) -> str:
    """Add an item to the shopping list."""
    if not run_context.session_state:
        run_context.session_state = {}
    
    if "shopping_list" not in run_context.session_state:
        run_context.session_state["shopping_list"] = []
    
    run_context.session_state["shopping_list"].append(item)
    len_shopping_list = len(run_context.session_state["shopping_list"])
    
    if len_shopping_list < 3:
        raise RetryAgentRun(
            f"Shopping list is: {run_context.session_state['shopping_list']}. Minimum 3 items in the shopping list. "
            + f"Add {3 - len_shopping_list} more items.",
        )
    
    logger.info(f"The shopping list is now: {run_context.session_state.get('shopping_list')}")
    return f"The shopping list is now: {run_context.session_state.get('shopping_list')}"


agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    session_id="retry_example_session",
    db=SqliteDb(
        session_table="retry_example_session",
        db_file="tmp/retry_example.db",
    ),
    # Initialize the session state with empty shopping list
    session_state={"shopping_list": []},
    tools=[add_item],
    markdown=True,
)
agent.print_response("Add milk", stream=True)
print(f"Final session state: {agent.get_session_state(session_id='retry_example_session')}")

In this example, when add_item is called with fewer than 3 items, it raises RetryAgentRun with instructions. The model receives this as a tool call error and can call add_item again with additional items to meet the requirement.

Using StopAgentRun

This example shows how to use the StopAgentRun exception to exit the tool call loop:

stop_in_tool_call.py

from agno.agent import Agent
from agno.exceptions import StopAgentRun
from agno.models.openai import OpenAIResponses
from agno.run import RunContext


def check_condition(run_context: RunContext, value: int) -> str:
    """Check a condition and stop tool calls if met."""
    if value > 100:
        raise StopAgentRun(
            f"Value {value} exceeds threshold. Stopping tool call execution."
        )
    return f"Value {value} is acceptable."


agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[check_condition],
    markdown=True,
)

# When the model calls check_condition with value > 100,
# the tool call loop will exit and the run will complete
agent.print_response("Use the check_condition tool to check if 150 is acceptable", stream=True)

In this example, when check_condition is called with a value greater than 100, it raises StopAgentRun. The tool call loop exits immediately, and the run completes with status COMPLETED. All session state, messages, and tool calls up to that point are stored in the database.

Make sure to set AGNO_DEBUG=True if you want to see the debug logs.

Developer Resources

• View the RetryAgentRun schema
• View the StopAgentRun schema
• View Cookbook