swiftide

The core primitives provide the shared interaction model. Around them, use pipelines for data flows, agents for tool loops, and tasks for graphs of typed hand-offs.

Quick Start

Swiftide keeps default dependencies light. Start with the agent harness and add the integrations your application needs.

cargo add swiftide --features swiftide-agents,openai
cargo add anyhow
cargo add tokio --features macros,rt-multi-thread

HTTPS works out of the box: Swiftide's HTTP clients use rustls with a built-in crypto provider. If your application installs its own process-wide rustls CryptoProvider before creating clients, Swiftide uses that one instead. Redis over rediss:// needs a process-wide provider; if none is installed when it connects, Swiftide installs aws-lc-rs.

If using OpenAI, set the API key expected by the OpenAI-compatible integration:

export OPENAI_API_KEY=...

To use another OpenAI-compatible endpoint, such as a gateway, vLLM or LiteLLM, set its URL and key on the builder:

let openai = OpenAI::builder()
    .api_base("http://127.0.0.1:8080/v1")
    .api_key("...")
    .default_prompt_model("my-model")
    .build()?;

Agent Harness

Use the agent harness to call a model, run tools, and control when an agent stops. Add tools as Rust functions or Tool implementations, and use hooks to run logic during the agent lifecycle.

AgentContext manages conversation history and gives tools access to a ToolExecutor. Use the local executor or run commands in an isolated environment with the Docker executor.

use anyhow::Result;
use swiftide::{
    agents,
    chat_completion::{ToolOutput, errors::ToolError},
    traits::AgentContext,
};

#[swiftide::tool(
    description = "Looks up a Swiftide concept",
    param(name = "concept", description = "Concept to explain")
)]
async fn explain_concept(
    _context: &dyn AgentContext,
    concept: &str,
) -> Result<ToolOutput, ToolError> {
    let explanation = match concept {
        "tasks" => "Tasks compose typed nodes into explicit workflows.",
        "agents" => "Agents run LLM completions, tools, hooks, and stop conditions.",
        "pipelines" => "Pipelines stream data through indexing and retrieval steps.",
        _ => "Swiftide composes agents, task graphs, tools, and RAG pipelines.",
    };

    Ok(explanation.into())
}

#[tokio::main]
async fn main() -> Result<()> {
    let openai = swiftide::integrations::openai::OpenAI::builder()
        .default_prompt_model("gpt-4o-mini")
        .build()?;

    agents::Agent::builder()
        .llm(&openai)
        .tools([explain_concept()])
        .on_new_message(|_, message| {
            println!("{message}");
            Box::pin(async { Ok(()) })
        })
        .limit(8)
        .build()?
        .query("Explain Swiftide tasks and agents in one paragraph.")
        .await?;

    Ok(())
}

The agent calls the model, exposes explain_concept as a tool, prints new messages, and stops within the configured turn limit. By default all agents have a tool to stop the loop. This can be customized.

Agent capabilities include:

• function tools through #[swiftide::tool], derived tools, or manual Tool implementations
• lifecycle hooks before and after completions, tools, messages, streaming chunks, start, and stop
• local or custom ToolExecutor implementations for command/file access
• human-in-the-loop approval via ApprovalRequired and feedback-aware contexts
• structured stop and failure payloads with custom JSON schemas
• MCP toolboxes that load tools at runtime
• streaming responses and reasoning-item handling for providers that support them

Start with examples/hello_agents.rs, then look at the human approval, MCP, streaming, resume, and structured-output examples.

Agent Tools and Hooks

Use swiftide-agents-contrib to add file tools, plans, context hooks, and lazy executors to your agents. Choose the features you need and register the components on your agent.

cargo add swiftide --features agents-contrib-file-tools,agents-contrib-planning

Import components from swiftide::agents_contrib, for example swiftide::agents_contrib::tools::ReadFile registers read_file; add .with_line_numbers() for read_file_with_line_numbers. Both accept file_name, optional one-based offset, and optional limit. Reads default to 2,000 lines, truncate long lines at 2,000 characters, and refuse windows above the 100,000-character budget. Partial pages explain how to continue. Contrib features are off by default. See the crate guide for examples, defaults, and the features to use when depending on the contrib crate directly.

Typed Task Graphs

Tasks are Swiftide's orchestration layer. A task is a typed graph of TaskNode steps. Each node has an input type, output type, and error type; transitions decide where the output goes next.

Tasks are strongly typed at build time. It allows you to compose agents, other swiftide components, and functions to create complex automations.

From examples/tasks.rs.

