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 and authentication 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. After calling Agent::start you receive a LoopDriver that yields LoopSteps – either a finished turn or an interrupt that requires host resolution before the loop can continue.

Agent::builder()
    .model(adapter)        // ModelAdapter implementation
    .tools(registry)       // ToolRegistry with registered tools
    .permissions(checker)  // PermissionChecker for gating tool use
    .observer(obs)         // LoopObserver for streaming events
    .build()?
    .start(config).await?  -> LoopDriver
        .submit_input(...)
        .next().await?     -> LoopStep::Finished | LoopStep::Interrupt

§Example

use agentkit_loop::{Agent, PromptCacheRequest, PromptCacheRetention, SessionConfig};

let agent = Agent::builder()
    .model(adapter)
    .build()?;

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

Structs§

Agent: A configured agent ready to start a session.
AgentBuilder: Builder for constructing an Agent.
InputRequest: Descriptor for a LoopInterrupt::AwaitingInput interrupt.
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.
PendingAuth: Handle for a pending authentication interrupt.
PromptCacheRequest: Prompt caching request sent alongside a turn.
SessionConfig: Configuration required to start a new model session.
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.
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§

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.