Struct Agent 

pub struct Agent {
    pub history: Box<dyn History>,
    /* private fields */
}

Agent loop that coordinates LLM calls and tool execution. Uses ParallelExecutor by default.

Fields

history: Box<dyn History>

Implementations

impl Agent

pub fn new(llm: impl LLMProvider + 'static) -> Self

Create a new agent loop

Examples found in repository

examples/chatbot.rs (line 15)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm).system("You are a helpful assistant");

    run_cli_loop(agent).await
}

examples/history.rs (line 42)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .history(CustomHistory::new(3));

    run_cli_loop(agent).await
}

examples/fn_tools.rs (line 35)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .tool(get_weather)
        .tool(add);

    run_cli_loop(agent).await
}

examples/bind_tools.rs (line 83)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let mut data = HashMap::new();
    data.insert("name".to_string(), "Alice".to_string());
    data.insert("age".to_string(), "30".to_string());

    let r = ReadonlyTool {
        data: Arc::new(data),
    };

    let w = WritableTool {
        data: Arc::new(Mutex::new(HashMap::new())),
    };

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .bind(r.clone(), ReadonlyTool::fetch)
        .bind(w.clone(), WritableTool::read)
        .bind(w, WritableTool::write);

    run_cli_loop(agent).await
}

examples/mcp.rs (line 73)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to a server running as a child process
    let service = ()
        .serve(TokioChildProcess::new(Command::new("npx").configure(
            |cmd| {
                cmd.args(&["-y", "@modelcontextprotocol/server-filesystem", "."]);
            },
        ))?)
        .await?;
    println!("Connected to MCP server");

    // List available tools and convert to tool definitions
    let tools = service.list_tools(Default::default()).await?.tools;
    let names = tools.iter().map(|t| t.name.to_string()).collect::<Vec<_>>();
    println!("Available tools: {names:#?}");
    let mcp_tool_defs = tools
        .iter()
        .map(|t| ToolDefinition {
            tool_type: "function".into(),
            function: ToolFunction {
                name: t.name.to_string(),
                description: t.description.as_deref().unwrap_or_default().to_string(),
                parameters: Parameters::from_object(t.input_schema.as_ref().clone()),
            },
        })
        .collect();

    let mcp_tool_executor = {
        let peer = service.clone();
        move |name: String, args: String| {
            let peer = peer.clone();
            async move {
                peer.call_tool(CallToolRequestParams {
                    meta: None,
                    name: name.into(),
                    arguments: serde_json::from_str(&args).unwrap(),
                    task: None,
                })
                .await
                .unwrap()
                .content[0]
                    .as_text()
                    .unwrap()
                    .text
                    .clone()
            }
        }
    };

    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .external(mcp_tool_defs, mcp_tool_executor);

    run_cli_loop(agent).await;

    // Gracefully close the connection
    service.cancel().await?;
    Ok(())
}

pub fn stream_callback<F>(self, callback: F) -> Self

where F: FnMut(String) + Send + 'static,

Set stream callback for LLM responses

Example

use tiny_loop::{Agent, llm::OpenAIProvider};

let agent = Agent::new(OpenAIProvider::new())
    .stream_callback(|chunk| print!("{}", chunk));

Examples found in repository

examples/common/streaming_cli.rs (lines 5-8)

pub async fn run_cli_loop(agent: Agent) {
    let mut agent = agent.stream_callback(|chunk| {
        print!("{}", chunk);
        io::stdout().flush().unwrap();
    });

    println!("Chatbot started. Type 'quit' to exit.\n");

    loop {
        print!("> ");
        io::stdout().flush().unwrap();

        let mut input = String::new();
        io::stdin().read_line(&mut input).unwrap();
        let input = input.trim();

        if input == "quit" {
            break;
        }

        match agent.chat(input).await {
            Ok(_) => println!("\n"),
            Err(e) => eprintln!("Error: {}\n", e),
        }
    }
}

pub fn history(self, history: impl History + 'static) -> Self

Set custom history manager (default: InfiniteHistory)

Example

use tiny_loop::{Agent, history::InfiniteHistory, llm::OpenAIProvider};

let agent = Agent::new(OpenAIProvider::new())
    .history(InfiniteHistory::new());

Examples found in repository

examples/history.rs (line 44)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .history(CustomHistory::new(3));

    run_cli_loop(agent).await
}

pub fn system(self, content: impl Into<String>) -> Self

Append a system message

Example

use tiny_loop::{Agent, llm::OpenAIProvider};

let agent = Agent::new(OpenAIProvider::new())
    .system("You are a helpful assistant");

