Distri: A Composable Agent Framework

Distri

Distri is an open-source AI agent framework built in Rust. Define agents in markdown, connect your product functions as tools, and run them from the CLI, as an API server, or embedded in your React UI.

Documentation · Website · Distri Cloud

Why Distri

• Agents as markdown — Define behavior, tools, and model settings in a single .md file with TOML frontmatter
• Built-in tool system — Builtins (search, shell, browser), dynamic HTTP tools, external client-side tools, and MCP support
• Skills — On-demand knowledge documents agents load at runtime via load_skill, with automatic re-injection after context compaction
• Sub-agents — Agents delegate to specialized child agents with isolated context and token budgets
• Remote execution — Run agents in sandboxed containers for untrusted code or resource isolation
• React SDK — Drop-in <Chat /> component with streaming, tool renderers, voice, and developer mode
• A2A compatible — Implements the A2A protocol for agent discovery and invocation
• Self-hosted — Run on your own infrastructure with SQLite. No external dependencies required.

Installation

# Install script (macOS / Linux)
curl -fsSL https://distri.dev/install.sh | sh

# Homebrew
brew tap distrihub/distri && brew install distri

# Verify
distri --version

# darwin-arm64 | darwin-x86_64 | linux-arm64 | linux-x86_64
TARGET=darwin-arm64
curl -L "https://github.com/distrihub/distri/releases/latest/download/distri-${TARGET}.tar.gz" -o distri.tar.gz
sudo tar -xzf distri.tar.gz -C /usr/local/bin distri

Invoke-WebRequest https://github.com/distrihub/distri/releases/latest/download/distri-windows-x86_64.zip -OutFile distri.zip
Expand-Archive distri.zip -DestinationPath $Env:LOCALAPPDATA\distri -Force
$Env:Path += ";$Env:LOCALAPPDATA\distri"

Run

Once installed, start the server and web UI:

distri serve

The first run downloads the matching distri-server binary and UI bundle from github.com/distrihub/distri/releases into ~/.distri/. Opens your browser automatically to http://localhost:7777.

Serve options

Lifecycle commands

Quick Start

Run a built-in agent

distri run search --task "What are the top programming languages in 2026?"

Define your own agent

Create agents/my_agent.md:

---
name = "my_agent"
description = "A helpful assistant with web search"
max_iterations = 15

[tools]
builtin = ["final", "search"]
---

# My Agent

You are a helpful assistant. Use the search tool to find current information.

{{task}}

Run it

# Interactive chat
distri tui my_agent

# Single task
distri run --agent my_agent --task "Find the latest SpaceX launch date"

# Start as API server
distri serve --port 8080

Push to Distri Cloud

distri login
distri agents push agents/my_agent.md

Built-in Agents

Requires BROWSR_BASE_URL and BROWSR_API_KEY for search, browser, and shell tools. Configured automatically on Distri Cloud.

Agent Definition Format

Agents are markdown files with TOML frontmatter:

---
name = "my_agent"
description = "What this agent does"
max_iterations = 25
context_size = 80000
sub_agents = ["search", "code"]     # delegate to other agents

[tools]
builtin = ["final", "search", "load_skill"]
external = ["Read", "Write", "Edit"]  # client-side tools

[[tools.dynamic]]
name = "my_api"
type = "http"
description = "Call my API"
config = { base_url = "$API_URL", headers = { "Authorization" = "Bearer $TOKEN" } }

[[available_skills]]
id = "*"
name = "*"
---

# System Prompt

Your instructions here. Supports Handlebars templates:
- {{task}} — the user's message
- {{> skills}} — available skills listing
- {{> connections}} — available connections

See Agent Definition docs for the full schema.

Skills

Skills are reusable instruction documents agents load on demand:

---
name = "data_pipeline"
description = "How to run the data transformation pipeline"
tags = ["data", "etl"]
context = "inline"
---

# Data Pipeline

## Steps
1. Fetch data with `my_api` tool...
2. Transform using Python...

# Push skills
distri skills push skills/data_pipeline.md
distri skills list

Agents call load_skill("data_pipeline") at runtime. Two modes:

• Inline (default) — content injected into conversation, survives context compaction
• Fork — spawns isolated child agent with skill as instructions

React SDK (DistriJS)

