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 with the builder’s preloaded transcript and pending-input queue baked in. The typical usage pattern is:

1. Call next to advance the loop.
2. Handle the returned LoopStep:
   • LoopStep::Finished – the turn completed, inspect the result.
   • LoopStep::Interrupt – resolve the interrupt via the bound Pending* handle, then call next again.

Example

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

let step = driver.next().await?;
match step {
    LoopStep::Finished(result) => println!("Done: {:?}", result.finish_reason),
    LoopStep::Interrupt(interrupt) => {
        // Resolve via the pending handle, 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>

Internal entry point for buffering user input. Reachable only via InputRequest::submit (resolves an AwaitingInput interrupt, including the very first one after Agent::start) and ToolRoundInfo::submit (interjects between tool rounds). Prior transcript items — the passive starting state of a session — are preloaded via AgentBuilder::transcript; an opening user turn for one-shot calls is preloaded via AgentBuilder::input. New input after start-up always flows through one of the typed submit handles.

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 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_for_with_patched_input( &mut self, call_id: ToolCallId, input: Value, ) -> Result<(), LoopError>

Resolve a pending LoopInterrupt::ApprovalRequest with a patched input that replaces the model’s original tool arguments.

Equivalent to calling [resolve_approval_for] with ApprovalDecision::Approve except the tool sees input instead of what the model emitted. The transcript still records the model’s original call.

Errors

Returns LoopError::InvalidState if no approval is pending for call_id.

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

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

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(..)). This is the steady state after Agent::start when no input was preloaded via AgentBuilder::input: the prior transcript loaded via AgentBuilder::transcript is passive, so the first call surfaces AwaitingInput and waits for the host to supply input via InputRequest::submit before any model turn is dispatched. If input was preloaded, the first call dispatches the model directly.

Errors

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