Swink Agent

A pure-Rust library for building LLM-powered agentic loops. Provider-agnostic core with pluggable streaming, concurrent tool execution, and lifecycle events.

Workspace

Key Ideas

• StreamFn is the only provider boundary — implement it to add a new LLM backend.
• AgentTool trait + JSON Schema validation for tool definitions.
• Tools execute concurrently within a turn; steering callbacks can interrupt mid-batch.
• Errors stay in the message log — the loop keeps running. Typed AgentError variants for callers.
• Events are push-only (AgentEvent stream). No inward mutation through events.
• No unsafe code. No global mutable state.

Quick Reference

cargo run -p swink-agent-tui     # launch the TUI (remote/Ollama defaults)
cargo run -p swink-agent-tui --features local  # include bundled local-LLM support
cargo test --workspace             # run all tests

Example: Build a Custom Agent

Wire up an LLM provider, register tools, and launch the interactive TUI — all in one file:

use swink_agent::{AgentOptions, BashTool, ModelConnections, ReadFileTool, WriteFileTool};
use swink_agent_adapters::build_remote_connection_for_model;
use swink_agent_local_llm::default_local_connection;
use swink_agent_tui::{TuiConfig, launch, restore_terminal, setup_terminal};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

    let connections = ModelConnections::new(
        build_remote_connection_for_model("claude-sonnet-4-6")?,
        vec![
            build_remote_connection_for_model("gpt-4.1")?,
            default_local_connection()?,
        ],
    );
    let tools = vec![
        BashTool::new().into_tool(),
        ReadFileTool::new().into_tool(),
        WriteFileTool::new().into_tool(),
    ];

    let options =
        AgentOptions::from_connections("You are a helpful assistant.", connections)
            .with_tools(tools);

    let mut terminal = setup_terminal()?;
    let result = launch(TuiConfig::default(), &mut terminal, options).await;

    restore_terminal()?;
    result
}

More Examples

Runnable examples are in SuperSwinkAI/Swink-Agent-Examples:

See docs/getting_started.md for setup and configuration. See docs/architecture/HLD.md for system design. See docs/planning/PRD.md for product requirements.