Examples found in repository

examples/chatbot.rs (line 15)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm).system("You are a helpful assistant");

    run_cli_loop(agent).await
}

examples/history.rs (line 43)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .history(CustomHistory::new(3));

    run_cli_loop(agent).await
}

examples/fn_tools.rs (line 36)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .tool(get_weather)
        .tool(add);

    run_cli_loop(agent).await
}

examples/bind_tools.rs (line 84)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let mut data = HashMap::new();
    data.insert("name".to_string(), "Alice".to_string());
    data.insert("age".to_string(), "30".to_string());

    let r = ReadonlyTool {
        data: Arc::new(data),
    };

    let w = WritableTool {
        data: Arc::new(Mutex::new(HashMap::new())),
    };

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .bind(r.clone(), ReadonlyTool::fetch)
        .bind(w.clone(), WritableTool::read)
        .bind(w, WritableTool::write);

    run_cli_loop(agent).await
}

examples/mcp.rs (line 74)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to a server running as a child process
    let service = ()
        .serve(TokioChildProcess::new(Command::new("npx").configure(
            |cmd| {
                cmd.args(&["-y", "@modelcontextprotocol/server-filesystem", "."]);
            },
        ))?)
        .await?;
    println!("Connected to MCP server");

    // List available tools and convert to tool definitions
    let tools = service.list_tools(Default::default()).await?.tools;
    let names = tools.iter().map(|t| t.name.to_string()).collect::<Vec<_>>();
    println!("Available tools: {names:#?}");
    let mcp_tool_defs = tools
        .iter()
        .map(|t| ToolDefinition {
            tool_type: "function".into(),
            function: ToolFunction {
                name: t.name.to_string(),
                description: t.description.as_deref().unwrap_or_default().to_string(),
                parameters: Parameters::from_object(t.input_schema.as_ref().clone()),
            },
        })
        .collect();

    let mcp_tool_executor = {
        let peer = service.clone();
        move |name: String, args: String| {
            let peer = peer.clone();
            async move {
                peer.call_tool(CallToolRequestParams {
                    meta: None,
                    name: name.into(),
                    arguments: serde_json::from_str(&args).unwrap(),
                    task: None,
                })
                .await
                .unwrap()
                .content[0]
                    .as_text()
                    .unwrap()
                    .text
                    .clone()
            }
        }
    };

    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .external(mcp_tool_defs, mcp_tool_executor);

    run_cli_loop(agent).await;

    // Gracefully close the connection
    service.cancel().await?;
    Ok(())
}

pub fn executor(self, executor: impl ToolExecutor + 'static) -> Self

Set a custom tool executor (default: ParallelExecutor)

Example

use tiny_loop::{Agent, tool::SequentialExecutor, llm::OpenAIProvider};

let agent = Agent::new(OpenAIProvider::new())
    .executor(SequentialExecutor::new());

pub fn tool<Args, Fut>(self, tool: fn(Args) -> Fut) -> Self

where Fut: Future<Output = String> + Send + 'static, Args: ToolArgs + 'static,

Register a tool function created by #[tool]

To register a tool method with an instance, use Self::bind. To register external tools (e.g. from MCP servers) use Self::external

Example

use tiny_loop::{Agent, tool::tool, llm::OpenAIProvider};

#[tool]
async fn fetch(
    /// URL to fetch
    url: String,
) -> String {
    todo!()
}

let agent = Agent::new(OpenAIProvider::new())
    .tool(fetch);

Examples found in repository

examples/fn_tools.rs (line 37)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .tool(get_weather)
        .tool(add);

    run_cli_loop(agent).await
}

pub fn bind<T, Args, Fut>(self, ins: T, tool: fn(T, Args) -> Fut) -> Self

where T: Send + Sync + Clone + 'static, Fut: Future<Output = String> + Send + 'static, Args: ToolArgs + 'static,

Bind an instance to a tool method created by #[tool]

To register a standalone tool function, use Self::tool. To register external tools (e.g. from MCP servers) use Self::external

Example

use tiny_loop::{Agent, tool::tool, llm::OpenAIProvider};
use std::sync::Arc;

#[derive(Clone)]
struct Database {
    data: Arc<String>,
}

#[tool]
impl Database {
    /// Fetch data from database
    async fn fetch(
        self,
        /// Data key
        key: String,
    ) -> String {
        todo!()
    }
}

let db = Database { data: Arc::new("data".into()) };
let agent = Agent::new(OpenAIProvider::new())
    .bind(db, Database::fetch);

Examples found in repository

examples/bind_tools.rs (line 85)

