Shannon — Production AI Agents That Actually Work

Ship reliable AI agents to production. Multi-strategy orchestration, swarm collaboration, token budget control, human approval workflows, and time-travel debugging — all built in. Live Demo

View real-time agent execution and event streams

Multi-agent orchestration with execution strategies, WASI sandboxing, and built-in observability

Why Shannon?

The Problem	Shannon's Solution
Agents fail silently?	Temporal workflows with time-travel debugging — replay any execution step-by-step
Costs spiral out of control?	Hard token budgets per task/agent with automatic model fallback
No visibility into what happened?	Real-time event streaming, Prometheus metrics, OpenTelemetry tracing
Security concerns?	WASI sandbox for code execution, OPA policies, multi-tenant isolation
Vendor lock-in?	Works with OpenAI, Anthropic, Google, DeepSeek, xAI, local models via Ollama

Quick Start

Prerequisites

Docker and Docker Compose
An API key for at least one LLM provider (OpenAI, Anthropic, etc.)

One-Command Install

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

This downloads config, prompts for API keys, pulls Docker images, and starts services.

Required API Keys (choose one):

OpenAI: OPENAI_API_KEY=sk-...
Anthropic: ANTHROPIC_API_KEY=sk-ant-...
Or any OpenAI-compatible endpoint

Optional but recommended:

Web Search: SERPAPI_API_KEY=... (serpapi.com)
Web Fetch: FIRECRAWL_API_KEY=... (firecrawl.dev)

Building from source? See Development below.

Platform-specific guides: Ubuntu | Rocky Linux | Windows | Windows (中文)

Your First Agent

Shannon provides multiple ways to interact with AI agents:

REST API

# Submit a 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 events in real-time
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=<task_id>"

Python SDK

pip install shannon-sdk

from shannon import ShannonClient

with ShannonClient(base_url="http://localhost:8080") as client:
    handle = client.submit_task("What is the capital of France?", session_id="demo")
    result = client.wait(handle.task_id)
    print(result.result)

See Python SDK Documentation.

OpenAI-Compatible API

# Drop-in replacement for OpenAI API
export OPENAI_API_BASE=http://localhost:8080/v1
# Your existing OpenAI code works unchanged

Desktop App

Download from GitHub Releases (macOS, Windows, Linux), or build from source:

cd desktop && npm install && npm run tauri:build

See Desktop App Guide.

Architecture

Client --> Gateway (Go) --> Orchestrator (Go) --> Agent Core (Rust) --> LLM Service (Python) --> Providers
             |                    |                      |                      |
             | Auth/Rate limit    | Temporal workflows    | WASI sandbox         | Tool execution
             |                    | Budget management     | Token enforcement    | Agent loop
             |                    | Complexity routing    | Circuit breaker      | Context management
             v                    v                       v                      v
           PostgreSQL          Temporal                 Redis              Tool Adapters

Core Services

Service	Language	Port	Role
Gateway	Go	8080	REST API, auth (JWT/API key), rate limiting
Orchestrator	Go	50052	Temporal workflows, task decomposition, budget management
Agent Core	Rust	50051	Enforcement gateway, WASI sandbox, token counting
LLM Service	Python	8000	Provider abstraction, MCP tools, agent loop
Playwright	Python	8002	Browser automation for web scraping

Execution Strategies

Tasks are automatically routed based on complexity:

Strategy	Trigger	Use Case
Simple	Complexity < 0.3	Single-agent, direct response
DAG	Multi-step tasks (default)	Fan-out/fan-in with dependency tracking
ReAct	Iterative reasoning	Reasoning + tool use loops
Research	Multi-step research	Tiered models for cost optimization (50-70% reduction)
Exploratory	Tree-of-Thoughts	Parallel hypothesis exploration
Browser Use	Web interaction tasks	Playwright-backed browsing agent
Domain Analysis	Specialized analysis	Domain-specific deep research
Swarm	Autonomous teams	Lead-orchestrated multi-agent with convergence detection

