A batteries-included Rust library for building agent workflows. Sync-only, opinionated, and designed for people getting started with agent patterns.

Define agents, wire them into workflows, and let the runner execute them. Agents communicate through shared context and control flow with outcomes like Continue, Next, Retry, and Done.

use agent_line::{Agent, Ctx, Outcome, Runner, StepResult, Workflow};

#[derive(Clone)]
struct State { n: i32 }

struct AddOne;
impl Agent<State> for AddOne {
    fn name(&self) -> &'static str { "add_one" }
    fn run(&mut self, state: State, _ctx: &mut Ctx) -> StepResult<State> {
        Ok((State { n: state.n + 1 }, Outcome::Done))
    }
}

fn main() {
    let mut ctx = Ctx::new();
    let mut agent = AddOne;
    let (state, _) = agent.run(State { n: 1 }, &mut ctx).unwrap();
    println!("n = {}", state.n); // n = 2
}

Agents are registered into a workflow, then wired together with start_at and then. The workflow validates everything at build time.

let wf = Workflow::builder("my-workflow")
    .register(StepA)
    .register(StepB)
    .register(StepC)
    .start_at("step_a")
    .then("step_b")
    .then("step_c")
    .build()
    .unwrap();

let mut runner = Runner::new(wf);
let result = runner.run(initial_state, &mut ctx);

Agents can also route dynamically by returning Outcome::Next("agent_name") instead of Outcome::Continue.

Ctx is shared mutable state passed to every agent. It provides a key-value store and an event log.

let mut ctx = Ctx::new();

// Key-value store
ctx.set("draft", "Hello world");
let val = ctx.get("draft"); // Some("Hello world")
ctx.remove("draft");

// Event log
ctx.log("validator: found 2 errors");
for entry in ctx.logs() {
    println!("{entry}");
}
ctx.clear_logs();

// Reset everything
ctx.clear();

Ctx persists across multiple runner.run() calls, so the log and store accumulate across runs.

Ctx includes a built-in LLM client that supports Ollama, OpenAI-compatible APIs (OpenRouter, etc.), and the Anthropic API.

let response = ctx.llm()
    .system("You are a helpful assistant.")
    .user("Summarize this text: ...")
    .send()?;

Set via environment variables:

Ollama (default, no API key needed):

export AGENT_LINE_MODEL=llama3.1:8b

OpenRouter:

export AGENT_LINE_PROVIDER=openai
export AGENT_LINE_LLM_URL=https://openrouter.ai/api
export AGENT_LINE_MODEL=amazon/nova-lite-v1
export AGENT_LINE_API_KEY=sk-or-...

Anthropic:

export AGENT_LINE_PROVIDER=anthropic
export AGENT_LINE_LLM_URL=https://api.anthropic.com
export AGENT_LINE_MODEL=claude-sonnet-4-20250514
export AGENT_LINE_API_KEY=sk-ant-...

Agents return an Outcome to control what happens next:

Standalone utility functions for common agent tasks. Import with use agent_line::tools;.

CmdOutput has success: bool, stdout: String, and stderr: String.

StepError has four variants designed around what the caller can do about them:

From impls exist for ureq::Error (maps to Transient) and std::io::Error (maps to Other), so you can use ? in tool calls.

let mut runner = Runner::new(wf)
    .with_max_steps(10_000)   // default, prevents infinite loops
    .with_max_retries(3);     // default, per-agent consecutive retry limit

Runner supports closure-based hooks for observability. Closures are FnMut, so you can use stateful callbacks (counters, accumulators, etc.).

let mut runner = Runner::new(wf)
    .on_step(|e| {
        println!(
            "[step {}] {} -> {:?} ({:.3}s)",
            e.step_number, e.agent, e.outcome, e.duration.as_secs_f64()
        );
    })
    .on_error(|e| {
        eprintln!("[error] {} at step {}: {}", e.agent, e.step_number, e.error);
    });

Or use the built-in tracing shorthand, which prints step transitions and errors to stderr:

let mut runner = Runner::new(wf).with_tracing();

Output looks like:

[step 1] fetch_weather -> Continue (0.001s)
[step 2] fetch_calendar -> Continue (0.000s)
[step 3] fetch_email -> Continue (0.000s)
[step 4] summarize -> Done (2.340s)

StepEvent is passed to on_step after each successful agent step:

ErrorEvent is passed to on_error when an agent errors or a limit is exceeded:

• Rename find_files to glob or add proper glob pattern support

• ureq - Sync HTTP client
• serde + serde_json - JSON serialization