async fn main() {
    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let mut data = HashMap::new();
    data.insert("name".to_string(), "Alice".to_string());
    data.insert("age".to_string(), "30".to_string());

    let r = ReadonlyTool {
        data: Arc::new(data),
    };

    let w = WritableTool {
        data: Arc::new(Mutex::new(HashMap::new())),
    };

    let agent = Agent::new(llm)
        .system("You are a helpful assistant with access to tools")
        .bind(r.clone(), ReadonlyTool::fetch)
        .bind(w.clone(), WritableTool::read)
        .bind(w, WritableTool::write);

    run_cli_loop(agent).await
}

pub fn external<Fut>( self, defs: Vec<ToolDefinition>, exec: impl Fn(String, String) -> Fut + Clone + Send + Sync + 'static, ) -> Self

where Fut: Future<Output = String> + Send + 'static,

Register external tools (e.g. from MCP servers)

To register a standalone tool function, use tool. To register a tool method with an instance, use bind.

Example

use tiny_loop::{Agent, llm::OpenAIProvider, types::{Parameters, ToolDefinition, ToolFunction}};
use serde_json::{json, Value};

let defs = vec![ToolDefinition {
    tool_type: "function".into(),
    function: ToolFunction {
        name: "get_weather".into(),
        description: "Get weather information".into(),
        parameters: Parameters::from_object(
            json!({
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    }
                },
                "required": ["city"]
            }).as_object().unwrap().clone()
        ),
    },
}];

let external_executor = move |name: String, args: String| {
    async move {
        let _args = serde_json::from_str::<Value>(&args).unwrap();
        "result".into()
    }
};

let agent = Agent::new(OpenAIProvider::new())
    .external(defs, external_executor);

Examples found in repository

examples/mcp.rs (line 75)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to a server running as a child process
    let service = ()
        .serve(TokioChildProcess::new(Command::new("npx").configure(
            |cmd| {
                cmd.args(&["-y", "@modelcontextprotocol/server-filesystem", "."]);
            },
        ))?)
        .await?;
    println!("Connected to MCP server");

    // List available tools and convert to tool definitions
    let tools = service.list_tools(Default::default()).await?.tools;
    let names = tools.iter().map(|t| t.name.to_string()).collect::<Vec<_>>();
    println!("Available tools: {names:#?}");
    let mcp_tool_defs = tools
        .iter()
        .map(|t| ToolDefinition {
            tool_type: "function".into(),
            function: ToolFunction {
                name: t.name.to_string(),
                description: t.description.as_deref().unwrap_or_default().to_string(),
                parameters: Parameters::from_object(t.input_schema.as_ref().clone()),
            },
        })
        .collect();

    let mcp_tool_executor = {
        let peer = service.clone();
        move |name: String, args: String| {
            let peer = peer.clone();
            async move {
                peer.call_tool(CallToolRequestParams {
                    meta: None,
                    name: name.into(),
                    arguments: serde_json::from_str(&args).unwrap(),
                    task: None,
                })
                .await
                .unwrap()
                .content[0]
                    .as_text()
                    .unwrap()
                    .text
                    .clone()
            }
        }
    };

    let api_key = std::env::var("LLM_API_KEY").expect("LLM_API_KEY not set");

    let llm = OpenAIProvider::new()
        .api_key(api_key)
        .base_url("https://openrouter.ai/api/v1")
        .model("google/gemini-3-flash-preview");

    let agent = Agent::new(llm)
        .system("You are a helpful assistant")
        .external(mcp_tool_defs, mcp_tool_executor);

    run_cli_loop(agent).await;

    // Gracefully close the connection
    service.cancel().await?;
    Ok(())
}

pub async fn run(&mut self) -> Result<String>

Run the agent loop until completion. Return the last AI’s response

pub async fn chat(&mut self, prompt: impl Into<String>) -> Result<String>

Run the agent loop with a new user input appended. Return the last AI’s response

Examples found in repository

examples/common/streaming_cli.rs (line 24)

pub async fn run_cli_loop(agent: Agent) {
    let mut agent = agent.stream_callback(|chunk| {
        print!("{}", chunk);
        io::stdout().flush().unwrap();
    });

    println!("Chatbot started. Type 'quit' to exit.\n");

    loop {
        print!("> ");
        io::stdout().flush().unwrap();

        let mut input = String::new();
        io::stdin().read_line(&mut input).unwrap();
        let input = input.trim();

        if input == "quit" {
            break;
        }

        match agent.chat(input).await {
            Ok(_) => println!("\n"),
            Err(e) => eprintln!("Error: {}\n", e),
        }
    }
}