Crate agentkit_loop

Expand description

Runtime-agnostic agent loop orchestration for sessions, turns, tools, and interrupts.

agentkit-loop is the central coordination layer in the agentkit workspace. It drives a model through a multi-turn agentic loop, executing tool calls, respecting permission checks, surfacing approval interrupts to the host application, and optionally compacting the transcript when it grows too large.

§Architecture

The main entry point is Agent, constructed via AgentBuilder. The builder optionally accepts the prior conversation transcript via AgentBuilder::transcript and the next user turn via AgentBuilder::input — both default to empty. Calling Agent::start with a SessionConfig returns a LoopDriver that yields LoopSteps — either a finished turn or an interrupt that requires host resolution before the loop can continue.

If no input was preloaded, the first call to LoopDriver::next yields LoopInterrupt::AwaitingInput and the host supplies the first user turn via InputRequest::submit. If input was preloaded, the first next() dispatches the model directly — convenient for one-shot calls.

Agent::builder()
    .model(adapter)              // ModelAdapter implementation
    .add_tool_source(registry)   // ToolRegistry (or any ToolSource); call again to federate
    .permissions(checker)        // PermissionChecker for gating tool use
    .observer(obs)               // LoopObserver for streaming events
    .transcript(prior)           // optional: passive prior transcript (system prompt, resumed session)
    .input(first_user_turn)      // optional: preload next user turn so first next() drives a turn
    .build()?
    .start(config).await?  -> LoopDriver
        .next().await?     -> LoopStep::Finished | LoopStep::Interrupt(...)

§Example

use agentkit_core::{Item, ItemKind};
use agentkit_loop::{
    Agent, PromptCacheRequest, PromptCacheRetention, SessionConfig,
};

// One-shot: preload system prompt and first user message; first next()
// drives the model directly.
let agent = Agent::builder()
    .model(adapter)
    .transcript(vec![Item::text(ItemKind::System, "You are a helpful assistant.")])
    .input(vec![Item::text(ItemKind::User, "Hello!")])
    .build()?;

let mut driver = agent
    .start(SessionConfig::new("demo").with_cache(
        PromptCacheRequest::automatic().with_retention(PromptCacheRetention::Short),
    ))
    .await?;

let _ = driver.next().await?;

Structs§

Agent: A configured agent ready to start a session.
AgentBuilder: Builder for constructing an Agent.
InputRequest: Descriptor for a LoopInterrupt::AwaitingInput interrupt.
LoopCtx: Read-only context handed to a LoopMutator alongside the cursor.
LoopDriver: The runtime driver that advances the agent loop step by step.
LoopSnapshot: A read-only snapshot of the loop driver’s current state.
ModelTurnResult: Final result produced by a single model turn.
PendingApproval: Handle for a pending approval interrupt.
PromptCacheRequest: Prompt caching request sent alongside a turn.
SessionConfig: Configuration required to start a new model session.
ToolRoundInfo: Metadata describing a completed tool round, surfaced via LoopInterrupt::AfterToolResult.
TranscriptCursor: Mutable handle over the live transcript with dirty tracking.
TurnRequest: Payload sent to the model at the start of each turn.
TurnResult: Outcome of a completed (or cancelled) turn.

Enums§

AgentEvent: Lifecycle and streaming events emitted by the LoopDriver.
LoopError: Errors that can occur while driving the agent loop.
LoopInterrupt: An interrupt that pauses the agent loop until the host resolves it.
LoopStep: The result of advancing the agent loop by one step.
ModelTurnEvent: Streaming event emitted by a ModelTurn during generation.
MutationPoint: Where in the loop a LoopMutator is given a chance to modify the transcript. Mutators run synchronously at these points; mid-stream mutation (e.g. between content deltas) is intentionally not supported because the assistant item is not yet fully constructed.
PromptCacheBreakpoint: Prefix boundary that a provider should cache when using explicit caching.
PromptCacheMode: Strength of a prompt-cache request.
PromptCacheRetention: High-level provider-neutral cache retention hint.
PromptCacheStrategy: Provider-neutral prompt caching strategy.

Traits§

EventEmitter: Sink for emitting AgentEvents from inside a LoopMutator. The driver supplies a concrete implementation via LoopCtx::emitter.
LoopMutator: Async transcript mutator. Registered via AgentBuilder::mutator and invoked at each MutationPoint. Mutators own their derived state (e.g. running token totals via interior mutability) and decide for themselves whether and how to modify the transcript.
LoopObserver: Observer hook for streaming agent events to the host application.
ModelAdapter: Factory for creating model sessions.
ModelSession: An active model session that can produce sequential turns.
ModelTurn: A streaming model turn that yields events one at a time.
TranscriptObserver: Receives full Items as they are appended to the driver’s transcript.