Distri: A Composable Agent Framework

Distri

Distri は Rust で構築されたオープンソースの AI エージェントフレームワークです。エージェントを Markdown で定義し、製品の関数をツールとして接続して、CLI、API サーバー、または React UI に組み込んで実行できます。

ドキュメント · ウェブサイト · Distri Cloud

Distri を選ぶ理由

• Markdown でエージェントを定義 — 動作、ツール、モデル設定を、TOML フロントマター付きの単一の .md ファイルで定義できます
• 組み込みのツールシステム — 組み込み機能（検索、シェル、ブラウザー）、動的な HTTP ツール、外部のクライアント側ツール、MCP に対応しています
• スキル — エージェントが実行時に load_skill を使って読み込む、必要に応じたナレッジドキュメントです。コンテキストの圧縮後も自動で再注入されます
• サブエージェント — エージェントが、分離されたコンテキストとトークン予算を持つ専門の子エージェントにタスクを委任します
• リモート実行 — 信頼できないコードやリソースの分離のために、サンドボックス化されたコンテナでエージェントを実行できます
• React SDK — ストリーミング、ツールレンダラー、音声、開発者モードに対応した <Chat /> コンポーネントをすぐに利用できます
• A2A 互換 — エージェントの検出と呼び出しのための A2A プロトコルを実装しています
• セルフホスト可能 — 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"

実行

インストール後、サーバーとウェブ UI を起動します。

distri serve

初回起動時に、対応する distri-server バイナリと UI バンドルが github.com/distrihub/distri/releases から ~/.distri/ にダウンロードされます。ブラウザーが自動的に起動し、http://localhost:7777 を開きます。

serve オプション

ライフサイクルコマンド

クイックスタート

組み込みエージェントを実行する

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

独自のエージェントを定義する

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

組み込みエージェント

検索、ブラウザー、シェルのツールには BROWSR_BASE_URL と BROWSR_API_KEY が必要です。Distri Cloud では自動的に設定されます。

エージェント定義の形式

エージェントは TOML フロントマターを含む 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

スキーマの詳細については、エージェント定義のドキュメントをご覧ください。

スキル

スキルは、エージェントが必要に応じて読み込む再利用可能な指示ドキュメントです。

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

エージェントは実行時に load_skill("data_pipeline") を呼び出します。モードは 2 種類あります。

• Inline（デフォルト）— 内容を会話に挿入します。コンテキストの圧縮後も保持されます
• Fork — スキルを指示として持つ、分離された子エージェントを起動します

React SDK（DistriJS）

エージェントを React アプリに組み込みます。

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 ストリーミング、カスタムレンダラーによるツール実行、音声入出力、開発者モード、ブラウザー側のファイルツール（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/

エージェントとスキルの管理

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 には 2 つの呼び出し API があり、どちらも Traces ビュー／distri traces list で完全にトレースされます（エージェント → ステップ → 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

複数の呼び出しを 1 つのトレースにまとめる： 関連する呼び出しに同じスレッド／コンテキスト IDを指定します（execute では contextId、llm_execute では thread_id）。Distri はその ID からトレース ID を導出するため、呼び出しが 1 つのトレースにまとめられます（例：1 回の評価実行におけるすべての評価呼び出し）。 プロセス間で伝播させるには、execute に明示的な trace_context { trace_id, parent_span_id } を渡し、呼び出し元の既存のトレースの下にエージェントのスパンをネストします。

詳細なガイドについては、**トレースとトレースコンテキスト**をご覧ください。

アーキテクチャ

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 — フェアコードの原則に準拠

リンク

• ドキュメント
• Distri Cloud
• GitHub リリース
• 課題