How kocoro-lab/shannon works
Shannon is a production multi-agent platform: clients submit tasks through a Go gateway, which routes them into Temporal-backed orchestration and agent execution; results and execution events return to clients. The workflow includes complexity/decomposition routing, strategy-specific execution, tool/LLM calls, and result synthesis. Major documented branches include research, swarm, approval, budgets, sessions, schedules, and streaming. Paths for unsampled capabilities use exact enclosing directories; wiring is included only where the README or sampled source supports it.
Main entry points: orchestrator_router.go Workflow router · manager.go Event streaming · lib.rs Agent core · registry.py Agent loop and tools
Components 24
Client access
- SDK and desktop
clients/python/src/shannon/client.py - Desktop interface
desktop/app/(app)/runs/page.tsx
Gateway and control
- Go gateway
go/orchestrator/cmd/gateway/main.go - Task API
go/orchestrator/cmd/gateway/internal/handlers/task.go - Workflow router
go/orchestrator/internal/workflows/orchestrator_router.go - Execution strategies
go/orchestrator/internal/workflows/strategies - Research workflow
go/orchestrator/internal/workflows/strategies/research.go - Swarm workflow
go/orchestrator/internal/workflows/swarm_workflow.go
Agent execution
- Agent core
rust/agent-core/src/lib.rs - LLM service API
python/llm-service/llm_service/api/agent.py - Agent loop and tools
python/llm-service/llm_service/tools/registry.py - Provider manager
python/llm-service/llm_provider/manager.py - Browser automation
python/playwright-service/app.py
State and governance
- Event streaming
go/orchestrator/internal/streaming/manager.go - Session continuity
go/orchestrator/internal/session/manager.go - Token budgets
go/orchestrator/internal/budget/manager.go - Policy and approvals
go/orchestrator/internal/policy/engine.go - Scheduled tasks
go/orchestrator/internal/schedules/manager.go
External services
- PostgreSQL
go/orchestrator/internal/db/client.go - Redis
go/orchestrator/internal/streaming/manager.go - Temporal
- LLM providers
- Tool services
python/llm-service/llm_service/tools/builtin
Other components
- Task user
Connections 30
- Task user → SDK and desktop: submits task
- Task user → Desktop interface: submits task
- SDK and desktop → Go gateway: calls REST
- Desktop interface → Go gateway: calls API
- Go gateway → Task API: dispatches request
- Task API → Workflow router: starts workflow
- Workflow router → Execution strategies: routes task
- Workflow router → Research workflow: routes research
- Workflow router → Swarm workflow: routes swarm
- Execution strategies → Agent core: executes agents
- Research workflow → Agent core: runs research
- Swarm workflow → Agent core: coordinates agents
- Agent core → LLM service API: requests inference
- LLM service API → Agent loop and tools: runs agent
- Agent loop and tools → Provider manager: requests completion
- Provider manager → LLM providers: calls provider
- Agent loop and tools → Tool services: invokes tools
- Tool services → Browser automation: uses browser
- Workflow router → Temporal: runs workflows
- Workflow router → Token budgets: tracks budget
- Workflow router → Policy and approvals: checks policy
- Workflow router → Session continuity: uses session
- Workflow router → Event streaming: emits events
- Event streaming → Redis: publishes events
- Event streaming → PostgreSQL: persists events
- Scheduled tasks → Temporal: creates schedules
- Scheduled tasks → PostgreSQL: persists schedules
- Session continuity → Redis: stores sessions
- Event streaming → SDK and desktop: streams events
- Event streaming → Desktop interface: streams events