Embed agents in your React app:

npm install @distri/react

import { useAgent, Chat } from '@distri/react';

function App() {
  const { agent } = useAgent({ agentIdOrDef: 'my_agent' });
  return <Chat agent={agent} threadId="conversation-1" />;
}

Features: SSE streaming, tool execution with custom renderers, voice I/O, developer mode, browser-side file tools (IndexedDB-backed Read/Write/Edit/Glob/Grep).

See the DistriJS docs for full integration guide.

CLI Reference

Server & UI

distri serve                        # Start server + UI on port 7777
distri serve --port 8080            # Custom port
distri serve --no-ui                # API-only
distri update                       # Pull latest server + UI
distri version                      # Show versions
distri uninstall                    # Clean ~/.distri/

Agent & skill management

distri                              # Interactive TUI
distri run --task "..." [--agent A] # Run a task
distri run --task "..." --remote    # Run in sandboxed container

distri agents list / push / delete  # Manage agents
distri skills list [-a] / push      # Manage skills

Debugging & tools

distri traces list / show ID [-v]   # Debug with trace viewer
distri tools list / invoke          # Inspect and test tools

Connections & config

distri connections list / token     # OAuth connections
distri secrets list / set / delete  # Manage secrets
distri workflows run / push         # DAG workflows

distri login                        # Auth with Distri Cloud
distri profile list / use / config  # Multi-profile management

Invocation & Traces

Distri has two invocation APIs, both fully traced (agent → steps → LLM → tools, with tokens/cost/latency and provenance) in the Traces view / distri traces list:

// JS (@distri/core)
const agent = await Agent.create('scoring_agent', client)
await agent.invoke({ /* messages */, contextId, tags: { team: 'growth' } })   // execute
await client.llm(messages, tools, { agent_id: 'scoring_agent', thread_id, title })  // llm_execute

// Rust (distri client)
run_agent(&client, RunOptions { agent: Some("scoring_agent".into()), task, thread_id,
                                tags: Some(tags), trace_context: None, ..Default::default() }, cb).await?;   // execute
client.llm_execute(LlmExecuteOptions::new(LLmContext { thread_id, label, messages, ..Default::default() })
                       .with_agent_id("scoring_agent".into())).await?;          // llm_execute

distri run --agent scoring_agent --task "grade: 2+2=4" --tag team=growth   # CLI

Grouping calls into one trace: give related calls the same thread / context id (contextId on execute, thread_id on llm_execute) — Distri derives the trace id from it, so they collapse into a single trace (e.g. all grading calls of one eval run). For cross-process propagation, pass an explicit trace_context { trace_id, parent_span_id } on execute to nest the agent's spans under a caller's existing trace.

See the full guide: Traces & Tracing Context.

Architecture

distri/
├── distri-types/          # Shared type definitions
├── distri-cli/            # CLI binary
├── distri/                # Client library
├── distri-formatter/      # Output formatting
│
├── server/
│   ├── distri-core/       # Agent engine (orchestrator, loop, tools, LLM)
│   ├── distri-server/     # HTTP server (actix-web, A2A endpoints)
│   ├── distri-stores/     # Storage backends (SQLite, Postgres)
│   ├── distri-auth/       # Auth providers
│   ├── distri-parsers/    # Parsing utilities
│   └── agents/            # Built-in agent definitions (.md)
│
└── samples/               # Example applications
    └── scraper/           # Web scraping agent

Execution Flow

User message → AgentOrchestrator
  → Load agent definition
  → Create ExecutorContext (thread, task, run)
  → AgentLoop
    → PlanningStrategy.plan() → LLM produces plan
    → ExecutionStrategy.execute_step() per step
      → Tool calls (builtin, dynamic, external, MCP)
      → Event streaming (SSE)
    → Loop until final tool or max iterations
  → Return result

Development

# Build
cargo build

# Run tests
cargo test

# Test a specific crate
cargo test -p distri-core

This repo is the Rust backend only. The TypeScript SDK (@distri/core, @distri/react, @distri/components) lives in distrihub/distrijs.

Samples

Licensing

• Root and common components: MIT License
• Server components (server/): Elastic License 2.0 — follows fair-code principles

Links

• Documentation
• Distri Cloud
• GitHub Releases
• Issues