use swiftide::{
    prompt::Prompt,
    tasks::{Task, TaskRunOutcome, Transition},
    traits::SimplePrompt,
};
use std::sync::Arc;

let prompt_model: Arc<dyn SimplePrompt> = Arc::new(openai.clone());
let briefing_agent = BriefingAgent::new(agent);
let mut task: Task<Prompt, String> = Task::new();

let brief = task.register_node(prompt_model.clone());
let decide = task.register_node(briefing_agent);
let render = task.register_node(prompt_model);

task.starts_with(brief);
task.register_transition(brief, move |short_brief| {
    decide.transitions_with(short_brief)
})?;
task.register_transition(decide, move |decision: BriefingDecision| {
    Transition::next(
        &render,
        Prompt::from("Write a hand-off note for {{audience}}: {{summary}}")
            .with_context_value("audience", decision.audience)
            .with_context_value("summary", decision.summary),
    )
})?;
task.register_transition(render, task.transitions_to_finish())?;

match task.run(Prompt::from("Summarize the rollout plan")).await? {
    TaskRunOutcome::Completed(note) => println!("{note}"),
    TaskRunOutcome::Paused => println!("Task paused"),
}

Task capabilities include:

• closure nodes for small glue steps and TaskNode implementations for domain logic
• typed NodeId handles, transitions, and join payloads
• static fan-out with explicit joins
• sequential or parallel branch execution
• pause, resume, and reset support
• adapters for prompt-like Swiftide primitives, chat completions, and tool executors
• TaskAgent for the simple case where an agent should run as a task node

See examples/tasks.rs for a prompt plus custom agent workflow, and examples/tasks_fanout.rs for fan-out and join.

RAG Pipelines

Swiftide includes first-class indexing and querying pipelines for retrieval-augmented generation. Pipelines are streaming and composable: load data, transform it, embed it, cache it, store it, then retrieve and answer with a typed query flow.

use swiftide::{
    indexing::{self, loaders::FileLoader, transformers::{ChunkCode, Embed, MetadataQACode}},
    integrations::qdrant::Qdrant,
};

async fn index(openai: swiftide::integrations::openai::OpenAI) -> anyhow::Result<()> {
    let qdrant = Qdrant::builder()
        .collection_name("swiftide-code")
        .vector_size(1536)
        .batch_size(50)
        .build()?;

    indexing::Pipeline::from_loader(FileLoader::new(".").with_extensions(&["rs"]))
        .with_default_llm_client(openai.clone())
        .then_chunk(ChunkCode::try_for_language_and_chunk_size("rust", 10..2048)?)
        .then(MetadataQACode::default())
        .then_in_batch(Embed::new(openai))
        .then_store_with(qdrant)
        .run()
        .await?;

    Ok(())
}

Indexing supports loaders, caches, chunkers, transformers, batch transformers, embedders, and storage backends. Query pipelines support query transformation, retrieval, response transformation, answer generation, hybrid search, reranking patterns, and evaluation.

Integrations

Swiftide integrations are feature-gated so application builds stay intentional.

Examples

The examples has a variety of examples.

• Agents: hello_agents.rs, streaming_agents.rs, agents_with_human_in_the_loop.rs, agents_mcp_tools.rs
• Structured outputs and control tools: stop_with_args_custom_schema.rs, agent_can_fail_custom_schema.rs
• Tasks: tasks.rs, tasks_fanout.rs
• RAG and retrieval: index_codebase.rs, query_pipeline.rs, hybrid_search.rs
• Provider and observability examples: responses_api.rs, responses_api_reasoning.rs, aws_bedrock_agent.rs, langfuse.rs

More background is available on the Bosun blog, including posts about tasks, streaming agents, human-in-the-loop flows, and Rust performance for AI tools.

Project Status

Swiftide is pre-1.0. APIs can change while the agent harness and task graph APIs settle around production use. The current API docs and examples are the most reliable source of exact signatures.

Swiftide is part of the bosun.ai project.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, open an issue for design discussion, file a bug report, or propose a feature. Join the Discord for a faster feedback loop.

Before opening a pull request:

1. Run the focused checks for the crates you changed.
2. Run cargo +nightly fmt --all -- --check.
3. Run cargo clippy --workspace --all-targets --all-features -- -D warnings when touching shared behavior.
4. Add or update examples, tests, or rustdoc when behavior changes.

AI-generated code is welcome and should be reviewed like any other code. Keep abstractions small, keep domain logic separate from plumbing, and pay attention to allocations in indexing, querying, and task execution paths.

AI agents can refer to AGENTS.md for workspace layout, commands, and expectations.

Core Team Members

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)