Core Capabilities

Research Workflows

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare renewable energy adoption in EU vs US",
    "context": {"force_research": true, "research_strategy": "deep"}
  }'

Swarm Multi-Agent

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze this dataset from multiple perspectives",
    "context": {"force_swarm": true}
  }'

Skills System

curl http://localhost:8080/api/v1/skills           # List skills
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "Review the auth module", "skill": "code-review", "session_id": "review-123"}'

Create custom skills in config/skills/user/ (create the directory if it doesn't exist — it's gitignored). See Skills System.

Human-in-the-Loop Approval

Enable approval gates via OPA policy or workflow templates with require_approval: true. Approvals route to connected daemon clients via WebSocket.

# Submit an approval decision
curl -X POST http://localhost:8080/api/v1/approvals/decision \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "<workflow_id>", "approval_id": "<approval_id>", "approved": true}'

Session Continuity

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "What is GDP?", "session_id": "econ-101"}'
# Follow-up remembers context
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "How does it relate to inflation?", "session_id": "econ-101"}'

Scheduled Tasks

curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Analysis", "cron_expression": "0 9 * * *", "task_query": "Analyze market trends"}'

Token Budget Control

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate a market report",
    "context": {"budget_max": 5000}
  }'

Time-Travel Debugging

./scripts/replay_workflow.sh task-prod-failure-123

10+ LLM Providers

Anthropic: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5
OpenAI: GPT-5.1, GPT-5 mini, GPT-5 nano
Google: Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro Preview
xAI: Grok 4 (reasoning & non-reasoning), Grok 3 Mini
DeepSeek: DeepSeek Chat, DeepSeek Reasoner
MiniMax: M2.7, M2.7-highspeed
Groq: Llama, Mixtral (ultra-fast inference)
Others: Qwen, Meta (Llama 4), Zhipu (GLM), Kimi
Local: Ollama, LM Studio, vLLM — any OpenAI-compatible endpoint
Automatic failover between providers

API Endpoints

Endpoint	Orchestrator?	Format	Use Case
`POST /v1/chat/completions`	Yes	OpenAI-compatible	Apps using OpenAI SDK
`POST /v1/completions`	No (proxy)	OpenAI-compatible	Thin LLM proxy
`POST /api/v1/tasks`	Yes	Shannon native (sync)	Full orchestrator pipeline
`POST /api/v1/tasks/stream`	Yes	Shannon native (SSE)	Streaming orchestration

Tool Execution: GET /api/v1/tools, POST /api/v1/tools/{name}/execute

Auth: GET /api/v1/auth/me, POST /api/v1/auth/refresh-key, GET/POST/DELETE /api/v1/auth/api-keys

Sessions: GET/PATCH/DELETE /api/v1/sessions/{id}, history, events, files

Task Control: POST /api/v1/tasks/{id}/cancel|pause|resume, GET .../control-state|events|timeline

Schedules: Full CRUD at /api/v1/schedules, plus pause, resume, runs

Real-Time: GET /api/v1/stream/sse, GET /api/v1/stream/ws, WS /v1/ws/messages (daemon)

Project Structure

shannon/
├── go/orchestrator/          # Temporal workflows, budget manager, gateway
│   ├── cmd/gateway/          # REST API gateway (auth, rate limiting)
│   └── internal/             # Workflows, strategies, activities
├── rust/agent-core/          # Enforcement gateway, WASI sandbox
├── python/llm-service/       # LLM providers, MCP tools, agent loop
├── desktop/                  # Tauri + Next.js desktop application
├── clients/python/           # Python SDK
├── protos/                   # Shared protobuf definitions
├── config/                   # YAML configuration files
├── deploy/compose/           # Docker Compose for local dev + release
├── migrations/               # PostgreSQL schema migrations
├── scripts/                  # Automation and helper scripts
└── docs/                     # Architecture and API documentation

Configuration

