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::loop_core::Loop;
use loopctl::tool::ToolRegistry;
use loopctl::config::LoopConfig;
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) -> &str { "llm-70b" }
#     fn stream_messages(&self, _req: loopctl::api::StreamRequest)
#         -> std::pin::Pin<Box<dyn futures::Stream<Item = Result<loopctl::stream::StreamEvent, loopctl::stream::StreamError>> + Send>> {
#         unimplemented!()
#     }
# }
let client = Arc::new(MyClient);

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

// 3. Configure
let config = LoopConfig {
    max_turns: 50,
    model: "llm-70b".into(),
    ..Default::default()
};

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

Use the Testing Module

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

use loopctl::testing::{MockApiClient, MockTool, test_config};
use loopctl::engine::BareLoop;
use loopctl::engine::loop_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

Architecture

At the center is BareLoop, the default agent loop. Each turn it streams a response from an ApiClient (your LLM provider), accumulates the result, and 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.