Shannon — Production AI Agents That Actually Work

The Problem

AI agent deployments at scale typically face three interlocking problems: costs spiral without deterministic budgets, failures go undetected until users report them, and security boundaries between tenants or execution environments are porous. This repository addresses those pain points with a multi-agent orchestration framework designed for production infrastructure.

What This Does

Shannon is a portfolio of 9 self-contained projects rather than a single monolithic codebase. The largest projects by file count are:

  • go/ (282 files, 270 code files) — orchestration and gateway services
  • python/ (142 files, 135 code files) — LLM service layer, tooling, and provider management
  • desktop/ (141 files, 60 code files, 7 data files) — Tauri-based native desktop application
  • rust/ (45 files, 36 code files) — systems-level components
  • clients/ (29 files, 21 code files) — Python SDK and example integrations

The Python LLM service is the most active import hub: python/llm-service/llm_service/tools/base.py has 15 importers and 27 importees with instability 0.96, meaning small changes there ripple widely. Similarly, python/llm-service/llm_service/tools/builtin/web_fetch.py at 1,866 lines is the single largest cognitive-load hotspot — max indentation depth 7, oversized by any standard. Duplicated 6-line blocks appear 956 times across 168 files, particularly in clients/python/examples/ and clients/python/src/shannon/__init__.py.

How It Is Wired

Execution flow depends on the deployment target:

  • Python SDK: clients/python/src/shannon/cli.py is the entry point, routing through clients/python/src/shannon/client.py to the REST gateway
  • Desktop app: desktop/src-tauri/src/main.rs and desktop/src-tauri/src/lib.rs initialize the Tauri app, which connects to the local gateway via Tauri commands
  • Go gateway: go/orchestrator/cmd/gateway/ hosts the HTTP server; the Dockerfile at go/orchestrator/cmd/gateway/Dockerfile builds the runtime image
  • Import graph: 223 internal modules with 126 import edges and zero circular dependencies. The Python LLM provider manager (python/llm-service/llm_provider/manager) has instability 1.0 — it imports 7 providers but nothing imports it back, making it a sink rather than a hub

What leaves the process: outbound HTTP to LLM providers (OpenAI, Anthropic, Google, DeepSeek), optional web fetch via Serpapi/Firecrawl keys, and WebSocket/event streaming for real-time task tracking. Database state is managed through the orchestrator’s Temporal-style workflow logs, though the exact schema is not mapped in this analysis.

How To Use It

Setup

The repository includes a convenience install script referenced in the README:

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

This pulls config, prompts for API keys, and starts Docker Compose services. Required env vars are documented in .env.example and include at minimum OPENAI_API_KEY or ANTHROPIC_API_KEY. Optional keys for web search (SERPAPI_API_KEY) and web fetch (FIRECRAWL_API_KEY) are noted there as well.

Running the 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-session"
  }'

# Stream events
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123"

# Get final result
curl "http://localhost:8080/api/v1/tasks/task-dev-123"

Python SDK

from shannon import ShannonClient

with ShannonClient(base_url="http://localhost:8080") as client:
    handl

Configuration is read from .env in the client working directory; the SDK pins the base URL and forwards all headers to the gateway.

Real-World Use

A midsize analytics firm could use Shannon to replace a brittle homegrown agent runner. The Python SDK submits extraction tasks via the REST API; the gateway orchestrates a multi-step workflow — web search, content fetch, LLM extraction, and result aggregation — with token budgets enforced per step. If the primary LLM provider times out, the system falls back to a secondary model configured in config/models.yaml. Real-time SSE streaming lets the UI show step-by-step execution, and the OPA policies in config/opa/policies/ enforce tenant-level data access limits. Deployment is Docker Compose (deploy/compose/docker-compose.yml) with Prometheus and Grafana metrics endpoints for cost and latency tracking.

Code Health & Issues

Static analysis of 603 code files produced 252 findings (69 high, 178 medium, 5 low). The most severe items from the code health audit:

  • [CRITICAL] Vulnerable dependencies pinned in manifests: tauri-plugin-shell@2 CVE-2025-31477, next@16.0.3 GHSA-9qr9-h5gf-34mp, and 33 more. The vulnerable code installs as-is; upgrading to the fixed versions and committing the lockfile is required.
  • [CRITICAL] Secret exfiltration risk: ANTHROPIC_API_KEY is committed in .github/workflows/claude-code-review.yml, a workflow triggered by pull requests that holds a publish token.
  • [HIGH] CORS wildcard with credentials enabled: allow_origins=["*"] in python/llm-service/main.py together with credentials allows any internet site to make authenticated requests on behalf of logged-in visitors.
  • [HIGH] Dependencies unpinned: clients/python/pyproject.toml has no lockfile, so transitive code differences between test and production environments are unguarded.
  • [HIGH] GitHub Actions not pinned to commit SHAs: dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, and others can be silently updated by maintainers, executing code with repository tokens.
  • [MEDIUM] No Dependabot or Renovate configured across 8 manifests — published advisories go unpatched until manual audit.
  • [MEDIUM] Container base images mutable: golang:1.24-alpine and alpine:3.19 in go/orchestrator/Dockerfile have no digest pinning.

The Bottom Line

Shannon is a functioning, production-oriented multi-agent framework with real orchestration primitives, Temporal-style workflow replay, and multi-provider fallback — valuable for teams needing observable, bounded AI agent execution. The codebase shows its age and scale in duplicated logic, oversized files, and critical dependency vulnerabilities that must be addressed before it can be relied upon in a hardened environment. It is best suited for organizations that can maintain their own dependency hygiene and are comfortable integrating via the REST SDK rather than requiring a fully opinionated opinionated UI.

Bottom line: Strong orchestration core let down by dependency security and code hygiene issues that should be resolved before production adoption.