SAGO-Agent

Production-grade multi-agent orchestration system — 339 specialist agents, 56+ production tools, multi-LLM support, streaming, parallel execution, feedback loops, workflows, containerized card TUI with dashboard, and built-in security.

What is Sago?

Sago is a production-grade multi-agent orchestration system built for real-world software engineering tasks. It goes beyond simple code generation — it autonomously delegates work to 339 specialist agents, uses 56+ production tools, streams responses token-by-token, runs agents in parallel, manages sessions, enforces permissions, and runs workflows.

Key Capabilities

Quick Start

# Clone the repository
git clone https://github.com/SAGO-AUTOMATES/SAGO-Agent.git
cd SAGO-Agent

# Install dependencies
pip install -e .

# Set your API key
export OPENROUTER_API_KEY="your-key-here"

# Launch the TUI
sago tui

# Or run tasks from CLI
sago smart "Fix the authentication bug"
sago run "Build a REST API" --agent python-engineer

Installation

From Source (Recommended)

git clone https://github.com/SAGO-AUTOMATES/SAGO-Agent.git
cd SAGO-Agent
pip install -e .

Using uv (Faster)

git clone https://github.com/SAGO-AUTOMATES/SAGO-Agent.git
cd SAGO-Agent
uv pip install -e .

Documentation & Technical Flows

• 📘 Architecture & Execution Flows (docs/FLOWS.md) — In-depth guide to Vector DB/RAG, Multi-Agent Swarms, Tool Permissions & Self-Healing Verification.
• 🛠️ Commands Reference (docs/COMMANDS.md) — Complete CLI and TUI slash command reference.
• 📦 Project Structure (docs/PROJECT.md) — Module map, agent registry, and engine layout.
• 🏗️ Build & Installation Guide (docs/BUILD.md) — Developer build, test, and dependency instructions.

Dependencies

• Python 3.11+
• openai (for LLM calls)
• textual (for TUI)
• pydantic (for data validation)

Optional:

• crewai (for CrewAI orchestration path)
• langgraph (for LangGraph workflow engine)
• anthropic (for Claude provider)
• google-generativeai (for Gemini provider)

CLI Commands

See docs/COMMANDS.md for full CLI and TUI command reference.

Core Execution

Interactive TUI

Workflows

System

339 Agents Across 22 Categories

50 Production Tools

See docs/TOOLS.md for complete tool documentation with usage examples.

File Operations

• read_file — Read file contents
• write_file — Write files with auto-directory creation
• glob_files — Pattern-based file search
• grep_content — Regex content search
• file_operations — Move, copy, delete, rename, mkdir, list
• archive — Create/extract zip, tar, tar.gz, tar.bz2
• hash_checksum — MD5, SHA1, SHA256, SHA512
• diff_tool — Compare files/text
• regex_tester — Test/debug regular expressions
• pdf_reader — Extract text from PDFs
• data_processor — JSON/YAML parse, validate, format, query, merge

Shell & System

• execute_shell — Run shell commands
• background_process — Run commands in background
• process_manager — List/kill processes
• env_info — System, disk, memory, network info
• env_manager — Environment variable management
• os_detector — Detect operating system
• cron_schedule — Manage scheduled tasks
• screenshot — Capture screenshots

Network

• http_client — API requests (GET, POST, PUT, DELETE)
• web_crawler — Crawl websites, extract content
• dns_lookup — DNS resolution
• port_scan — Scan ports
• network_config — Network configuration info

SSH

• ssh_connect — SSH connections
• ssh_command — Execute remote commands
• ssh_transfer — File transfer via SCP/SFTP

Coding

• code_analyzer — Code structure, complexity, issues
• linter — Code linting
• formatter — Code formatting
• test_runner — Run tests
• debugger — Debug with breakpoints, AST analysis
• log_analyzer — Analyze log files
• text_summarizer — Summarize text

DevOps

• docker_ops — Docker ps, build, run, compose
• git_ops — Git status, log, diff, commit, push

Session & Other

• session_manager — Session management
• clipboard — Clipboard operations
• prompt_generator — Generate prompts
• permission_manager — Manage permissions
• spawn_agent — Delegate to specialist agents

Permission System

Sago includes a risk-based permission system that controls which tools can be executed.

Risk Levels

Managing Permissions

# View all tool permissions
/permissions

# View blocked tools only
/permissions blocked

# Allow a tool
/allow execute_shell

# Block a tool
/block sudo_executor

Configuration

Permissions are stored in ~/.sago/permissions.json:

{
  "auto_approve_safe": true,
  "auto_approve_low": true,
  "require_approval_medium": true,
  "require_approval_high": true,
  "require_approval_critical": true,
  "blocked_tools": ["dangerous_tool"]
}

Session Persistence

Sessions are automatically saved to SQLite (~/.sago/data/sago.db) and can be exported to JSON.

# Save current session
/save my-session

# List saved sessions
/sessions

# Load a session
/load my-session

# Export to markdown
/export

# Compact context (summarize old messages)
/compact

Token Usage & Cost Tracking

# In TUI
/cost

# From CLI
sago usage

Output includes:

• Total input/output tokens
• Cache hit/miss counts and savings percentage
• Per-model cost breakdown (9 models supported)
• Session-level and cumulative tracking

Workflow Engine

