Reagent

Reagent is a Rust library for building and running AI agents that interact with LLMs. It abstracts away provider-specific details (currently supports Ollama and OpenRouter), provides a consistent API for prompting, structured outputs, and tool use, and allows you to define fully custom invocation flows.

You can add the library to your project by pulling from crates:

cargo add reagent-rs

or directly from github:

[dependencies]
reagent = { git = "https://github.com/VakeDomen/Reagent" }

Notes

Reagent is experimental and provider support may change.
Not all provider features are unified;

Features

Multiple providers: Ollama (default) and OpenRouter (experimental)
Structured output via JSON Schema (manual or via schemars)
Tooling:
- Define tools with input schemas
- Register async executors for tool calls
- Integrate MCP (Model Context Protocol) servers as tools
Flows:
- Default flows for common patterns
- Custom flows and closures
- Prebuilt flows for quick prototyping
Prompt templates with runtime or dynamic data sources
Notifications: subscribe to agent events like token streaming, tool calls, errors, etc.

Quick Start

use std::error::Error;
use reagent::AgentBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {

    let mut agent = AgentBuilder::default()
        .set_model("qwen3:0.6b")
        .set_system_prompt("You are a helpful assistant.")
        .build()
        .await?;

    let resp = agent.invoke_flow("Hello!").await?;
    println!("Agent response: {}", resp.content.unwrap_or_default());

    Ok(())
}

Building Agents

The AgentBuilder uses a builder pattern. Only model is required; everything else has defaults.

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_system_prompt("You are a helpful assistant.")
    .set_temperature(0.7)
    .set_num_ctx(2048)
    .build()
    .await?;

Providers

By default, Reagent assumes an Ollama instance running locally.

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_provider(Provider::Ollama)
    .set_base_url("http://localhost:11434")
    .build()
    .await?;

To use OpenRouter:

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_provider(Provider::OpenRouter)
    .set_api_key("YOUR_KEY")
    .build()
    .await?;

Note: some providers require provider-specific response format settings.

Structured Output

You can ask the model to return JSON that matches a schema.

Manual schema:

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_response_format(r#"{
        "type":"object",
        "properties":{
            "windy":{"type":"boolean"},
            "temperature":{"type":"integer"},
            "description":{"type":"string"}
        },
        "required":["windy","temperature","description"]
    }"#)
    .build()
    .await?;

From struct via schemars:

#[derive(JsonSchema)]
struct Weather { 
    windy: bool, 
    temperature: i32, 
    description: String 
}

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_response_format(serde_json::to_string_pretty(&schema_for!(Weather))?)
    .build()
    .await?;

To get parsed output directly:

let resp: Weather = agent.invoke_flow_structured_output("What's the weather?").await?;

Tools

Tools let the model call custom functions. Define an executor closure, wrap it in a ToolBuilder, and register it with the agent.

let exec: AsyncToolFn = Arc::new(|args: Value| Box::pin(async move {
    // do your thing
    Ok(r#"{"windy":false,"temperature":18}"#.into())
}));

let tool = ToolBuilder::new()
    .function_name("get_weather")
    .add_required_property("location", "string", "City name")
    .executor(exec)
    .build()?;

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .add_tool(tool)
    .add_mcp_server(McpServerType::sse("http://localhost:8000/sse"))
    .add_mcp_server(McpServerType::stdio("npx -y @<something/memory>"))
    .add_mcp_server(McpServerType::streamable_http("http://localhost:8001/mcp"))
    .build()
    .await?;

Flows

Flows control how the agent is invoked.

Default flow: prompt -> LLM -> (maybe tool call -> LLM) -> result
Prebuilt flows: e.g., reply, reply_without_tools, call_tools, plan_and_execute
Custom flow functions:

fn my_flow<'a>(agent: &'a mut Agent, prompt: String) -> FlowFuture<'a> {
    Box::pin(async move {
        // custom logic
        Ok(Message::assistant("Hello"))
    })
}

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_flow(Flow::Custom(my_flow))
    .build()
    .await?;

Custom flow closures: inline with Flow::new_closure

Templates

Define prompts with placeholders:

let template = Template::simple("Hello {{name}}!");

let agent = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_template(template)
    .build()
    .await?;

let prompt_data = HashMap::from([
    ("name", "Peter"),
]);

let resp = agent.invoke_flow_with_template(prompt_data).await?;

Pass a HashMap of values to invoke_flow_with_template.

You can also provide a TemplateDataSource that injects dynamic values at invocation time.

Notifications & Streaming

You can receive events from the agent using build_with_notification:

let (agent, mut rx) = AgentBuilder::default()
    .set_model("qwen3:0.6b")
    .set_stream(true)
    .build_with_notification()
    .await?;

Prebuilds

For quick experiments, StatelessPrebuild and StatefullPrebuild offer presets some simple flow patterns. Stateful versions keep conversation history; stateless ones reset each call.

Examples:

let agent = StatelessPrebuild::reply()
    .set_model("qwen3:0.6b")
    .build()
    .await?;
let agent = StatefullPrebuild::call_tools()
    .set_model("qwen3:0.6b")
    .build()
    .await?;

License

MIT

reagent-rs 0.2.0