convez.ai
AgenteAutomaçãoAvançado
prime-radiant-inc

Sprout: Sistema Multi-Agente Autoaprendizável

prime-radiant-inc/sprout

Sistema multi-agente recursivo que se auto-melhora aprendendo de falhas

Ver no GitHub
BomPluginScore · de 0 a 100

Um sistema experimental de agentes IA que se autoaperfeiçoa através de decomposição recursiva de tarefas e delegação a especialistas. O agente raiz quebra objetivos em subgoals, delega a especialistas, e aprende de falhas mutando um genoma baseado em git. Suporta Claude, GPT e Gemini com arquitetura hierárquica de delegação completa.

Instalação

$npx convez-ai prime-radiant-inc/sprout

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
112
Forks
13
Acompanhando
2
Saúde
37%
Último commit
há 3 meses
Versão
—
Issues abertas
3
Contribuidores
1

Casos de uso

  • Automação de desenvolvimento de software complexo com decomposição automática de tarefas
  • Assistência de codificação autonôma que se adapta e melhora com o uso
  • Orquestração de múltiplos especialistas (arquiteto, eng, revisor) para projetos grandes
  • Sistemas que precisam aprender e evoluir comportamentos através de feedback de falhas

Veredito

Sprout é um projeto ambicioso de multi-agência inteligente com arquitetura bem pensada (genoma git, aprendizado assíncrono, hierarquia clara), mas ainda experimental — recomendado para quem busca explorar sistemas autoaprendizáveis e não teme lidar com complexidade significativa. Excelente como base para pesquisa e prototipagem de agentes em cascata.

README

A tradução para o português deste README ainda está na fila.

🌱 Sprout

A self-improving, multi-agent AI system that decomposes tasks and delegates to specialist agents. Sprout is an autonomous coding assistant built on a recursive agent architecture — where every action is a goal-directed delegation to a subagent.

Overview

Sprout operates on a simple but powerful loop:

Perceive → Recall → Plan → Act → Verify ─── loop
                                  │
                                  └──→ Learn (async)

A root agent receives your goal, breaks it into subgoals, and delegates each to a specialist. Specialists can be orchestrators themselves (delegating further) or leaf workers that execute primitives directly. The system learns from its mistakes — stumbles, failures, and inefficiencies are detected and fed into an asynchronous learning pipeline that mutates the agent genome over time.

Key Concepts

  • Agents all the way down — Every action is a delegation to a subagent. The root never executes tools directly.
  • Genome — A git-backed knowledge base storing agent definitions, memories, routing rules, and learned behaviors. Every mutation is committed for full auditability and rollback.
  • Primitives — The immutable kernel operations: read_file, write_file, edit_file, apply_patch, exec, grep, glob, fetch. Only leaf agents execute these.
  • Learn signals — Failures, timeouts, retries, and inefficiencies are detected automatically. When patterns emerge (≥3 repeated stumbles, ≥2 unresolved errors), the system triggers genome mutations to improve future performance.
  • Multi-provider LLM — First-class support for Anthropic (Claude), OpenAI (GPT/o-series), OpenAI Codex, and Google (Gemini) with a unified adapter interface.

Architecture

root (best model — orchestrator)
  ├─ utility/reader          (fast — read-only file discovery)
  ├─ utility/editor          (balanced — file editing & creation)
  ├─ utility/command-runner  (fast — shell command execution)
  ├─ utility/web-reader      (fast — HTTP requests & web content)
  ├─ utility/mcp             (fast — Model Context Protocol client)
  ├─ utility/task-manager    (fast — task tracking)
  ├─ project-explorer        (fast — codebase analysis)
  ├─ architect               (best — system design)
  ├─ tech-lead               (best — engineering orchestrator)
  │    ├─ engineer           (best — implementation)
  │    ├─ spec-reviewer      (best — spec compliance)
  │    └─ quality-reviewer   (best — code quality)
  ├─ verifier                (best — test & build verification)
  ├─ debugger                (best — systematic debugging)
  └─ quartermaster           (best — capability expert & meta-agent)
       ├─ qm-indexer         (fast — discover & cache capabilities)
       ├─ qm-planner         (best — design multi-step plans)
       ├─ qm-fabricator      (best — build new specialist agents)
       └─ qm-reconciler      (best — genome reconciliation)