File	Purpose
`.env`	API keys, runtime settings
`config/shannon.yaml`	Feature flags, auth, tracing
`config/models.yaml`	LLM providers, pricing, capabilities
`config/features.yaml`	Workflow settings, execution modes
`config/openai_models.yaml`	Custom `shannon-*` model names for OpenAI-compatible API
`config/research_strategies.yaml`	Research strategy model tiers

Service Ports (Local Development)

Service	Port	Protocol
Gateway	8080	HTTP
Orchestrator	50052 (gRPC), 8081 (health)	gRPC/HTTP
Agent Core	50051	gRPC
LLM Service	8000	HTTP
Temporal	7233 (gRPC), 8088 (UI)	gRPC/HTTP
PostgreSQL	5432	TCP
Redis	6379	TCP

Development

Building from Source

git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon
make setup                              # Create .env + generate protobuf stubs
vim .env                                # Add your API key
./scripts/setup_python_wasi.sh          # Download Python WASI interpreter
make dev                                # Start all services
make smoke                              # Run E2E smoke tests

Development Commands

make dev      # Start all services
make smoke    # E2E smoke tests
make ci       # Full CI suite
make proto    # Regenerate protobuf files
make lint     # Run linters
make logs     # View service logs
make down     # Stop all services

Browser Automation (Optional)

The Playwright service enables browser automation workflows (3.4GB image with Chromium). It is not started by default. To enable it:

# Development
docker compose -f deploy/compose/docker-compose.yml --profile browser up -d

# Pre-built images
docker compose -f deploy/compose/docker-compose.release.yml --profile browser up -d

Test it with:

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query":"Go to https://waylandz.com and get the page title","session_id":"test","context":{"role":"browser_use"}}'

Using Pre-built Images

cd Shannon
cp .env.example .env && vim .env
docker compose -f deploy/compose/docker-compose.release.yml up -d

Troubleshooting

Health Checks

docker compose -f deploy/compose/docker-compose.yml ps
curl http://localhost:8080/health
curl http://localhost:8081/health

Common Issues

Services not starting:

Check .env has required API keys
Ensure ports 8080, 8081, 50052 are not in use
Run docker compose down && docker compose up -d to recreate

Task execution fails:

Verify LLM API key is valid
Check orchestrator logs: docker compose logs -f orchestrator

Out of memory:

Reduce WASI_MEMORY_LIMIT_MB (default: 512)
Lower HISTORY_WINDOW_MESSAGES (default: 50)

Documentation

Resource	Description
Official Docs	Full documentation site
Architecture	System design deep-dive
Streaming APIs	SSE and WebSocket streaming
Skills System	Custom skill development
Session Workspaces	WASI sandbox guide
Extending Shannon	Custom tools and templates
Swarm Agents	Multi-agent collaboration

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License — Use it anywhere, modify anything. See LICENSE.

Stop debugging AI failures. Start shipping reliable agents.

GitHub · Docs

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
clients/python		clients/python
config		config
deploy/compose		deploy/compose
desktop		desktop
docs		docs
examples/openai-sdk		examples/openai-sdk
go/orchestrator		go/orchestrator
migrations		migrations
protos		protos
python		python
rust		rust
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md

Folders and files

Latest commit

History

Repository files navigation

Shannon — Production AI Agents That Actually Work

Why Shannon?

Quick Start

Prerequisites

One-Command Install

Your First Agent

REST API

Python SDK

OpenAI-Compatible API

Desktop App

Architecture

Core Services

Execution Strategies

Core Capabilities

Research Workflows

Swarm Multi-Agent

Skills System

Human-in-the-Loop Approval

Session Continuity

Scheduled Tasks

Token Budget Control

Time-Travel Debugging

10+ LLM Providers

API Endpoints

Project Structure

Configuration

Service Ports (Local Development)

Development

Building from Source

Development Commands

Browser Automation (Optional)

Using Pre-built Images

Troubleshooting

Health Checks

Common Issues

Documentation

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages