Struct AgentLoop 

pub struct AgentLoop { /* private fields */ }

Stable since 0.63.0

AgentLoop.

Implementations

impl AgentLoop

pub fn new_with_resolver( provider: Arc<dyn Provider>, config: AgentLoopConfig, tools: Arc<ToolRegistry>, state: SharedState, resolver: Arc<dyn ProviderResolver>, ) -> AgentLoop

Creates a new AgentLoop with an explicit provider resolver. Use this when the model ID needs to be resolved to a provider+model pair using custom logic (e.g., per-session routing).

pub fn new( provider: Arc<dyn Provider>, config: AgentLoopConfig, tools: Arc<ToolRegistry>, state: SharedState, ) -> AgentLoop

Create a new AgentLoop using the global resolver (backward compat).

pub fn with_before_tool_call( self, hook: Arc<dyn Fn(&str, &Value) -> Pin<Box<dyn Future<Output = Result<Option<AgentToolResult>, Error>> + Send>> + Send + Sync>, ) -> AgentLoop

Registers a hook called before every tool execution. The hook can inspect and modify tool arguments, or reject the call entirely.

pub fn with_after_tool_call( self, hook: Arc<dyn Fn(&str, &AgentToolResult) -> Pin<Box<dyn Future<Output = Result<Option<AgentToolResult>, Error>> + Send>> + Send + Sync>, ) -> AgentLoop

Registers a hook called after every tool execution. The hook receives the tool name, arguments, and result.

pub fn steer(&self, message: Message)

Inject a steering message into the agent loop.

Steering messages are processed at the start of each turn, before the next LLM call. If the steering queue is at capacity (256 messages), the message is dropped and a warning is logged.

pub fn follow_up(&self, message: Message)

Enqueue a follow-up message to continue the conversation after all tool calls in the current batch are complete.

If the follow-up queue is at capacity (64 messages), the message is dropped and a warning is logged.

pub fn clear_steering_queue(&self)

Removes all pending steering messages from the queue. See steer() for an explanation of steering messages.

pub fn clear_follow_up_queue(&self)

Removes all pending follow-up messages from the queue. See follow_up() for an explanation of follow-up messages.

pub fn clear_all_queues(&self)

Removes all pending messages from both the steering and follow-up queues.

pub fn cancel_auto_retry(&self)

Cancels any in-progress auto-retry countdown. After calling this, the agent will not automatically retry on the next turn.

pub fn auto_retry_attempt(&self) -> usize

Returns the current auto-retry attempt number (0-based). Useful for displaying retry status in the UI.

pub fn state(&self) -> &SharedState

Get a reference to the shared state. Used by Agent to sync state after loop execution.

pub fn external_stop(&self) -> &Arc<Atomic<bool>>

Get the external stop flag.

pub fn set_cancel_signal(&mut self, flag: Arc<Atomic<bool>>)

Sets a shared cancel signal (typically Agent::cancel_flag). The streaming loop checks this in its periodic wake-up timer, ensuring cancellation is detected even when the provider stream produces no events (e.g. waiting for first token).

pub fn set_auto_retry_state( &mut self, enabled: Arc<Atomic<bool>>, cancel: Arc<Atomic<bool>>, notify: Arc<Notify>, )

Install shared auto-retry state (enabled flag + cancel + notify) so the owning Agent can toggle auto-retry and abort an in-progress retry at runtime. Called once per run, mirroring Self::set_cancel_signal. Also defensively resets the cancel flag so a prior abort_retry does not bleed into this run (retry.rs resets it before each wait regardless).

pub fn cancel_signal(&self) -> Option<Arc<Atomic<bool>>>

Returns a clone of the loop’s cancel-signal flag, if one has been installed via Self::set_cancel_signal. Used by tool execution to bridge the loop’s AtomicBool cancellation into the per-tool oneshot::Receiver cancellation channel (audit finding F-8).

pub fn is_cancelled(&self) -> bool

Returns true if cancellation has been requested via either external_stop or the direct cancel_signal.

pub fn cancel(&self)

Request cancellation from outside the loop (e.g. Ctrl+C). Sets the external_stop flag which causes the streaming loop to abort on its next periodic check (~500ms) and the agent loop to exit after the current turn.

pub fn set_steering_hook( &mut self, hook: Arc<dyn Fn() -> Vec<Message> + Send + Sync>, )

Set the steering hook — called each turn to drain new messages from the session’s steering queue into the loop’s internal queue.

pub fn set_follow_up_hook( &mut self, hook: Arc<dyn Fn() -> Vec<Message> + Send + Sync>, )

Set the follow-up hook — called each turn to drain new messages from the session’s follow-up queue into the loop’s internal queue.

pub async fn run( &self, prompt: String, emit: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<Vec<AgentEvent>, Error>

Runs the agent loop with a single user prompt. Convenience wrapper around run_messages().

pub async fn run_message( &self, message: Message, emit: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<Vec<AgentEvent>, Error>

Run with an explicit initial Message (e.g. a user message carrying image content blocks) instead of a plain-text prompt. Thin wrapper over run_messages(), mirroring run().

pub async fn run_mut<S>( &self, prompt: String, state: S, emit: impl FnMut(AgentEvent, &mut S) + Send + 'static, ) -> Result<(Vec<AgentEvent>, S), Error>

where S: Send + Debug + 'static,

Run with an FnMut callback and mutable state — no Arc<Mutex<>> needed.

Unlike run(), which takes Fn, this method accepts FnMut and a user-provided state value S. The callback receives &mut S on each event, so you can accumulate results without any locking overhead.

Returns the collected events and the final state value.

Example

#[derive(Default)]
struct MyState { steps: usize, output: String }

let (events, state) = agent_loop.run_mut(
    "do something".into(),
    MyState::default(),
    |event, s| {
        match event {
            AgentEvent::ToolExecutionEnd { is_error: false, .. } => s.steps += 1,
            AgentEvent::AgentEnd { messages, .. } => {
                if let Some(Message::Assistant(a)) = messages.last() {
                    s.output = a.text_content();
                }
            }
            _ => {}
        }
    },
).await?;

pub async fn run_messages( &self, prompts: Vec<Message>, emit: Arc<dyn Fn(AgentEvent) + Send + Sync>, ) -> Result<Vec<AgentEvent>, Error>

Runs the agent loop with a list of pre-constructed messages. This is the primary entry point for executing agent turns.

pub async fn continue_loop( &self, emit: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<Vec<AgentEvent>, Error>

Resumes the agent loop after a previous turn ended in a paused state (e.g., waiting for user confirmation). Emits events to the provided callback.