The Problem
Enterprises that deploy autonomous LLM agents at scale hit three recurring blockers: unpredictable run‑time failures, runaway token costs, and lack of auditability. Without built‑in budgeting, tracing, and sandboxing, a single mis‑behaving agent can explode budgets or expose sensitive data.
What This Does
Shannon supplies a production‑ready orchestration layer that runs agents inside WASI sandboxes, enforces per‑task token limits, and records every step to a Prometheus‑compatible metrics store. The core server lives in the Docker compose stack (deploy/compose/docker-compose.yml) and is driven by Temporal‑style workflows defined in config/workflows/.
The Python SDK (clients/python/src/shannon/cli.py, client.py) offers a thin wrapper around the REST API, while the desktop UI (desktop/app/...) visualises live event streams (desktop/components/radar/). Configuration files such as config/agent.yaml, config/models.yaml, and OPA policies (config/opa/policies/.rego) let operators tune model selection, security rules, and token budgets without code changes.
How To Use It
Setup
Clone and enter repo git clone https://github.com/Kocoro-lab/Shannon.git cd Shannon Copy example env and insert your keys cp .env.example .env # keys: OPENAIAPIKEY, ANTHROPICAPIKEY, etc. Start the stack (Docker Compose pulls images defined in deploy/compose/docker-compose.yml and grafana/prometheus overlay) docker compose -f deploy/compose/docker-compose.yml up -d
If you need to rebuild the desktop app:
cd desktop npm ci # uses package-lock.json npm run dev # or npm run build && npm start for production
Configuration
API keys are read from the .env file (refer to the README “Required API Keys”). Agent behaviour (token caps, model fallback) lives in config/agent.yaml. OPA security rules are in config/opa/policies/*.rego and are automatically loaded by the server at start‑up.
Running
REST API – Submit a task with curl (see README). Python SDK – Example from clients/python/examples/simpletask.py:
from shannon import ShannonClient
with ShannonClient(baseurl="http://localhost:8080") as client: task = client.submit(query="Summarize Q3 earnings", sessionid="demo") print(task.result()) Desktop UI – Open http://localhost:3000 after npm run dev; the radar component streams events from the backend.
Real‑World Use
A data‑science platform can embed Shannon to run ad‑hoc research agents. A nightly job posts a task via the Python SDK, receives a streamed SSE feed, and stores the final summary in the platform’s knowledge base. The OPA policy config/opa/policies/teams/data-science/policy.rego can restrict the agent to only use approved internal LLM endpoints, ensuring compliance.
summary = client.submit( query="Generate a risk assessment for the new product launch", sessionid="risk-prod" ).wait() storeinkb(summary, tag="risk")
Code Health & Issues
Severity Low – Missing Go source – README badges reference Go (v1.22+) but the repo contains no .go files; build scripts may be absent. Severity Medium – Python SDK lacks type hints – Files in clients/python/src/shannon/ are pure Python; static analysis will be limited. Severity Low – OPA policy coverage – Policies exist, but no test suite validates them (config/opa has no corresponding tests). Severity Low – Secrets in repo – No API keys are committed, but the .env.example may encourage developers to paste keys directly; recommend secret management via Docker secrets or Vault. Severity Low – CI present – GitHub Actions workflows (.github/workflows/ci.yml) run tests, and a license file is included, indicating basic SDLC hygiene. Severity Low – Tests – 14 test files across Python SDK and integration (clients/python/tests/) provide coverage for core client logic.
Overall the repository shows a coherent layout, versioned config, and automated CI. No obvious build‑breakers are detected.
The Bottom Line
Shannon delivers a ready‑to‑run stack for secure, cost‑controlled LLM agents, with a usable Python SDK and a visual desktop monitor. It’s well‑structured and CI‑backed, but the missing Go component and limited type safety in Python suggest a modest integration effort for teams that need strict static guarantees. Ideal for medium‑to‑large organizations that require observability, sandboxing, and policy enforcement around AI agents.