Struct Runner 

pub struct Runner<S: Clone + 'static> { /* private fields */ }

Executes a Workflow step by step, handling retries, waits, and routing.

Implementations

impl<S: Clone + 'static> Runner<S>

pub fn new(wf: Workflow<S>) -> Self

Create a runner for the given workflow with default limits (max_steps: 10,000, max_retries: 3).

Examples found in repository

examples/workflow.rs (line 42)

fn main() {
    let mut ctx = Ctx::new();
    let wf = Workflow::builder("demo")
        .register(AddOne)
        .register(StopAtThree)
        .start_at("add_one")
        .then("stop")
        .build()
        .unwrap();

    let final_state = Runner::new(wf).run(State { n: 0 }, &mut ctx).unwrap();
    println!("final n={}", final_state.n);
}

examples/assistant.rs (line 131)

fn main() {
    let mut ctx = Ctx::new();

    let wf = Workflow::builder("daily-briefing")
        .register(FetchWeather)
        .register(FetchCalendar)
        .register(FetchEmail)
        .register(Summarize)
        .start_at("fetch_weather")
        .then("fetch_calendar")
        .then("fetch_email")
        .then("summarize")
        .build()
        .unwrap();

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

    let mut iteration = 0;
    loop {
        iteration += 1;
        println!("=== Briefing #{iteration} ===\n");

        match runner.run(BriefingState::new(), &mut ctx) {
            Ok(state) => {
                println!("{}\n", state.summary);
            }
            Err(e) => {
                eprintln!("Briefing failed: {e}\n");
            }
        }

        ctx.clear_logs();

        println!("(sleeping 30s before next briefing...)\n");
        thread::sleep(Duration::from_secs(30));
    }
}

examples/edit_loop.rs (lines 93-102)

fn main() {
    let mut ctx = Ctx::new();

    let mut runner = Runner::new(
        Workflow::builder("edit-loop")
            .register(Writer)
            .register(Validator)
            .register(Fixer { retried: false })
            .start_at("writer")
            .then("validator")
            .build()
            .unwrap(),
    );

    let mut revision = 0;
    for round in 1..=3 {
        println!("=== Round {round} ===");

        let doc = Doc {
            text: String::new(),
            revision,
        };

        match runner.run(doc, &mut ctx) {
            Ok(doc) => {
                println!("  Final text: {:?}", doc.text);
                println!("  Revisions:  {}", doc.revision);
                revision = doc.revision;
            }
            Err(e) => println!("  Error: {e}"),
        }

        println!("  Log:");
        for entry in ctx.logs() {
            println!("    {entry}");
        }
        ctx.clear_logs();
        println!();
    }
}

examples/coder.rs (line 181)

fn main() {
    let tmp = std::env::temp_dir().join("agent-line-coder");
    scaffold_project(&tmp);

    let lib_path = tmp.join("src/lib.rs").display().to_string();
    let manifest = tmp.join("Cargo.toml").display().to_string();

    let mut ctx = Ctx::new();
    ctx.set("manifest_path", &manifest);

    let wf = Workflow::builder("coding-agent")
        .register(Planner)
        .register(Coder)
        .register(Tester)
        .start_at("planner")
        .then("coder")
        .then("tester")
        .build()
        .unwrap();

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

    let result = runner.run(
        Task {
            description: "Add a function called `reverse_string` that reverses a string \
                          and add unit tests"
                .into(),
            file_path: lib_path,
            code: String::new(),
            test_output: String::new(),
            attempts: 0,
            max_attempts: 3,
        },
        &mut ctx,
    );

    println!("=== Result ===");
    match result {
        Ok(task) => {
            println!("  Success after {} fix attempts", task.attempts);
            println!("  Final code:\n{}", task.code);
        }
        Err(e) => println!("  Failed: {e}"),
    }

    println!("\n=== Log ===");
    for entry in ctx.logs() {
        println!("  {entry}");
    }
}

examples/newsletter.rs (line 169)

