PolarisPolaris

Composable building blocks for powerful agent harnesses

A robust, performant open source toolkit for building agent harnesses, written in Rust

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.
Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Why build your own agent harness?

Generic agents are useful until you need one that reflects your product, your workflow, your data, or your risk boundaries. The harness is where those decisions live: how the agent reasons, what it can access, when it asks for help, and how it keeps going over longer work.

If those choices are hidden inside a fixed runtime, you inherit its defaults. If they are part of your harness, you can shape them around the experience you actually want to deliver.

Polaris gives you composable building blocks so you can design those behaviors directly, rather than treating them as hidden framework defaults.

Turn agent behavior into product design.

These are the parts of the harness that usually decide whether an agent feels useful, trustworthy, and production-ready, and where teams start building real product differentiation.

Shape how your agent reasons

When reasoning is explicit, you can improve how an agent plans, retries, branches, and finishes work instead of hoping a fixed loop behaves the right way.

  • Tune how the agent works for your product or workflow, rather than adapting your product to the framework.
  • Inspect and refine decision paths when an agent behaves poorly or gets stuck.
  • Build agents that can handle multi-step work without turning the runtime into a black box.
let mut graph = Graph::new();// Start by preparing the turn state and prompt context.graph.add_system(init);graph.add_loop::<ReactState, _, _>("react", |s| s.is_complete, |g| {    // Ask the model what to do next.    g.add_system(act);    g.add_conditional_branch::<LlmResponse, _, _, _>(        "tool-or-final",        |response| !response.tool_calls().is_empty(),        |tool_branch| {            tool_branch.add_system(execute_tools);            tool_branch.add_system(record_tool_results);        },        |done_branch| {            // Exit the loop once the agent is ready to answer.            done_branch.add_system(finalize);        },    );});

Build long running agents with memory

Polaris makes it easier to build agents that can pick up where they left off, recover from failure, and stay useful across longer tasks or sessions.

  • Give users continuity instead of resetting the agent every time something changes.
  • Recover from interruptions without rebuilding the whole workflow from scratch.
  • Move from a demo chat loop to a real long-running agent product.
let mut server = Server::new();server    .add_plugins(PersistencePlugin)    .add_plugins(SessionsPlugin::new(Arc::new(FileStore::new("data"))));let sessions = server.api::<SessionsAPI>().unwrap();// Register the harness once, then create resumable sessions around it.sessions.register_agent(ReActAgent)?;let session = sessions.create_session("react-agent").await?;// Checkpoints give you a clean recovery point.sessions.checkpoint(session.id(), "before-tool-loop").await?;let turn = sessions.run_turn(session.id(), "Refactor the worker pool").await?;if turn.failed() {    // Roll back the session instead of rebuilding the whole run.    sessions.rollback(session.id(), "before-tool-loop").await?;}

Keep context under control

Good agents depend on the right information being available at the right time. Polaris helps you decide what the agent sees, what it updates, what it carries forward, and how that context strategy should evolve as the product changes.

  • Prevent hidden framework state from silently shaping agent behavior.
  • Swap context strategies as requirements change, from simple windows to more structured approaches.
  • Make it easier to reason about memory, history, and local state as the harness grows.
  • Give teams clearer control over reliability, cost, and context quality.
#[system]async fn act(    context: Res<ContextManager>,    strategy: Res<Arc<dyn ContextStrategy>>,    llm: Res<AgentLlm>,    tool_registry: Res<ToolRegistry>,) -> Result<LlmResponse, SystemError> {    // Build the prompt with whichever context policy this harness uses.    let messages = strategy.prepare(&context);    llm.builder().with_registry(&tool_registry).messages(messages).reason().await}#[system]fn remember_tool_result(    tool_output: Out<ToolExecutionResult>,    mut context: ResMut<ContextManager>,    trace: Res<RequestTrace>,) {    // Feed the tool result back into the next reasoning step.    context.messages.push(tool_output.as_tool_message());    // Store extra local state without hiding it inside the framework.    context.set_local("last_trace_id", trace.id().to_string());}// Swap strategies without rewriting the rest of the harness.server.insert_resource(Arc::new(SlidingWindow::last_n(24)) as Arc<dyn ContextStrategy>);// orserver.insert_resource(Arc::new(SummarizingContext::new(compactor_model)) as Arc<dyn ContextStrategy>);

Add tool use without giving away the keys

Polaris helps you turn tool use into a product surface you can trust, with permission boundaries, confirmations, and runtime controls around risky actions.

  • Build coding agents and internal operators that can take action safely.
  • Decide which commands, files, and actions are allowed in each environment.
  • Mix low-risk tools, confirmed tools, and sandboxed shell access in the same harness.
  • Add approval steps where trust matters instead of leaving everything up to the model.
// Register the shared tool lifecycle once for the harness.server.add_plugins(ToolsPlugin);// Add safe filesystem tools scoped to the repo or working directory.server.add_plugins(    FileToolsPlugin::new(        FileToolsConfig::new(&working_dir)            .with_read(true)            .with_write(true),    ),);// Add shell access with explicit command and directory boundaries.server.add_plugins(    ShellPlugin::new(        ShellConfig::new()            .with_allowed_commands(vec![                "cargo *".into(),                "git diff *".into(),                "git status".into(),            ])            .with_allowed_dirs(vec![working_dir.to_string_lossy().into_owned()])            .with_permission(ToolPermission::Confirm),    ),);

Use tracing to see what your agent is actually doing

When agents misbehave, observability stops being a nice-to-have. Polaris makes it easier to instrument the harness itself, attach graph-level hooks, and export traces to OpenTelemetry from the start.

  • Understand where failures come from instead of guessing from final outputs.
  • Track execution across graph steps, model calls, and tool runs as one system.
  • Attach graph hooks where you need extra visibility without tangling observability into business logic.
  • Export OpenTelemetry spans so local debugging and production monitoring use the same trace surface.
// Start with structured traces for graph execution and tool activity.let tracing_plugin = TracingPlugin::default()    .with_fmt(FmtConfig::default().env_filter("polaris=debug,warn"))    .with_content(false);server.add_plugins(tracing_plugin);// Attach graph hooks when you want visibility around specific steps.graph.add_hook(GraphHook::on_node_start(|node, trace| {    trace.record("graph.node.start", node.name());}));graph.add_hook(GraphHook::on_node_end(|node, trace| {    trace.record("graph.node.end", node.name());}));// Export the same traces to any OpenTelemetry-compatible backend.if let Some(endpoint) = &otel_endpoint {    server.add_plugins(OpenTelemetryPlugin::new(endpoint));}

Keep humans in the loop with user handoff where it matters

The best agents do not need to be fully autonomous. Polaris makes it easier to pause, ask for input, request approval, or hand work back to a user cleanly.

  • Design agents that collaborate with users
  • Add checkpoints and human approval for sensitive actions.
  • Use the same handoff patterns across CLI, app, and service environments.
#[system]async fn execute_tools(    decision: Out<LlmResponse>,    user_io: Res<UserIO>,    tool_registry: Res<ToolRegistry>,) -> Result<(), SystemError> {    for tool_call in decision.tool_calls() {        if tool_registry.permission(&tool_call.function.name) == Some(ToolPermission::Confirm) {            let response = user_io.confirm("Run this tool?").await?;            if !response.confirmed {                continue;            }        }    }    Ok(())}

Start shaping your own harness with Polaris