Agent Definitions

Agents are defined as Markdown specs in root/. Each spec declares:

FieldDescription
nameAgent identifier
descriptionWhat the agent does (shown to parent agents)
modelLLM tier: best, balanced, or fast
toolsList of primitives this agent can use
agentsList of subagent paths this agent can delegate to
max_turnsMaximum planning iterations before forced stop
max_depthHow deep in the delegation tree this agent can appear
can_spawnWhether the agent can delegate to subagents
timeoutMaximum wall-clock time for the agent
can_learnWhether learn signals from this agent trigger genome mutations
system_promptThe agent's personality, instructions, and constraints

The Quartermaster

The quartermaster is a meta-agent that understands what Sprout can do and helps extend it:

  • Oracle mode — "What tools/agents exist?" → Indexes all capabilities and returns a synthesis.
  • Planner mode — "How do I accomplish X?" → Builds a concrete plan using available tools.
  • Fabricator mode — "Build a specialist for Y" → Creates a new agent YAML, writes it to the genome, and refreshes the capability index.

This means Sprout can grow its own agent roster at runtime.

Inter-Agent Communication

Agents communicate over a WebSocket pub/sub bus with topic-based messaging:

session/{session_id}/agent/{handle_id}/{channel}

Channels include inbox, events, and ready. Agents can be spawned as separate processes, enabling true parallelism for non-blocking delegations.

The Kernel

The kernel is the immutable foundation — the parts of Sprout that never change:

  1. Core loop — Perceive → Recall → Plan → Act → Verify
  2. Primitives — The 8 built-in tool operations
  3. Learn process — Stumble detection and genome mutation
  4. Audit log — JSONL event stream for every session
  5. Safety constraints — Path validation, timeouts, depth limits

Learning & Memory

Sprout maintains persistent memory across sessions:

  • Memories — Keyword-tagged observations with time-decay confidence (30-day half-life). Automatically recalled when relevant to the current task.
  • Routing rules — Learned heuristics for which agent to delegate to for specific task patterns.
  • Metrics — Per-agent stumble rates and action counts, used to decide when learning should trigger.
  • Git history — Every genome mutation is committed, so any change can be inspected or rolled back.

Installation

Prerequisites

  • Bun runtime (v1.0+)
  • TypeScript 5+
  • At least one LLM provider credential

Setup

# Clone the repository
git clone <repo-url>
cd sprout

# Install dependencies (root + web)
bun install

# Set up API-key-backed LLM providers as environment variables
export ANTHROPIC_API_KEY="your-key-here"
# and/or
export OPENAI_API_KEY="your-key-here"
# and/or
export GOOGLE_API_KEY="your-key-here"

The OpenAI Codex provider kind (openai-codex) uses ChatGPT OAuth from provider settings. It does not use OPENAI_API_KEY and does not accept a pasted API key. Add or edit an OpenAI Codex provider in settings, then use the provider settings login/logout actions to sign in or out with ChatGPT.

Model Resolution

Sprout maps abstract tiers to concrete models:

TierAnthropicOpenAIGoogle
bestclaude-opus-4-6gpt-4.1gemini-2.5-pro
balancedclaude-sonnet-4-6——
fastclaude-haikugpt-4.1-minigemini-2.0-flash

The provider is selected based on which provider credentials are available.

Usage

Interactive Mode

# Start an interactive session
bun run src/host/cli.ts

# Or use the binary name
bunx sprout

This opens a terminal UI with:

  • Rich conversation view with collapsible tool details
  • Status bar showing context usage, turns, tokens, and model
  • Emacs-style keybindings (Ctrl+A/E, Ctrl+K/U, etc.)
  • Command history (up/down arrows)
  • Model switching at runtime

