Skip to main content
The StopAgentRun exception allows you to exit the model execution loop and end the agent run. When raised from a tool function, the agent immediately 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 gracefully after exiting the tool call loop.

​
Constructor

StopAgentRun(
    exc: str,
    user_message: Optional[Union[str, Message]] = None,
    agent_message: Optional[Union[str, Message]] = None,
    messages: Optional[List[Union[dict, Message]]] = None,
)

​
Parameters

​
exc
str
required
The reason for stopping execution. This message is logged and can be used for debugging or user feedback.
​
user_message
Union[str, Message]
An optional message to display to the user about why execution stopped.
​
agent_message
Union[str, Message]
An optional message from the agent’s perspective about the stop.
​
messages
List[Union[dict, Message]]
An optional list of messages to add to the conversation history before stopping.

​
When to Use

Use StopAgentRun when:
  • Critical errors: An error occurs that cannot be recovered from
  • Security triggers: A security threshold or policy is violated
  • Task completion: The task is fully completed and no further tool calls are needed
  • Resource limits: A resource limit (time, cost, API calls) is reached
  • Manual intervention needed: The situation requires human review or approval
  • Early termination: You want to exit the tool call loop based on business logic

​
Behavior

When StopAgentRun is raised:
  1. The tool call loop exits immediately
  2. No further tool calls are executed
  3. The run status is set to COMPLETED
  4. All session state is saved to the database
  5. All messages and tool calls up to that point are preserved
  6. The optional user_message or agent_message can be displayed to the user

​
See Also