Shannon

Shannon

An open-source, enterprise-ready AI agent platform built with Rust for performance, Go for orchestration, Python for LLMs, and Solana for Web3 trust.

Stars: 106

Visit
 screenshot

Shannon is a battle-tested infrastructure for AI agents that solves problems at scale, such as runaway costs, non-deterministic failures, and security concerns. It offers features like intelligent caching, deterministic replay of workflows, time-travel debugging, WASI sandboxing, and hot-swapping between LLM providers. Shannon allows users to ship faster with zero configuration multi-agent setup, multiple AI patterns, time-travel debugging, and hot configuration changes. It is production-ready with features like WASI sandbox, token budget control, policy engine (OPA), and multi-tenancy. Shannon helps scale without breaking by reducing costs, being provider agnostic, observable by default, and designed for horizontal scaling with Temporal workflow orchestration.

README:

Shannon — Production AI Agents That Actually Work

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│     We're building a unified dashboard and a centralized documentation hub,  │
│     with all features already implemented in the code. We're working hard    │
│     to polish them, and we'd love your support!                              │
│                                                                              │
│     Please ⭐ star this repo to show your interest and stay updated as we    │
│     refine these tools. Thanks for your patience and encouragement!          │
│                                                                              │
└────────────────────────────────────────────────────────────────────────────-─┘

License: MIT Go Version Rust Docker PRs Welcome

Stop burning money on AI tokens. Ship reliable agents that won't break in production.

Shannon is battle-tested infrastructure for AI agents that solves the problems you'll hit at scale: runaway costs, non-deterministic failures, and security nightmares. Built on Temporal workflows and WASI sandboxing, it's the platform we wished existed when our LLM bills hit $50k/month.

🔥 The Problems We Solve

  • "Our AI costs are out of control" → 70% token reduction via intelligent caching
  • "We can't debug production issues" → Deterministic replay of any workflow
  • "Agents keep breaking randomly" → Time-travel debugging with full state history
  • "We're worried about prompt injection" → WASI sandbox + OPA policies for bulletproof security
  • "Different teams need different models" → Hot-swap between 15+ LLM providers
  • "We need audit trails for compliance" → Every decision logged and traceable

⚡ What Makes Shannon Different

🚀 Ship Faster

  • Zero Configuration Multi-Agent - Just describe what you want: "Analyze data, then create report" → Shannon handles dependencies automatically
  • Multiple AI Patterns - ReAct, Tree-of-Thoughts, Chain-of-Thought, Debate, and Reflection (configurable via cognitive_strategy)
  • Time-Travel Debugging - Export and replay any workflow to reproduce exact agent behavior
  • Hot Configuration - Change models, prompts, and policies without restarts

🔒 Production Ready

  • WASI Sandbox - Full Python 3.11 support with bulletproof security (→ Guide)
  • Token Budget Control - Hard limits per user/session with real-time tracking
  • Policy Engine (OPA) - Define who can use which tools, models, and data
  • Multi-Tenancy - Complete isolation between users, sessions, and organizations

📈 Scale Without Breaking

  • 70% Cost Reduction - Smart caching, session management, and token optimization
  • Provider Agnostic - OpenAI, Anthropic, Google, Azure, Bedrock, DeepSeek, Groq, and more
  • Observable by Default - Prometheus metrics, Grafana dashboards, OpenTelemetry tracing
  • Distributed by Design - Horizontal scaling with Temporal workflow orchestration

Model pricing is centralized in config/models.yaml - all services load from this single source for consistent cost tracking.

🎯 Why Shannon vs. Others?

Challenge Shannon LangGraph AutoGen CrewAI
Multi-Agent Orchestration ✅ DAG/Graph workflows ✅ Stateful graphs ✅ Group chat ✅ Crew/roles
Agent Communication ✅ Message passing ✅ Tool calling ✅ Conversations ✅ Delegation
Memory & Context ✅ Long/short-term, vector ✅ Multiple types ✅ Conversation history ✅ Shared memory
Debugging Production Issues ✅ Replay any workflow ❌ Good luck ❌ Printf debugging
Token Cost Control ✅ Hard budget limits
Security Sandbox ✅ WASI isolation
Policy Control (OPA) ✅ Fine-grained rules
Deterministic Replay ✅ Time-travel debugging
Session Persistence ✅ Redis-backed, durable ⚠️ In-memory only ⚠️ Limited
Multi-Language ✅ Go/Rust/Python ⚠️ Python only ⚠️ Python only ⚠️ Python only
Production Metrics ✅ Prometheus/Grafana ⚠️ DIY

🚀 Quick Start

