Distri: A Composable Agent Framework

Distri

Distri 是一个用 Rust 构建的开源 AI Agent 框架。使用 Markdown 定义 Agent，将产品功能连接为工具，然后通过命令行、API 服务或嵌入 React UI 来运行它们。

文档 · 网站 · Distri Cloud

为什么选择 Distri

• 以 Markdown 定义 Agent — 在单个带 TOML frontmatter 的 .md 文件中定义行为、工具和模型设置
• 内置工具系统 — 内置工具（搜索、shell、浏览器）、动态 HTTP 工具、外部客户端工具和 MCP 支持
• 技能 — Agent 在运行时通过 load_skill 按需加载的知识文档；上下文压缩后会自动重新注入
• 子 Agent — Agent 将任务委派给专门的子 Agent，并为其分配独立的上下文和 token 预算
• 远程执行 — 在沙箱容器中运行 Agent，以处理不受信任的代码或隔离资源
• React SDK — 即插即用的 <Chat /> 组件，支持流式传输、工具渲染器、语音和开发者模式
• 兼容 A2A — 实现用于 Agent 发现和调用的 A2A protocol
• 可自托管 — 使用 SQLite 在自己的基础设施上运行，无需外部依赖。

安装

# 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"

运行

安装后，启动服务和 Web UI：

distri serve

首次运行时，会从 github.com/distrihub/distri/releases 下载匹配的 distri-server 二进制文件和 UI 包到 ~/.distri/。随后会自动在浏览器中打开 http://localhost:7777。

服务选项

生命周期命令

快速开始

运行内置 Agent

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

定义自己的 Agent

创建 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}}

运行它

# 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

推送到 Distri Cloud

distri login
distri agents push agents/my_agent.md

内置 Agent

搜索、浏览器和 shell 工具需要 BROWSR_BASE_URL 和 BROWSR_API_KEY。在 Distri Cloud 上会自动配置。

Agent 定义格式

Agent 是带有 TOML frontmatter 的 Markdown 文件：

---
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

完整模式请参阅 Agent 定义文档。

技能

技能是可复用的指令文档，Agent 可按需加载：

---
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

Agent 在运行时调用 load_skill("data_pipeline")。有两种模式：

• Inline（默认）——将内容注入对话，并在上下文压缩后保留
• Fork ——启动独立的子 Agent，并将技能作为指令

React SDK（DistriJS）

在 React 应用中嵌入 Agent：

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" />;
}

功能：SSE 流式传输、支持自定义渲染器的工具执行、语音 I/O、开发者模式、浏览器端文件工具（由 IndexedDB 支持的 Read/Write/Edit/Glob/Grep）。

完整集成指南请参阅 DistriJS 文档。

CLI 参考

服务端和 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 和技能管理

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

调试和工具

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

连接和配置

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

调用与跟踪

Distri 有两种调用 API，二者都会在 Traces 视图 / distri traces list 中完整记录跟踪信息（Agent → 步骤 → LLM → 工具， 包括令牌数 / 成本 / 延迟和来源）：

// 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

将调用归入同一条跟踪： 为相关调用指定相同的 thread / context id （execute 中的 contextId，llm_execute 中的 thread_id）——Distri 会据此派生跟踪 ID， 从而将它们合并为一条跟踪（例如，一次评估运行中的所有评分调用）。 如需跨进程传递跟踪信息，可在 execute 中传入显式的 trace_context { trace_id, parent_span_id }， 将 Agent 的 span 嵌套在调用方已有的跟踪中。

完整指南请参阅：跟踪与跟踪上下文。

架构

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

执行流程

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

开发

# Build
cargo build

# Run tests
cargo test

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

此仓库仅包含 Rust 后端。TypeScript SDK（@distri/core、 @distri/react、@distri/components）位于 distrihub/distrijs。

示例

许可

• 根目录和通用组件：MIT License
• 服务端组件（server/）：Elastic License 2.0——遵循 fair-code 原则

链接

• 文档
• Distri Cloud
• GitHub 版本发布
• 问题反馈