fn main() {
    let mut ctx = Ctx::new();

    // could populate ctx.store with some writing rules or could read in a markdown skill and pass
    // that into the agent.
    // Phase 1: find topics
    let topic_wf = Workflow::builder("find-topics")
        .register(TopicSearcher)
        .register(TopicPicker)
        .start_at("topic_searcher")
        .then("topic_picker")
        .build()
        .unwrap();

    let mut topic_runner = Runner::new(topic_wf);
    let topics = topic_runner
        .run(
            TopicState {
                query: "bluecollar engineering newsletter".into(),
                topics: vec![],
                selected: vec![],
            },
            &mut ctx,
        )
        .unwrap();

    println!("=== Topics ===");
    for entry in ctx.logs() {
        println!("  {entry}");
    }
    ctx.clear_logs();
    println!();

    // Phase 2: write one article per topic
    let article_wf = Workflow::builder("write-article")
        .register(ArticleWriter)
        .register(ArticleValidator)
        .register(ArticleFixer)
        .start_at("article_writer")
        .then("article_validator")
        .build()
        .unwrap();

    let mut article_runner = Runner::new(article_wf);
    let mut finished_articles: Vec<String> = Vec::new();

    for (i, topic) in topics.selected.iter().enumerate() {
        println!("=== Article {} ===", i + 1);

        let result = article_runner
            .run(
                ArticleState {
                    topic: topic.clone(),
                    draft: String::new(),
                    revision: 0,
                },
                &mut ctx,
            )
            .unwrap();

        finished_articles.push(result.draft.clone());
        println!("  Revisions: {}", result.revision);

        for entry in ctx.logs() {
            println!("  {entry}");
        }
        ctx.clear_logs();
        println!();
    }

    // Phase 3: "store" the articles
    println!("=== Stored ===");
    for (i, article) in finished_articles.iter().enumerate() {
        let preview: String = article.chars().take(60).collect();
        println!("  article_{}.md: {preview}...", i + 1);
    }
}

examples/parallel.rs (line 237)

fn main() {
    let topics = vec![
        "Rust in embedded systems".to_string(),
        "Why plumbers love side projects".to_string(),
        "Electricians using Raspberry Pi on the job".to_string(),
    ];

    // Shared guidelines for all writers -- the author's voice and style rules
    let guidelines = "\
        Write in first person. \
        Do not use emdashes. \
        Add a touch of humor. \
        Keep it under 300 words."
        .to_string();

    println!("=== Fan-out: {} threads ===\n", topics.len());

    // Fan-out: spawn one thread per topic
    let handles: Vec<_> = topics
        .into_iter()
        .enumerate()
        .map(|(i, topic)| {
            let guidelines = guidelines.clone();

            thread::spawn(move || {
                // Each thread gets its own Ctx and Runner -- no shared mutable state
                let mut ctx = Ctx::new();

                let wf = Workflow::builder("write-article")
                    .register(Researcher)
                    .register(Writer)
                    .register(Editor)
                    .start_at("researcher")
                    .then("writer")
                    .then("editor")
                    .build()
                    .unwrap();

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

                let result = runner.run(ArticleState::new(topic.clone(), guidelines), &mut ctx);

                // Print the log from this thread's pipeline
                for entry in ctx.logs() {
                    println!("  [thread {}] {}", i, entry);
                }

                result
            })
        })
        .collect();

    // Fan-in: join all threads, collect results
    let mut finished = Vec::new();
    for handle in handles {
        match handle.join().unwrap() {
            Ok(state) => finished.push(state),
            Err(e) => eprintln!("thread failed: {e}"),
        }
    }

    // Show results
    println!("\n=== Fan-in: {} articles ===\n", finished.len());
    for (i, article) in finished.iter().enumerate() {
        let preview: String = article.draft.chars().take(72).collect();
        println!(
            "  {}. {} (rev {})\n     {preview}...\n",
            i + 1,
            article.topic,
            article.revision
        );
    }
}

pub fn with_max_steps(self, max_steps: usize) -> Self

Prevent accidental infinite loops.

pub fn with_max_retries(self, max_retries: usize) -> Self

Set the maximum consecutive retries per agent before failing.

Examples found in repository

examples/parallel.rs (line 237)

fn main() {
    let topics = vec![
        "Rust in embedded systems".to_string(),
        "Why plumbers love side projects".to_string(),
        "Electricians using Raspberry Pi on the job".to_string(),
    ];

    // Shared guidelines for all writers -- the author's voice and style rules
    let guidelines = "\
        Write in first person. \
        Do not use emdashes. \
        Add a touch of humor. \
        Keep it under 300 words."
        .to_string();

    println!("=== Fan-out: {} threads ===\n", topics.len());

    // Fan-out: spawn one thread per topic
    let handles: Vec<_> = topics
        .into_iter()
        .enumerate()
        .map(|(i, topic)| {
            let guidelines = guidelines.clone();

            thread::spawn(move || {
                // Each thread gets its own Ctx and Runner -- no shared mutable state
                let mut ctx = Ctx::new();

                let wf = Workflow::builder("write-article")
                    .register(Researcher)
                    .register(Writer)
                    .register(Editor)
                    .start_at("researcher")
                    .then("writer")
                    .then("editor")
                    .build()
                    .unwrap();

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

                let result = runner.run(ArticleState::new(topic.clone(), guidelines), &mut ctx);

                // Print the log from this thread's pipeline
                for entry in ctx.logs() {
                    println!("  [thread {}] {}", i, entry);
                }

                result
            })
        })
        .collect();

    // Fan-in: join all threads, collect results
    let mut finished = Vec::new();
    for handle in handles {
        match handle.join().unwrap() {
            Ok(state) => finished.push(state),
            Err(e) => eprintln!("thread failed: {e}"),
        }
    }

    // Show results
    println!("\n=== Fan-in: {} articles ===\n", finished.len());
    for (i, article) in finished.iter().enumerate() {
        let preview: String = article.draft.chars().take(72).collect();
        println!(
            "  {}. {} (rev {})\n     {preview}...\n",
            i + 1,
            article.topic,
            article.revision
        );
    }
}

