Shannon
Production multi-agent orchestration with budgets, replayable workflows, and policy-controlled execution.
- Source repo
- Kocoro-lab/Shannon
- Stars
- ★ 2.3k
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Go
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A platform engineering team needs self-hosted, retryable, replayable Temporal workflows for multi-step AI operations.
- Not a fit if
- Teams that want to run it without Docker, PostgreSQL, Redis, and Temporal
- Small teams unwilling to maintain a Go, Rust, and Python stack
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Shannon is a production-oriented multi-agent orchestration framework built across Go, Rust, and Python services. Its architecture combines a Gateway, a Temporal-based Orchestrator, a Rust Agent Core with WASI sandboxing, and a Python LLM Service for provider and tool interactions. Tasks can enter through native REST endpoints, SSE, a Python SDK, a desktop application, or an OpenAI-compatible API, then route to strategies such as Simple, DAG, ReAct, Research, and Swarm. It is designed to run as a self-hosted Docker Compose stack with PostgreSQL, Redis, and Temporal; Playwright browser automation is optional. It best fits teams that need execution replay, spend controls, approval gates, and operational visibility around agent workflows.
A client submits a query, session_id, and optional context to POST /api/v1/tasks; the Gateway handles REST access, JWT/API-key authentication, and rate limiting, while the Orchestrator uses Temporal for decomposition, strategy selection, and budget management. Agent Core performs token counting, circuit breaking, and WASI sandbox enforcement, and the LLM Service calls providers including OpenAI, Anthropic, Google, DeepSeek, xAI, and Ollama while exposing MCP tools and an agent loop. Shannon returns task results synchronously or emits execution events through GET /api/v1/stream/sse, WebSocket, and task-event endpoints. It also exposes tool execution, session management, scheduling, and controls to cancel, pause, or resume tasks.
- A platform engineering team needs self-hosted, retryable, replayable Temporal workflows for multi-step AI operations.
- An application team wants to preserve an OpenAI SDK integration while routing requests through
OPENAI_API_BASE=http://localhost:8080/v1for orchestration and task controls. - A research team needs multi-stage research, parallel perspective analysis, or lead-orchestrated agent teams using
force_researchorforce_swarm. - A team handling sensitive execution steps needs WASI isolation, OPA policy controls, and human approval gates.
- A web-automation workflow needs a Playwright-backed browsing agent and can enable the separate browser Compose profile.
How do you install or deploy this agent?
Prerequisites are Docker, Docker Compose, and an API key for at least one LLM provider. Run: curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash. The documented installer downloads configuration, prompts for API keys, pulls Docker images, and starts services. For a source build: git clone https://github.com/Kocoro-lab/Shannon.git && cd Shannon && make setup; add an API key to .env, run ./scripts/setup_python_wasi.sh, then run make dev.
How do you use this agent?
After the services start, submit a first task: curl -X POST http://localhost:8080/api/v1/tasks -H "Content-Type: application/json" -d '{"query":"What is the capital of France?","session_id":"demo"}'. Stream its events with curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=<task_id>". For Python, install shannon-sdk, create ShannonClient(base_url="http://localhost:8080"), then call submit_task and wait. For the OpenAI-compatible route, set OPENAI_API_BASE=http://localhost:8080/v1.
What are this agent's strengths and limitations?
- Uses Temporal workflows and provides
replay_workflow.shfor step-by-step execution replay, which is directly useful for investigating workflow failures. - Combines hard token budgets, budget-driven model fallback, and multiple complexity-routed execution strategies.
- Offers several documented integration paths: native REST, SSE/WebSocket, a Python SDK, and an OpenAI-compatible API.
- Documents concrete control components for execution: WASI sandboxing, OPA policies, multi-tenant isolation, and human approval workflows.
- Deployment requires Docker, Docker Compose, and at least one LLM-provider API key, alongside services such as PostgreSQL, Redis, and Temporal.
- The implementation spans Go, Rust, Python, and an optional Tauri/Next.js desktop app, increasing the surface area for source builds and troubleshooting.
- Playwright automation is disabled by default, and its Chromium image is documented as approximately 3.4GB.
- The README lists provider support and automatic failover, but does not provide evidence of feature parity or production SLA across providers.
How does this agent compare with similar options?
The README positions Shannon around production reliability: compared with LangChain's LLM-chain and RAG focus and CrewAI's role-based task delegation focus, Shannon emphasizes Temporal workflows, time-travel debugging, and hard token budgets.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Shannon This agent | 53 · Major gaps | Self-hosted serviceFree + model costs | ★ 2.3k | 2mo ago | Go | OpenAI API · Claude API |
| MassGen | 51 · Major gaps | CLIFree + model costs | ★ 1.1k | 4mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Agent Squad | 31 · Major gaps | Library / SDKFree + model costs | ★ 7.8k | 29d ago | Python | OpenAI API · Claude API |
| Vigil Multi-Agent Terminal Orchestrator | 69 · Some gaps | Desktop appFree + model costs | ★ 28 | 29d ago | Swift | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows WASI sandbox, OPA policies, multi-tenant isolation, human approval workflows, token budget control, but implementation details are not shown in provided files, and publisher identity is unverified. Deductions: security features are mostly asserted without code-level evidence; publisher unverified.
README and CI config show Temporal workflows, time-travel debugging, health checks, error handling, but no actual run results. Deductions: dependency availability unverified, failure message specifics not shown.
README shows multiple execution strategies, many LLM providers, platform-specific guides, but capability boundaries and trigger precision are not fully specified. Deductions: capability boundaries and trigger conditions incomplete.
Clear architecture docs, install guides, examples and FAQ, but known limitations and changelog incomplete. Deductions: known limitations not explicitly listed, changelog not provided.
Multiple APIs and SDKs provided, output formats clear, but no actual performance or cost data. Deductions: cost-benefit not quantified.
README claims partially correspond to code structure, but lack independent verification. Deductions: claim-code correspondence incomplete, facts and inferences not clearly separated.
- Publisher identity unverified, proceed with caution.
- Security features are mostly asserted, review actual code implementation.
- Dependency availability and failure messages unverified.
- Known limitations and changelog incomplete.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.5.1 Shannon v0.5.1
Release notes excerpt
Shannon v0.5.1 Docker Images ```bash docker pull waylandzhang/gateway:v0.5.1 docker pull waylandzhang/orchestrator:v0.5.1 docker pull waylandzhang/agent-core:v0.5.1 docker pull waylandzhang/llm-service:v0.5.1 docker pull waylandzhang/playwright-service:v0.5.1 ``` Quick Start ```bash curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash ``` Full Changelog See [CHANGELOG.md](https://github.com/Kocoro-lab/Shannon/blob/v0.5.1/CHANGELOG.md)View on GitHub ↗ -
v0.5.0 Shannon v0.5.0
Release notes excerpt
Shannon v0.5.0 Docker Images ```bash docker pull waylandzhang/gateway:v0.5.0 docker pull waylandzhang/orchestrator:v0.5.0 docker pull waylandzhang/agent-core:v0.5.0 docker pull waylandzhang/llm-service:v0.5.0 docker pull waylandzhang/playwright-service:v0.5.0 ``` Quick Start ```bash curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash ``` Full Changelog See [CHANGELOG.md](https://github.com/Kocoro-lab/Shannon/blob/v0.5.0/CHANGELOG.md)View on GitHub ↗ -
v0.4.1 Shannon v0.4.1
Release notes excerpt
Shannon v0.4.1 Docker Images ```bash docker pull waylandzhang/gateway:v0.4.1 docker pull waylandzhang/orchestrator:v0.4.1 docker pull waylandzhang/agent-core:v0.4.1 docker pull waylandzhang/llm-service:v0.4.1 docker pull waylandzhang/playwright-service:v0.4.1 ``` Quick Start ```bash curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash ``` Full Changelog See [CHANGELOG.md](https://github.com/Kocoro-lab/Shannon/blob/v0.4.1/CHANGELOG.md)View on GitHub ↗
FAQ
Can we keep using an existing OpenAI SDK integration?
OPENAI_API_BASE to http://localhost:8080/v1.Is Shannon tied to one model provider?
How can a team cap task spend?
budget_max in the task context. The README states that Shannon enforces hard token limits and can fall back to cheaper models as a budget nears exhaustion.Is browser automation enabled automatically?
--profile browser option.