Prerequisites

  • Docker and Docker Compose
  • Make, curl, grpcurl
  • An API key for at least one supported LLM provider
Docker Setup Instructions (click to expand)

Installing Docker

macOS:

# Install Docker Desktop from https://www.docker.com/products/docker-desktop/
# Or using Homebrew:
brew install --cask docker

Linux (Ubuntu/Debian):

# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

Verifying Docker Installation

docker --version
docker compose version

Docker Services

The make dev command starts all services:

  • PostgreSQL: Database on port 5432
  • Redis: Cache on port 6379
  • Qdrant: Vector store on port 6333
  • Temporal: Workflow engine on port 7233 (UI on 8088)
  • Orchestrator: Go service on port 50052
  • Agent Core: Rust service on port 50051
  • LLM Service: Python service on port 8000

30-Second Setup

git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon
make setup-env

# Download Python WASI interpreter for secure code execution (20MB)
./scripts/setup_python_wasi.sh

Add at least one LLM API key to .env (for example):

echo "OPENAI_API_KEY=your-key-here" >> .env

Start the stack and run a smoke check:

make dev
make smoke

Your First Agent

Shannon provides a simple REST API for easy integration and real-time streaming to monitor agent actions:

Submit Your First Task

# For development (no auth required)
export GATEWAY_SKIP_AUTH=1

# Submit a task
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze the sentiment of: Shannon makes AI agents simple!",
    "session_id": "demo-session-123"
  }'

# Response includes workflow_id for tracking
# {"workflow_id":"task-dev-1234567890","status":"running"}

Watch Your Agent Work in Real-Time

# Stream live events as your agent works (replace with your workflow_id)
curl -N http://localhost:8081/stream/sse?workflow_id=task-dev-1234567890

# You'll see human-readable events like:
# event: AGENT_THINKING
# data: {"message":"Analyzing sentiment: Shannon makes AI agents simple!"}
#
# event: TOOL_INVOKED
# data: {"message":"Processing natural language sentiment analysis"}
#
# event: AGENT_COMPLETED
# data: {"message":"Task completed successfully"}

Get Your Results

# Check final status and result
curl http://localhost:8080/api/v1/tasks/task-dev-1234567890

# Response includes status, result, tokens used, and metadata

Production Setup

For production, use API keys instead of GATEWAY_SKIP_AUTH:

# Create an API key (one-time setup)
make seed-api-key  # Creates test key: sk_test_123456

# Use in requests
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -H "Content-Type: application/json" \
  -d '{"query":"Your task here"}'
Advanced Methods: Scripts, gRPC, and Command Line (click to expand)

Using Shell Scripts

# Submit a simple task
./scripts/submit_task.sh "Analyze the sentiment of: 'Shannon makes AI agents simple!'"

# Check session usage and token tracking (session ID is in SubmitTask response message)
grpcurl -plaintext \
  -d '{"sessionId":"YOUR_SESSION_ID"}' \
  localhost:50052 shannon.orchestrator.OrchestratorService/GetSessionContext

# Export and replay a workflow history (use the workflow ID from submit_task output)
./scripts/replay_workflow.sh <WORKFLOW_ID>

Direct gRPC Calls

# Submit via gRPC
grpcurl -plaintext \
  -d '{"query":"Analyze sentiment","sessionId":"test-session"}' \
  localhost:50052 shannon.orchestrator.OrchestratorService/SubmitTask

# Stream events via gRPC
grpcurl -plaintext \
  -d '{"workflowId":"task-dev-1234567890"}' \
  localhost:50052 shannon.orchestrator.OrchestratorService/StreamEvents

WebSocket Streaming

# Connect to WebSocket for bidirectional streaming
wscat -c ws://localhost:8081/api/v1/stream/ws?workflow_id=task-dev-1234567890

Temporal UI (Visual Workflow Debugging)

# Access Temporal Web UI for visual workflow inspection
open http://localhost:8088

# Or navigate manually to see:
# - Workflow execution history and timeline
# - Task status, retries, and failures
# - Input/output data for each step
# - Real-time workflow progress
# - Search workflows by ID, type, or status

The Temporal UI provides a powerful visual interface to:

  • Debug workflows - See exactly where and why workflows fail
  • Monitor performance - Track execution times and bottlenecks
  • Inspect state - View all workflow inputs, outputs, and intermediate data
  • Search & filter - Find workflows by various criteria
  • Replay workflows - Visual replay of historical executions

🌐 API Features

The REST API supports:

  • Idempotency: Use Idempotency-Key header for safe retries
  • Rate Limiting: Per-API-key limits to prevent abuse
  • Resume on Reconnect: SSE streams can resume from last event using Last-Event-ID
  • WebSocket: Available at /api/v1/stream/ws for bidirectional streaming

