loopctl

A trait-based framework for building agent loops with pluggable LLM clients, tools, and memory.

Overview

loopctl provides the core infrastructure for building LLM-based agent loops: a streaming API client abstraction, tool registry, loop detection and convergence, fallback model chains, cancellation, and a default loop engine (BareLoop). You bring your own LLM provider client and tool implementations; the framework handles the rest.

Modules

Quick Start

Implement a Tool

use loopctl::tool::{Tool, ToolContext, ToolOutput, ToolError, ToolSchema};
use serde_json::{Value, json};
use std::pin::Pin;
use std::future::Future;

struct EchoTool;

impl Tool for EchoTool {
    fn name(&self) -> &str { "echo" }
    fn description(&self) -> &str { "Echoes back the input" }

    fn schema(&self) -> ToolSchema {
        ToolSchema {
            tool: "echo".into(),
            description: "Echoes back the input".into(),
            input_schema: json!({
                "type": "object",
                "properties": { "message": { "type": "string" } },
                "required": ["message"]
            }),
        }
    }

    fn call(&self, input: Value, _ctx: &ToolContext)
        -> Pin<Box<dyn Future<Output = Result<ToolOutput, ToolError>> + Send + '_>>
    {
        let msg = input["message"].as_str().unwrap_or("").to_string();
        Box::pin(async move { Ok(ToolOutput::text(msg)) })
    }
}

Run an Agent Loop

use loopctl::engine::BareLoop;
use loopctl::engine::core::Loop;
use loopctl::engine::RunConfig;
use loopctl::tool::ToolRegistry;
use loopctl::config::SessionConfig;
use std::sync::Arc;

// 1. Bring your own API client (implements ApiClient trait)
# struct MyClient;
# use loopctl::api::ApiClient;
# impl ApiClient for MyClient {
#     fn model(&self) -> String { "llm-70b".to_string() }
#     fn stream_messages(&self, _req: &loopctl::api::StreamRequest)
#         -> std::pin::Pin<Box<dyn futures::Stream<Item = Result<loopctl::stream::StreamEvent, loopctl::api::error::ApiError>> + Send>> {
#         unimplemented!()
#     }
# }
let client = Arc::new(MyClient);

// 2. Register tools
let mut registry = ToolRegistry::new();
// registry.register(EchoTool);

// 3. Configure
let config = SessionConfig::default();

// 4. Run
let mut agent = BareLoop::new(client, registry, config);
// let result = agent.run("Use the echo tool to say hello", &RunConfig::default()).await?;
// println!("Completed in {} turns", result.turn_count());

Use the Testing Module

[dev-dependencies]
loopctl = { version = "0.3", features = ["testing"] }

use loopctl::testing::{MockApiClient, MockTool, test_config};
use loopctl::engine::BareLoop;
use loopctl::engine::core::Loop;
use loopctl::tool::ToolRegistry;
use std::sync::Arc;

let mut client = MockApiClient::new("test-model");
client = client.with_text_response("Hello from the mock");

let mut registry = ToolRegistry::new();
registry.register(MockTool::new("demo", "A demo tool"));

let agent = BareLoop::new(
    Arc::new(client),
    registry,
    test_config(),
);
// let result = agent.run("test input").await?;

Feature Flags

Streaming vs non-streaming

The engine selects a turn mode at runtime via TurnMode (NonStreaming or Streaming), set with set_turn_mode. The two modes are independent of whether the streaming feature is compiled in, though the feature gates what Streaming can do:

• TurnMode::NonStreaming drives each turn via [ApiClient::create_message] — a single request/response with no per-delta callbacks. The full assistant text surfaces through on_response. Always available, even under default = [].

• TurnMode::Streaming routes turns through StreamHandler with retry, timeout, rate-limit detection, and on_text_delta / on_thinking_delta callbacks for real-time token display. Requires the streaming feature (implied by every HTTP provider).

The constructor default is Streaming when the streaming feature is enabled and NonStreaming otherwise — but a constructed loop can switch to either mode at runtime regardless of the default.

Architecture

At the center is BareLoop, the default agent loop. Each turn it requests a response from an ApiClient (your LLM provider) — via the streaming path (StreamHandler) under TurnMode::Streaming, or via create_message under TurnMode::NonStreaming — then dispatches any requested tool calls through a ToolRegistry. Results are fed back into the conversation and the cycle repeats until the model ends its turn or a configured limit is reached.

Two cross-cutting concerns run alongside the main loop:

• Detection & Fallback — convergence detection, loop detection, and automatic model/API fallback when requests fail.
• ToolRegistry — holds your registered tools and routes tool calls to them.

Development

make ci        # fmt + check + clippy + test + docs (all features)
make test      # run all tests
make lint      # auto-format

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.