Create stateful, multi-step automations:

# Create a workflow
sago workflow-create "Deploy Pipeline"

# Add steps with dependencies
sago workflow-add-step <id> --name "Test" --type agent_call --config '{"task": "Run tests"}'
sago workflow-add-step <id> --name "Build" --type tool_call --config '{"tool": "execute_shell", "args": {"command": "make build"}}' --depends-on test-step
sago workflow-add-step <id> --name "Deploy" --type agent_call --config '{"task": "Deploy to production"}' --depends-on build-step

# Execute
sago workflow-run <id>

# Stream execution
sago workflow-run <id> --stream

Architecture

See docs/PROJECT.md for detailed project structure. MCP server documented in docs/MCP.md.

sago/
├── agents/              # 339 agent profiles
│   ├── profiles/        # One .py per agent with metadata
│   ├── registry.py      # Agent loading and lookup
│   ├── spawner.py       # Agent execution with feedback loops
│   └── handoff.py       # HandoffContext, RecursionGuard, FeedbackRequest
├── tools/               # 50 production tools
│   ├── base.py          # BaseTool with permission checks
│   ├── file/            # File operations (12 tools)
│   ├── shell/           # Shell execution
│   ├── network/         # HTTP, DNS, crawling
│   ├── coding/          # Code analysis, debugging
│   ├── ssh/             # SSH operations
│   ├── system/          # Git, Docker, env
│   └── admin/           # Sudo, permissions
├── engine/              # Execution engines
│   ├── simple_executor.py   # Smart executor with auto-discovery
│   └── unified.py           # Unified executor (simple/crewai/langgraph)
├── permissions.py       # Risk-based permission system
├── workflow/            # Workflow engine
│   ├── engine.py        # Stateful workflows with dependencies
│   └── langgraph_engine.py  # LangGraph integration
├── server/              # TCP daemon server
│   └── daemon.py        # Background daemon with client
├── mcp/                 # Model Context Protocol
│   └── server.py        # MCP server with 50 tools
├── tui/                 # Terminal UI
│   ├── app.py           # Textual TUI with dashboard
│   ├── widgets/         # AgentDashboard, AgentSpinner, HandoffFlow
│   ├── helpers.py       # Agent-tagged message rendering
│   └── smart_input.py   # Input processor
├── llm/                 # LLM providers
│   ├── openai_provider.py
│   ├── openrouter.py
│   ├── gemini.py
│   └── claude.py
├── memory/              # Memory and context
│   ├── rag.py           # RAG memory with search
│   ├── compaction.py    # Session compaction
│   └── profiles.py      # User profiles
├── cache/               # Intelligent caching
│   └── intelligent.py   # Content-hash cache with TTL/LRU
├── tracking/            # Usage tracking
│   └── token_tracker.py # Token counting and cost
├── sessions/            # Session management
│   └── manager.py       # Multi-session with parallel execution
├── errors/              # Error handling
│   └── handler.py       # Recovery with fallback tools
├── database.py          # SQLite persistence
├── paths.py             # Cross-platform paths
├── config/              # Configuration
│   ├── loader.py
│   ├── project_config.py
│   └── sago.yaml
└── main.py              # CLI entry point

Quality

Sago includes comprehensive coverage across unit, integration, and security categories.

433 tests — all passing. See docs/ERRORS.md for error handling and docs/FLOWS.md for system flowcharts.

Quality Areas

Security

Path Traversal Protection

• Tools validate file paths before execution
• Blocked paths configurable per project

Command Injection Protection

• Shell commands validated before execution
• Permission system blocks dangerous operations

Permission Bypass Prevention

• High/critical risk tools require explicit approval
• Session-isolated approval state
• Blocked tools cannot be executed even with valid credentials

Input Validation

• Empty/None inputs handled gracefully
• Special characters sanitized
• Error messages don't expose internals

Sensitive Data Filtering

• API keys never exposed in tool output
• Passwords filtered from system info

LLM Providers

Effort Levels

Configuration

Project Config

After sago init, edit config.sago.json:

{
  "agents": {
    "python-engineer": {
      "enabled": true,
      "system_prompt_override": "Custom prompt...",
      "tools_add": ["web_crawler"],
      "temperature": 0.8
    }
  },
  "permissions": {
    "allow_shell_execute": true,
    "allow_ssh": false,
    "blocked_paths": ["/etc", "/sys"]
  }
}

Global Config

Stored in ~/.sago/:

~/.sago/
├── data/sago.db          # SQLite database
├── permissions.json      # Tool permissions
├── sessions/             # Saved sessions (JSON)
└── config.yaml           # Global configuration

CI/CD

GitHub Actions pipeline runs on every push:

1. Lint — Ruff code quality
2. Type Check — MyPy static analysis
3. Unit Tests — Tool, permission, agent tests
4. Integration Tests — Executor, server, workflow tests
5. Security Tests — Vulnerability checks
6. Build — Package build verification

See .github/workflows/ci.yml for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Make your changes
4. Ensure code quality with linting
5. Submit a pull request

Development Setup

git clone https://github.com/SAGO-AUTOMATES/SAGO-Agent.git
cd SAGO-Agent
pip install -e ".[dev]"

Documentation

License

GPL-3.0 - see LICENSE for details.

Sago — Because every task deserves the perfect agent.