💰 Real-World Impact

Before Shannon vs After

Metric Before After Impact
Monthly LLM Costs $50,000 $15,000 -70%
Debug Time (P1 issues) 4-6 hours 15 minutes -95%
Agent Success Rate 72% 94% +22%
Mean Time to Recovery 45 min 3 min -93%
Security Incidents 3/month 0 -100%

📚 Examples That Actually Matter

Example 1: Cost-Controlled Customer Support

# Set hard budget limits - agent stops before breaking the bank
{
    "query": "Help me troubleshoot my deployment issue",
    "session_id": "user-123-session",
    "budget": {
        "max_tokens": 10000,        # Hard stop at 10k tokens
        "alert_at": 8000,           # Alert at 80% usage
        "rate_limit": "100/hour"    # Max 100 requests per hour
    },
    "policy": "customer_support.rego"  # OPA policy for allowed actions
}
# Result: 70% cost reduction, zero runaway bills

Example 2: Debugging Production Failures

# Production agent failed at 3am? No problem.
# Export and replay the workflow in one command
./scripts/replay_workflow.sh task-prod-failure-123

# Or specify a particular run ID
./scripts/replay_workflow.sh task-prod-failure-123 abc-def-ghi

# Output shows step-by-step execution with token counts, decisions, and state changes
# Fix the issue, add a test case, never see it again

Example 3: Multi-Team Model Governance

# teams/data-science/policy.rego
allow_model("gpt-4o") if team == "data-science"
allow_model("claude-4") if team == "data-science"
max_tokens(50000) if team == "data-science"

# teams/customer-support/policy.rego
allow_model("gpt-4o-mini") if team == "support"
max_tokens(5000) if team == "support"
deny_tool("database_write") if team == "support"

Example 4: Security-First Code Execution

# Python code runs in isolated WASI sandbox with full standard library
./scripts/submit_task.sh "Execute Python: print('Hello from secure WASI!')"

# Even malicious code is safe
./scripts/submit_task.sh "Execute Python: import os; os.system('rm -rf /')"
# Result: OSError - system calls blocked by WASI sandbox

# Advanced: Session persistence for data analysis
./scripts/submit_task.sh "Execute Python with session 'analysis': data = [1,2,3,4,5]"
./scripts/submit_task.sh "Execute Python with session 'analysis': print(sum(data))"
# Output: 15

→ Full Python Execution Guide

More Production Examples (click to expand)
  • Incident Response Bot: Auto-triages alerts with budget limits
  • Code Review Agent: Enforces security policies via OPA rules
  • Data Pipeline Monitor: Replays failed workflows for debugging
  • Compliance Auditor: Full trace of every decision and data access
  • Multi-Tenant SaaS: Complete isolation between customer agents

See docs/production-examples/ for battle-tested implementations.

🏗️ Architecture

High-Level Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│ Orchestrator │────▶│ Agent Core  │
└─────────────┘     │     (Go)     │     │   (Rust)    │
                    └──────────────┘     └─────────────┘
                           │                     │
                           ▼                     ▼
                    ┌──────────────┐     ┌─────────────┐
                    │   Temporal   │     │ WASI Tools  │
                    │   Workflows  │     │   Sandbox   │
                    └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ LLM Service  │
                    │   (Python)   │
                    └──────────────┘

Production Data Flow

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                            │
├─────────────┬─────────────┬─────────────┬───────────────────────┤
│    HTTP     │    gRPC     │     SSE     │  WebSocket (soon)     │
└─────────────┴─────────────┴─────────────┴───────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR (Go)                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐   │
│  │   Router   │──│   Budget   │──│  Session   │──│   OPA    │   │
│  │            │  │  Manager   │  │   Store    │  │ Policies │   │
│  └────────────┘  └────────────┘  └────────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────────┘
        │                │                 │                │
        ▼                ▼                 ▼                ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│   Temporal   │ │    Redis     │ │  PostgreSQL  │ │   Qdrant     │
│  Workflows   │ │    Cache     │ │    State     │ │   Vectors    │
│              │ │   Sessions   │ │   History    │ │   Memory     │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                       AGENT CORE (Rust)                         │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐   │
│  │    WASI    │──│   Policy   │──│    Tool    │──│  Agent   │   │
│  │   Sandbox  │  │  Enforcer  │  │  Registry  │  │  Comms   │   │
│  └────────────┘  └────────────┘  └────────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────────┘
        │                                              │
        ▼                                              ▼
┌────────────────────────────────┐    ┌─────────────────────────────────┐
│     LLM SERVICE (Python)       │    │     OBSERVABILITY LAYER         │
│  ┌────────────┐ ┌────────────┐ │    │  ┌────────────┐ ┌────────────┐  │
│  │  Provider  │ │    MCP     │ │    │  │ Prometheus │ │  OpenTel   │  │
│  │  Adapter   │ │   Tools    │ │    │  │  Metrics   │ │  Traces    │  │
│  └────────────┘ └────────────┘ │    │  └────────────┘ └────────────┘  │
└────────────────────────────────┘    └─────────────────────────────────┘

Core Components

  • Orchestrator (Go): Task routing, budget enforcement, session management, OPA policy evaluation
  • Agent Core (Rust): WASI sandbox execution, policy enforcement, agent-to-agent communication
  • LLM Service (Python): Provider abstraction (15+ LLMs), MCP tools, prompt optimization
  • Data Layer: PostgreSQL (workflow state), Redis (session cache), Qdrant (vector memory)
  • Observability: Prometheus metrics, OpenTelemetry tracing, Grafana dashboards

🚦 Getting Started for Production

Day 1: Basic Setup

# Clone and configure
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon
make setup-env
echo "OPENAI_API_KEY=sk-..." >> .env

# Start with budget limits
echo "DEFAULT_MAX_TOKENS=5000" >> .env
echo "DEFAULT_RATE_LIMIT=100/hour" >> .env

# Launch
make dev

Day 2: Add Policies

# Create your first OPA policy
cat > config/policies/default.rego << EOF
package shannon

default allow = false

# Allow all for dev, restrict in prod
allow {
    input.environment == "development"
}

# Production rules
allow {
    input.environment == "production"
    input.tokens_requested < 10000
    input.model in ["gpt-4o-mini", "claude-4-haiku"]
}
EOF

# Hot reload - no restart needed!

Day 7: Debug Your First Issue

# Something went wrong in production?
# 1. Find the workflow ID from logs
grep ERROR logs/orchestrator.log | tail -1

# 2. Export the workflow
./scripts/replay_workflow.sh export task-xxx-failed debug.json

# 3. Replay locally to see exactly what happened
./scripts/replay_workflow.sh replay debug.json

# 4. Fix, test, deploy with confidence

Day 30: Scale to Multiple Teams

# config/teams.yaml
teams:
  data-science:
    models: ["gpt-4o", "claude-4-sonnet"]
    max_tokens_per_day: 1000000
    tools: ["*"]

  customer-support:
    models: ["gpt-4o-mini"]
    max_tokens_per_day: 50000
    tools: ["search", "respond", "escalate"]

  engineering:
    models: ["claude-4-sonnet", "gpt-4o"]
    max_tokens_per_day: 500000
    tools: ["code_*", "test_*", "deploy_*"]

📖 Documentation

Getting Started

Core Features

Architecture

API & Integration

Embeddings & Vector Memory

  • How vectors are generated: The Go orchestrator calls the Python LLM Service at /embeddings/, which by default uses OpenAI (model text-embedding-3-small).
  • Graceful degradation: If no embedding provider is configured (e.g., no OPENAI_API_KEY) or the endpoint is unavailable, workflows still run. Vector features degrade gracefully:
    • No vectors are stored (vector upserts are skipped)
    • Session memory retrieval returns an empty list
    • Similar-query enrichment is skipped
  • Enable vectors: Set OPENAI_API_KEY in .env, keep vector.enabled: true in config/shannon.yaml, and run Qdrant (port 6333)
  • Disable vectors: Set vector.enabled: false in config/shannon.yaml (or set degradation.fallback_behaviors.vector_search: skip)

🔧 Development

Local Development

# Run linters and formatters
make lint
make fmt

# Run smoke tests
make smoke

# View logs
make logs

# Check service status
make ps

Testing

# Run integration tests
make integration-tests

# Run specific integration test
make integration-single

# Test session management
make integration-session

# Run coverage reports
make coverage

🤝 Contributing

We love contributions! Please see our Contributing Guide for details.

🌟 Community

❓ FAQ

Q: How is this different from just using LangGraph? A: LangGraph is a library for building stateful agents. Shannon is production infrastructure. We handle the hard parts: deterministic replay for debugging, token budget enforcement, security sandboxing, and multi-tenancy. You can even use LangGraph within Shannon if you want.

Q: Can I migrate from my existing LangGraph/AutoGen setup? A: Yes. Most migrations take 1-2 days. We provide adapters and migration guides. Your agents get instant upgrades: 70% cost reduction, replay debugging, and production monitoring.

Q: What's the overhead? A: ~50ms latency, 100MB memory per agent. The tradeoff: your agents don't randomly fail at 3am, and you can actually debug when they do.

Q: Is it really enterprise-ready? A: We run 1M+ agent executions/day in production. Temporal (our workflow engine) powers Uber, Netflix, and Stripe. WASI (our sandbox) is a W3C standard. This isn't a weekend project.

Q: What about vendor lock-in? A: Zero lock-in. Standard protocols (gRPC, HTTP, SSE). Export your workflows anytime. Swap LLM providers with one line. MIT licensed forever.

📊 Project Status

Battle-Tested in Production

  • 1M+ workflows/day across 50+ organizations
  • 99.95% uptime (excluding LLM provider outages)
  • $2M+ saved in token costs across users
  • Zero security incidents with WASI sandboxing

What's Coming (Roadmap)

Now → v0.1 (Production Ready)

  • Core platform stable - Go orchestrator, Rust agent-core, Python LLM service
  • Deterministic replay debugging - Export and replay any workflow execution
  • OPA policy enforcement - Fine-grained security and governance rules
  • WebSocket streaming - Real-time agent communication with event filtering and replay
  • SSE streaming - Server-sent events for browser-native streaming
  • MCP integration - Model Context Protocol for standardized tool interfaces
  • WASI sandbox - Secure code execution environment with resource limits
  • Multi-agent orchestration - DAG workflows with parallel execution
  • Vector memory - Qdrant-based semantic search and context retrieval
  • Circuit breaker patterns - Automatic failure recovery and degradation
  • Multi-provider LLM support - OpenAI, Anthropic, Google, DeepSeek, and more
  • Token budget management - Hard limits with real-time tracking
  • Session management - Durable state with Redis/PostgreSQL persistence
  • 🚧 LangGraph adapter - Bridge to LangChain ecosystem (integration framework complete)
  • 🚧 AutoGen adapter - Bridge to Microsoft AutoGen multi-agent conversations

v0.2

  • [ ] Enterprise SSO - SAML/OAuth integration with existing identity providers
  • [ ] Natural language policies - Human-readable policy definitions with AI assistance
  • [ ] Enhanced monitoring - Custom dashboards and alerting rules
  • [ ] Advanced caching - Multi-level caching with semantic deduplication
  • [ ] Real-time collaboration - Multi-user agent sessions with shared context
  • [ ] Plugin ecosystem - Third-party tool and integration marketplace
  • [ ] Workflow marketplace - Community-contributed agent templates and patterns
  • [ ] Edge deployment - WASM execution in browser environments

v0.3

  • [ ] Autonomous agent swarms - Self-organizing multi-agent systems
  • [ ] Cross-organization federation - Secure agent communication across tenants
  • [ ] Predictive scaling - ML-based resource allocation and optimization
  • [ ] Blockchain integration - Proof-of-execution and decentralized governance
  • [ ] Advanced personalization - User-specific LoRA adapters and preferences

v0.4

  • [ ] Continuous learning - Automated prompt and strategy optimization
  • [ ] Multi-agent marketplaces - Economic incentives and reputation systems
  • [ ] Advanced reasoning - Hybrid symbolic + neural approaches
  • [ ] Global deployment - Multi-region, multi-cloud architecture
  • [ ] Regulatory compliance - SOC 2, GDPR, HIPAA automation
  • [ ] AI safety frameworks - Constitutional AI and alignment mechanisms

Track detailed progress →

📚 Documentation

Core Guides

API References

🚀 Start Building Production AI Today

# You're 3 commands away from production-ready AI agents
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon && make setup-env && make dev

# Join 1,000+ developers shipping reliable AI

Get Involved

🔮 Coming Soon

Solana Integration for Web3 Trust

We're building decentralized trust infrastructure with Solana blockchain:

  • Cryptographic Verification: On-chain attestation of AI agent actions and results
  • Immutable Audit Trail: Blockchain-based proof of task execution
  • Smart Contract Interoperability: Enable AI agents to interact with DeFi and Web3 protocols
  • Token-Gated Capabilities: Control agent permissions through blockchain tokens
  • Decentralized Reputation: Build trust through verifiable on-chain agent performance

Stay tuned for our Web3 trust layer - bringing transparency and verifiability to AI systems!

📄 License

MIT License - Use it anywhere, modify anything, zero restrictions. See LICENSE.


Stop debugging AI failures. Start shipping reliable agents.

DiscordGitHub

If Shannon saves you time or money, let us know! We love success stories.
Twitter/X: @ShannonAgents

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for Shannon

Similar Open Source Tools

For similar tasks

For similar jobs