One-Shot Mode

# Execute a single goal and exit
bunx sprout --prompt "Add error handling to the login function in src/auth.ts"

Session Management

# List previous sessions
bunx sprout --resume

# Resume a specific session
bunx sprout --resume <session-id>

# Resume the most recent session
bunx sprout --resume-last

Genome Management

# List all agents in the genome
bunx sprout --genome list

# View genome mutation history
bunx sprout --genome log

# Roll back a genome mutation
bunx sprout --genome rollback <commit-hash>

Web Interface

Sprout includes a browser-based UI as an alternative to the terminal.

# Start with both TUI and web interface
bunx sprout --web

# Headless mode (web only, no terminal UI)
bunx sprout --web-only

# Specify a port (default: 7777)
bunx sprout --web-only --port 8080

You can also start the web server mid-session with the /web slash command (and stop it with /web stop).

Development workflow:

# Terminal 1: Run Sprout headless on a fixed port
bunx sprout --web-only --port 7777

# Terminal 2: Run the Vite dev server with hot reload
bun run web:dev

To build the web UI for production: bun run web:build

Slash Commands

While in interactive mode:

CommandDescription
/helpShow available commands
/modelSwitch LLM model
/compactManually trigger context compaction
/clearClear conversation history
/statusShow session status
/webStart the web server (opens browser)
/web stopStop the web server
/quitExit the session

MCP Integration

Sprout includes a standalone MCP (Model Context Protocol) client CLI:

# List configured MCP servers
bun run root/agents/utility/agents/mcp/tools/mcp-cli.ts list-servers

# List tools on a server
bun run root/agents/utility/agents/mcp/tools/mcp-cli.ts list-tools github

# Call a tool
bun run root/agents/utility/agents/mcp/tools/mcp-cli.ts call-tool github search_repositories '{"query": "sprout"}'

MCP servers are configured in mcp.json.

Project Configuration

AGENTS.md

Place an AGENTS.md file in your project root (next to .git) to give Sprout project-specific context. Sprout discovers this file automatically by walking up from the current directory.

You can also:

  • Place a global AGENTS.md at ~/.config/sprout/AGENTS.md for cross-project guidance
  • Use AGENTS.override.md in subdirectories for directory-specific overrides
  • Stay within the 32 KiB budget for assembled project docs

Genome Path

Default genome path precedence:

  • --genome-path <path> (highest)
  • SPROUT_GENOME_PATH
  • $XDG_DATA_HOME/sprout-genome
  • ~/.local/share/sprout-genome (fallback)

Override explicitly with:

bunx sprout --genome-path /path/to/genome

Project Structure

sprout/
├── root/                  # Agent tree (Markdown specs)
│   ├── root.md            # Root orchestrator
│   ├── preambles/         # Shared system prompt fragments
│   │   ├── global.md
│   │   ├── orchestrator.md
│   │   └── worker.md
│   └── agents/            # Nested agent tree
│       ├── utility/agents/ # Leaf workers (reader, editor, command-runner, etc.)
│       ├── tech-lead.md    # Engineering orchestrator
│       ├── tech-lead/agents/ # engineer, spec-reviewer, quality-reviewer
│       ├── quartermaster.md
│       ├── quartermaster/agents/ # qm-indexer, qm-planner, qm-fabricator, qm-reconciler
│       ├── architect.md
│       ├── verifier.md
│       ├── debugger.md
│       └── project-explorer.md
├── docs/                  # Internal documentation
├── src/
│   ├── agents/            # Agent lifecycle, planning, delegation, verification
│   ├── bus/               # WebSocket pub/sub for inter-process communication
│   ├── genome/            # Persistent knowledge base (agents, memories, routing)
│   ├── host/              # CLI, session management, bus infrastructure
│   ├── kernel/            # Primitives, path constraints, execution sandbox
│   ├── learn/             # Stumble detection, metrics, genome mutation triggers
│   ├── llm/               # Multi-provider LLM adapters (Anthropic, OpenAI, Gemini)
│   ├── tui/               # Terminal UI (Ink/React components)
│   ├── web/               # Web server (HTTP + WebSocket bridge)
│   ├── util/              # Utilities
│   ├── index.ts           # Public API exports
│   └── mcp-cli.ts         # Standalone MCP client CLI
├── web/                   # Browser UI (Vite + React + TypeScript)
├── test/                  # Comprehensive test suite (55+ test files)
│   ├── fixtures/vcr/      # Recorded HTTP responses for integration tests
│   └── helpers/           # Test utilities (VCR replay)
├── package.json
├── tsconfig.json
├── biome.json             # Linting & formatting (Biome)
└── mcp.json               # MCP server configuration

