Struct LoopDriver 

pub struct LoopDriver<S>
where
    S: ModelSession,
{ /* private fields */ }

The runtime driver that advances the agent loop step by step.

Obtained from Agent::start. The typical usage pattern is:

1. Call submit_input to enqueue user messages.
2. Call next to run the next turn.
3. Handle the returned LoopStep:
   • LoopStep::Finished – the turn completed, inspect the result.
   • LoopStep::Interrupt – resolve the interrupt and call next again.

Example

use agentkit_core::{Item, ItemKind};
use agentkit_loop::{LoopDriver, LoopStep};

driver.submit_input(vec![Item::text(ItemKind::User, "Hello!")])?;

let step = driver.next().await?;
match step {
    LoopStep::Finished(result) => println!("Done: {:?}", result.finish_reason),
    LoopStep::Interrupt(interrupt) => {
        // Resolve the interrupt (approval, auth, or input), then call next() again.
        println!("Interrupted: {interrupt:?}");
    }
}

Implementations

impl<S> LoopDriver<S>

where S: ModelSession,

pub fn submit_input(&mut self, input: Vec<Item>) -> Result<(), LoopError>

Enqueue user input items for the next turn.

Items are buffered and consumed the next time next is called. Must not be called while an interrupt is pending.

Errors

Returns LoopError::InvalidState if an interrupt is still unresolved.

pub fn set_next_turn_cache( &mut self, cache: PromptCacheRequest, ) -> Result<(), LoopError>

Override the prompt cache request for the next model turn.

The override is consumed the next time the driver starts a model turn. Session-level defaults still apply to later turns.

pub fn submit_input_with_cache( &mut self, input: Vec<Item>, cache: PromptCacheRequest, ) -> Result<(), LoopError>

Enqueue user input and set a prompt cache override for the next model turn in one call.

pub fn resolve_approval_for( &mut self, call_id: ToolCallId, decision: ApprovalDecision, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest.

After calling this, invoke next to continue the loop. If the decision is ApprovalDecision::Approve the tool call executes; if denied, an error result is fed back to the model.

Errors

Returns LoopError::InvalidState if no approval is pending.

pub fn resolve_approval( &mut self, decision: ApprovalDecision, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest when exactly one approval is outstanding.

pub fn resolve_auth( &mut self, resolution: AuthResolution, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::AuthRequest.

The resolution must reference the same request id as the pending AuthRequest. After calling this, invoke next to continue the loop.

Errors

Returns LoopError::InvalidState if no auth request is pending or if the resolution’s request id does not match.

pub fn snapshot(&self) -> LoopSnapshot

Take a read-only snapshot of the driver’s current transcript and input queue.

pub async fn next(&mut self) -> Result<LoopStep, LoopError>

Advance the loop by one step.

This is the main method for driving the agent. It processes pending interrupt resolutions, consumes queued input, starts a model turn, executes tool calls, and returns once the turn finishes or an interrupt occurs.

If no input is queued and no interrupt is pending, returns LoopStep::Interrupt(LoopInterrupt::AwaitingInput(..)).

Errors

Returns LoopError::InvalidState if called while an unresolved interrupt is pending, or propagates provider / tool / compaction errors.