StopAgentRun

API reference for the StopAgentRun exception used to exit the tool call loop and complete the agent run.

The StopAgentRun exception allows you to exit the model execution loop and end the agent run. When raised from a tool function, the agent exits the tool call loop after the current batch of tool calls completes, and the run status is set to COMPLETED. When the agent has a configured database, runs outside a team or workflow, and has session data, Agno saves the session.

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 added to the conversation as a user message before the run stops.

agent_message · Union[str, Message]

An optional message added to the conversation as an assistant message before the run stops.

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. Remaining tool calls in the current batch finish executing
2. No further LLM iterations run; the tool call loop exits after the current batch
3. The run status is set to COMPLETED
4. Agno saves the session when the agent has a configured database, runs outside a team or workflow, and has session data
5. All messages, tool calls, and tool results up to that point are preserved
6. Any user_message or agent_message is added to the conversation history before the run completes

See Also

• RetryAgentRun Exception
• Exceptions & Retries Guide