Development

Code Quality

# Install project git hooks once per clone
bun run hooks:install

# Type checking
bun run typecheck

# Lint
bun run lint

# Format
bun run format

# All checks
bun run check

# CI-equivalent local gate
bun run check:ci

# Deep local hygiene (CI gate + dead code + dependency cycles)
bun run check:deep

# Dead-code report (non-blocking)
bun run deadcode

# Runtime dead-code gate (unresolved-import check + trace checks)
bun run deadcode:runtime

# Strict dependency-cycle gate (non-zero on findings)
bun run deps:cycles:strict

# Repeat unit lane to catch flakes
FLAKE_RUNS=10 bun run test:flake

Testing

Sprout uses Bun's native test runner with a comprehensive suite of 55+ test files:

# Run all unit tests
bun run test:unit

# Run with watch mode
bun run test:watch

# Run integration tests (uses VCR-recorded HTTP responses)
bun run test:integration

# Record new VCR cassettes (makes real API calls)
bun run test:integration:record

# Run integration tests against live APIs
bun run test:integration:live

Testing patterns:

  • Unit tests mock the LLM Client with predetermined responses
  • Integration tests use a VCR (Video Cassette Recorder) pattern — HTTP responses are recorded once and replayed in CI
  • All file I/O tests use isolated temp directories (mkdtemp)
  • Agent tests verify event emission, delegation flows, timeout handling, and lifecycle

Pre-commit

# Run checks + typecheck + unit tests
bun run precommit

# Run pre-push checks manually (same gate as .githooks/pre-push)
bun run check:ci && bun run deps:cycles

How It Works — A Walkthrough

Say you ask: "Add input validation to the signup form"

  1. Root agent receives the goal and plans: "I need to understand the current code, then edit it."
  2. Root delegates to reader: "Find the signup form component and return its contents."
  3. Reader uses glob + read_file primitives, returns the code.
  4. Root delegates to editor: "Add email format validation and password strength checks to src/components/SignupForm.tsx."
  5. Editor uses read_file → edit_file → read_file (verify), returns success.
  6. Root delegates to command-runner: "Run the test suite to make sure nothing broke."
  7. Command-runner uses exec("bun test"), returns results.
  8. If tests fail, root detects the stumble and iterates — delegating back to editor with the error context.
  9. Throughout, learn signals are emitted asynchronously. If the editor repeatedly fails on a certain pattern, the genome is mutated to improve its prompt or add a memory.

Baseline Performance

From 2,201 tracked sessions:

MetricValue
Total tool uses77,220
Total messages237,000
Average stumble rate3.7%
Total stumbles2,890
Top stumble sourceCommand failures (33%)

Tech Stack

ComponentTechnology
RuntimeBun
LanguageTypeScript 5 (strict mode)
Terminal UIInk (React for CLIs)
LLM ProvidersAnthropic, OpenAI, OpenAI Codex, Google GenAI
Code QualityBiome
TestingBun native test runner + VCR
IPCWebSocket pub/sub bus
PersistenceGit-backed JSONL + YAML

Version

0.1.0

Ver o original no GitHub

Bom para

Relacionados