Struct AgentRunner 

pub struct AgentRunner { /* private fields */ }

Manages an Agent across multiple conversation turns.

Preserves transcript between turns, emits events via a caller-provided channel, and tracks cumulative turn count. Each call to turn() runs the agent once with the given goal, then restores the transcript so the next turn continues the conversation.

Optionally holds a reference to a shared BackgroundJobManager. When clear() is called, any pending background jobs are also cleared.

Example

let mut runner = AgentRunner::new(agent);
let (tx, mut rx) = mpsc::unbounded_channel();

// First turn
let outcome = runner.turn("Hello", Some(tx.clone())).await?;

// Second turn — transcript from turn 1 is preserved
let outcome = runner.turn("Follow up", Some(tx.clone())).await?;

// Start fresh
runner.clear();

Implementations

impl AgentRunner

pub fn new(agent: Agent) -> Self

Create a runner from a pre-built Agent.

pub fn with_bg_manager( agent: Agent, bg_manager: Arc<Mutex<BackgroundJobManager>>, ) -> Self

Create a runner that also manages background jobs.

When clear() is called, all tracked background jobs are removed from the shared manager in addition to clearing the transcript.

pub async fn turn( &mut self, goal: impl Into<String>, events: Option<UnboundedSender<StepEvent>>, ) -> Result<AgentOutcome>

Run a single turn with the given goal.

If events is Some(sender), step events are streamed through the channel in real time. Pass None to suppress events.

The transcript is automatically preserved for the next turn. Returns the outcome of this turn.

pub fn clear(&mut self)

Clear the conversation history and reset the turn counter.

If a BackgroundJobManager was provided, all tracked background jobs are also removed.

pub fn turns(&self) -> usize

Number of turns completed so far.

pub fn agent(&self) -> &Agent

Access the underlying agent (e.g., to call confirm_plan).

pub fn agent_mut(&mut self) -> &mut Agent

Mutable access to the underlying agent.

pub async fn run_loop( &mut self, initial_goal: impl Into<String>, wakeup_slot: &WakeupSlot, events: Option<UnboundedSender<StepEvent>>, ) -> Result<Vec<AgentOutcome>>

Run a loop: execute turns until the agent stops scheduling wakeups.

Between turns, sleeps for the requested delay. If the agent doesn’t call schedule_wakeup during a turn, the loop ends.

The wakeup_slot should be the same slot registered with the ScheduleWakeup tool in the agent’s tool registry.

pub async fn run_event_loop( &mut self, initial_goal: impl Into<String>, wakeup_slot: &WakeupSlot, events: Option<UnboundedSender<StepEvent>>, ) -> Result<Vec<AgentOutcome>>

Run a loop with background job awareness.

After each turn, checks both:

1. The WakeupSlot for an explicit wakeup request (from schedule_wakeup tool)
2. The BackgroundJobManager for completed jobs

If a background job completed, its output is injected as the next turn’s goal. If a wakeup was scheduled, the runner sleeps for the requested delay then continues. If neither is present, the loop ends.

The wakeup_slot should be the same slot registered with the ScheduleWakeup tool in the agent’s tool registry.