agent-line

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.

Quick Start

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
}

Workflows

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.

Context (Ctx)

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.

LLM Integration

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()?;

Configuration

Set via environment variables:

Provider examples

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-...

Outcomes

Agents return an Outcome to control what happens next:

Tools

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

File operations

Command execution

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

HTTP

Parsing

Error Handling

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.

Runner Configuration

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

Hooks

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)

Hook event types

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:

Examples

TODO

• Rename find_files to glob or add proper glob pattern support

Dependencies

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