pub fn on_step(self, cb: impl FnMut(&StepEvent<'_>) + 'static) -> Self

Register a callback that fires after each successful agent step.

pub fn on_error(self, cb: impl FnMut(&ErrorEvent<'_>) + 'static) -> Self

Register a callback that fires when an agent errors or a limit is exceeded.

pub fn with_tracing(self) -> Self

Set both hooks to print step transitions and errors to stderr.

Examples found in repository

examples/assistant.rs (line 131)

fn main() {
    let mut ctx = Ctx::new();

    let wf = Workflow::builder("daily-briefing")
        .register(FetchWeather)
        .register(FetchCalendar)
        .register(FetchEmail)
        .register(Summarize)
        .start_at("fetch_weather")
        .then("fetch_calendar")
        .then("fetch_email")
        .then("summarize")
        .build()
        .unwrap();

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

    let mut iteration = 0;
    loop {
        iteration += 1;
        println!("=== Briefing #{iteration} ===\n");

        match runner.run(BriefingState::new(), &mut ctx) {
            Ok(state) => {
                println!("{}\n", state.summary);
            }
            Err(e) => {
                eprintln!("Briefing failed: {e}\n");
            }
        }

        ctx.clear_logs();

        println!("(sleeping 30s before next briefing...)\n");
        thread::sleep(Duration::from_secs(30));
    }
}

pub fn run(&mut self, state: S, ctx: &mut Ctx) -> Result<S, StepError>

Run the workflow to completion, returning the final state or an error. Can be called multiple times on the same runner.

Examples found in repository

examples/workflow.rs (line 42)

fn main() {
    let mut ctx = Ctx::new();
    let wf = Workflow::builder("demo")
        .register(AddOne)
        .register(StopAtThree)
        .start_at("add_one")
        .then("stop")
        .build()
        .unwrap();

    let final_state = Runner::new(wf).run(State { n: 0 }, &mut ctx).unwrap();
    println!("final n={}", final_state.n);
}

examples/assistant.rs (line 138)

fn main() {
    let mut ctx = Ctx::new();

    let wf = Workflow::builder("daily-briefing")
        .register(FetchWeather)
        .register(FetchCalendar)
        .register(FetchEmail)
        .register(Summarize)
        .start_at("fetch_weather")
        .then("fetch_calendar")
        .then("fetch_email")
        .then("summarize")
        .build()
        .unwrap();

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

    let mut iteration = 0;
    loop {
        iteration += 1;
        println!("=== Briefing #{iteration} ===\n");

        match runner.run(BriefingState::new(), &mut ctx) {
            Ok(state) => {
                println!("{}\n", state.summary);
            }
            Err(e) => {
                eprintln!("Briefing failed: {e}\n");
            }
        }

        ctx.clear_logs();

        println!("(sleeping 30s before next briefing...)\n");
        thread::sleep(Duration::from_secs(30));
    }
}

examples/edit_loop.rs (line 113)

fn main() {
    let mut ctx = Ctx::new();

    let mut runner = Runner::new(
        Workflow::builder("edit-loop")
            .register(Writer)
            .register(Validator)
            .register(Fixer { retried: false })
            .start_at("writer")
            .then("validator")
            .build()
            .unwrap(),
    );

    let mut revision = 0;
    for round in 1..=3 {
        println!("=== Round {round} ===");

        let doc = Doc {
            text: String::new(),
            revision,
        };

        match runner.run(doc, &mut ctx) {
            Ok(doc) => {
                println!("  Final text: {:?}", doc.text);
                println!("  Revisions:  {}", doc.revision);
                revision = doc.revision;
            }
            Err(e) => println!("  Error: {e}"),
        }

        println!("  Log:");
        for entry in ctx.logs() {
            println!("    {entry}");
        }
        ctx.clear_logs();
        println!();
    }
}

examples/coder.rs (lines 183-195)

fn main() {
    let tmp = std::env::temp_dir().join("agent-line-coder");
    scaffold_project(&tmp);

    let lib_path = tmp.join("src/lib.rs").display().to_string();
    let manifest = tmp.join("Cargo.toml").display().to_string();

    let mut ctx = Ctx::new();
    ctx.set("manifest_path", &manifest);

    let wf = Workflow::builder("coding-agent")
        .register(Planner)
        .register(Coder)
        .register(Tester)
        .start_at("planner")
        .then("coder")
        .then("tester")
        .build()
        .unwrap();

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

    let result = runner.run(
        Task {
            description: "Add a function called `reverse_string` that reverses a string \
                          and add unit tests"
                .into(),
            file_path: lib_path,
            code: String::new(),
            test_output: String::new(),
            attempts: 0,
            max_attempts: 3,
        },
        &mut ctx,
    );

    println!("=== Result ===");
    match result {
        Ok(task) => {
            println!("  Success after {} fix attempts", task.attempts);
            println!("  Final code:\n{}", task.code);
        }
        Err(e) => println!("  Failed: {e}"),
    }

    println!("\n=== Log ===");
    for entry in ctx.logs() {
        println!("  {entry}");
    }
}

examples/newsletter.rs (lines 171-178)

fn main() {
    let mut ctx = Ctx::new();

    // could populate ctx.store with some writing rules or could read in a markdown skill and pass
    // that into the agent.
    // Phase 1: find topics
    let topic_wf = Workflow::builder("find-topics")
        .register(TopicSearcher)
        .register(TopicPicker)
        .start_at("topic_searcher")
        .then("topic_picker")
        .build()
        .unwrap();

    let mut topic_runner = Runner::new(topic_wf);
    let topics = topic_runner
        .run(
            TopicState {
                query: "bluecollar engineering newsletter".into(),
                topics: vec![],
                selected: vec![],
            },
            &mut ctx,
        )
        .unwrap();

    println!("=== Topics ===");
    for entry in ctx.logs() {
        println!("  {entry}");
    }
    ctx.clear_logs();
    println!();

    // Phase 2: write one article per topic
    let article_wf = Workflow::builder("write-article")
        .register(ArticleWriter)
        .register(ArticleValidator)
        .register(ArticleFixer)
        .start_at("article_writer")
        .then("article_validator")
        .build()
        .unwrap();

    let mut article_runner = Runner::new(article_wf);
    let mut finished_articles: Vec<String> = Vec::new();

    for (i, topic) in topics.selected.iter().enumerate() {
        println!("=== Article {} ===", i + 1);

        let result = article_runner
            .run(
                ArticleState {
                    topic: topic.clone(),
                    draft: String::new(),
                    revision: 0,
                },
                &mut ctx,
            )
            .unwrap();

        finished_articles.push(result.draft.clone());
        println!("  Revisions: {}", result.revision);

        for entry in ctx.logs() {
            println!("  {entry}");
        }
        ctx.clear_logs();
        println!();
    }

    // Phase 3: "store" the articles
    println!("=== Stored ===");
    for (i, article) in finished_articles.iter().enumerate() {
        let preview: String = article.chars().take(60).collect();
        println!("  article_{}.md: {preview}...", i + 1);
    }
}

examples/parallel.rs (line 239)

fn main() {
    let topics = vec![
        "Rust in embedded systems".to_string(),
        "Why plumbers love side projects".to_string(),
        "Electricians using Raspberry Pi on the job".to_string(),
    ];

    // Shared guidelines for all writers -- the author's voice and style rules
    let guidelines = "\
        Write in first person. \
        Do not use emdashes. \
        Add a touch of humor. \
        Keep it under 300 words."
        .to_string();

    println!("=== Fan-out: {} threads ===\n", topics.len());

    // Fan-out: spawn one thread per topic
    let handles: Vec<_> = topics
        .into_iter()
        .enumerate()
        .map(|(i, topic)| {
            let guidelines = guidelines.clone();

            thread::spawn(move || {
                // Each thread gets its own Ctx and Runner -- no shared mutable state
                let mut ctx = Ctx::new();

                let wf = Workflow::builder("write-article")
                    .register(Researcher)
                    .register(Writer)
                    .register(Editor)
                    .start_at("researcher")
                    .then("writer")
                    .then("editor")
                    .build()
                    .unwrap();

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

                let result = runner.run(ArticleState::new(topic.clone(), guidelines), &mut ctx);

                // Print the log from this thread's pipeline
                for entry in ctx.logs() {
                    println!("  [thread {}] {}", i, entry);
                }

                result
            })
        })
        .collect();

    // Fan-in: join all threads, collect results
    let mut finished = Vec::new();
    for handle in handles {
        match handle.join().unwrap() {
            Ok(state) => finished.push(state),
            Err(e) => eprintln!("thread failed: {e}"),
        }
    }

    // Show results
    println!("\n=== Fan-in: {} articles ===\n", finished.len());
    for (i, article) in finished.iter().enumerate() {
        let preview: String = article.draft.chars().take(72).collect();
        println!(
            "  {}. {} (rev {})\n     {preview}...\n",
            i + 1,
            article.topic,
            article.revision
        );
    }
}