# Shannon > Shannon is a production-grade AI agent orchestration platform built with Go, Rust, and Python. It provides durable workflows via Temporal, secure code execution via WASI sandboxing, multi-provider LLM support, and cost control with 85-95% token savings. Shannon orchestrates AI agents through a distributed microservices architecture: - **Gateway** (Go): REST API, authentication, SSE streaming - **Orchestrator** (Go + Temporal): Workflow coordination, cognitive patterns (CoT, ToT, ReAct), budget enforcement - **Agent Core** (Rust): WASI sandboxing, tool execution, circuit breakers - **LLM Service** (Python): Multi-provider gateway (OpenAI, Anthropic, Google, etc.), MCP tool integration **Key Features**: Temporal workflows, WASI Python sandbox, intelligent caching, 85-95% token savings, MCP tool protocol, vendor adapters, Skills API **Languages Available**: English | [中文](https://docs.shannon.run/cn) | [日本語](https://docs.shannon.run/ja) ## Documentation - [Quick Start](https://docs.shannon.run/en/quickstart): Get Shannon running in minutes - [Installation](https://docs.shannon.run/en/quickstart/installation): System requirements and setup - [Configuration](https://docs.shannon.run/en/quickstart/configuration): Environment variables and settings ## Core Concepts - [Agents](https://docs.shannon.run/en/quickstart/concepts/agents): AI agents with roles and capabilities - [Workflows](https://docs.shannon.run/en/quickstart/concepts/workflows): Temporal-based durable workflows - [Cost Control](https://docs.shannon.run/en/quickstart/concepts/cost-control): Budget management and token limits - [Streaming](https://docs.shannon.run/en/quickstart/concepts/streaming): Real-time SSE event streaming ## API Reference - [API Overview](https://docs.shannon.run/en/api/overview): REST and gRPC API introduction - [Authentication](https://docs.shannon.run/en/api/authentication): API key authentication (skip with GATEWAY_SKIP_AUTH=1) - [Submit Task](https://docs.shannon.run/en/api/rest/submit-task): POST /api/v1/tasks - Start agent workflow - [Task Status](https://docs.shannon.run/en/api/rest/get-status): GET /api/v1/tasks/{id} - Check execution status - [List Tasks](https://docs.shannon.run/en/api/rest/list-tasks): GET /api/v1/tasks - List all tasks - [Streaming](https://docs.shannon.run/en/api/rest/streaming): SSE endpoint for real-time events - [Event Types](https://docs.shannon.run/en/api/event-types): SSE event schema reference - [Skills API](https://docs.shannon.run/en/api/rest/skills): POST /api/v1/skills - Dynamic skill execution - [Channels API](https://docs.shannon.run/en/api/rest/channels): Channel management for multi-tenant messaging - [Tools API](https://docs.shannon.run/en/api/rest/tools): Tool execution and management endpoints - [Daemon WebSocket](https://docs.shannon.run/en/api/rest/daemon-websocket): Persistent WebSocket connection for real-time daemon communication ## SDKs - [Python SDK Installation](https://docs.shannon.run/en/sdk/python/installation): pip install shannon-sdk - [Python SDK Quickstart](https://docs.shannon.run/en/sdk/python/quickstart): Basic usage examples - [CLI Reference](https://docs.shannon.run/en/sdk/python/cli): Complete CLI reference - all 26 commands with flags and examples - [Streaming](https://docs.shannon.run/en/sdk/python/streaming): SSE and WebSocket event streaming - [Async Usage](https://docs.shannon.run/en/sdk/python/async-usage): AsyncShannonClient for concurrent tasks ## Deployment - [Docker Compose](https://docs.shannon.run/en/deployment/docker-compose): Local development setup - [Kubernetes](https://docs.shannon.run/en/deployment/kubernetes): Production K8s deployment - [AWS](https://docs.shannon.run/en/deployment/aws): EKS deployment guide - [Environment Variables](https://docs.shannon.run/en/deployment/environment-variables): Configuration reference ## Architecture - [System Overview](https://docs.shannon.run/en/architecture/overview): Component architecture and data flow - [Components](https://docs.shannon.run/en/architecture/components): Service deep dive (Gateway, Orchestrator, Agent Core, LLM Service) - [Temporal Workflows](https://docs.shannon.run/en/architecture/temporal-workflows): Durable workflow patterns and retry logic - [Tool Execution](https://docs.shannon.run/en/architecture/tool-execution): WASI sandbox architecture and security - [LLM Caching](https://docs.shannon.run/en/architecture/llm-caching): Intelligent semantic caching strategy - [Vector Memory](https://docs.shannon.run/en/architecture/vector-memory): Qdrant-based long-term memory ## Tutorials - [Custom Tools](https://docs.shannon.run/en/tutorials/custom-tools): Building custom agent tools with Python - [OpenAPI Tools](https://docs.shannon.run/en/tutorials/openapi-tools): Auto-generate tools from OpenAPI specs - [Vendor Adapters](https://docs.shannon.run/en/tutorials/vendor-adapters): Request/response transformations for custom integrations - [Research Assistant](https://docs.shannon.run/en/tutorials/research-assistant): Build a multi-agent research system - [Model Selection](https://docs.shannon.run/en/tutorials/model-selection): Choose optimal LLMs per task - [Extending Shannon](https://docs.shannon.run/en/tutorials/extending-shannon): Custom roles, tools, and workflows ## Quick Start Commands ```bash # Clone and setup git clone https://github.com/Kocoro-lab/Shannon.git cd Shannon make setup echo "OPENAI_API_KEY=sk-your-key" >> .env ./scripts/setup_python_wasi.sh # Run locally make dev # Submit a task via curl curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query": "Analyze the benefits of microservices architecture"}' ``` ## Shannon CLI Quick Reference Install: `pip install shannon-sdk` (provides the `shannon` command) Connect to local: `shannon --base-url http://localhost:8080 COMMAND` Connect to cloud: `shannon --base-url http://localhost:8080 --api-key YOUR_KEY COMMAND` Or set env vars: `SHANNON_BASE_URL`, `SHANNON_API_KEY`, `SHANNON_BEARER_TOKEN` **Tasks:** ```bash shannon submit "Your query" --wait # submit and wait for result shannon submit "Query" --model-tier small --mode simple --wait # cost-optimized shannon submit "Query" --force-research --research-strategy deep --wait # deep research shannon submit "Query" --swarm --wait # multi-agent swarm shannon submit "Query" --model-override gpt-5-nano-2025-08-07 --provider-override openai --wait shannon status TASK_ID # check task status shannon cancel TASK_ID --reason "reason" # cancel task shannon pause TASK_ID --reason "reason" # pause at checkpoint shannon resume TASK_ID --reason "reason" # resume paused task shannon control-state TASK_ID # get pause/cancel state ``` **Streaming:** ```bash shannon stream WORKFLOW_ID # stream all events shannon stream WORKFLOW_ID --types LLM_OUTPUT,WORKFLOW_COMPLETED # filter event types ``` **HITL Review:** ```bash shannon review-get WORKFLOW_ID # get review state shannon review-feedback WORKFLOW_ID "feedback message" # submit feedback shannon review-approve WORKFLOW_ID --version N # approve plan shannon approve APPROVAL_ID WORKFLOW_ID --approve --feedback "ok" # approve request shannon approve APPROVAL_ID WORKFLOW_ID --reject --feedback "no" # reject request ``` **Sessions:** ```bash shannon session-list --limit 10 # list sessions shannon session-get SESSION_ID # get session details shannon session-title SESSION_ID "New Title" # update title shannon session-delete SESSION_ID # delete session ``` **Schedules:** ```bash shannon schedule-create "Name" "0 9 * * *" "Query" --timezone Asia/Tokyo # create shannon schedule-list --status ACTIVE # list active schedules shannon schedule-get SCHEDULE_ID # get details shannon schedule-update SCHEDULE_ID --cron "0 10 * * *" --query "new query" # update shannon schedule-pause SCHEDULE_ID --reason "reason" # pause shannon schedule-resume SCHEDULE_ID # resume shannon schedule-runs SCHEDULE_ID --page 1 # execution history shannon schedule-delete SCHEDULE_ID # delete ``` **Skills:** ```bash shannon skills-list --category research # list skills shannon skill-get SKILL_NAME # get skill details shannon skill-versions SKILL_NAME # list versions ``` Full CLI reference: [https://docs.shannon.run/en/sdk/python/cli](https://docs.shannon.run/en/sdk/python/cli) ## Troubleshooting - [Common Issues](https://docs.shannon.run/en/quickstart/troubleshooting): Solutions for setup and runtime errors - Ports: Gateway (8080), Orchestrator (50052), Agent Core (50051), LLM Service (8000) - Authentication: Set `GATEWAY_SKIP_AUTH=1` for development - WASI Setup: Run `./scripts/setup_python_wasi.sh` for Python sandbox ## Links - [GitHub Repository](https://github.com/Kocoro-lab/Shannon) - [Documentation](https://docs.shannon.run) - [Twitter](https://x.com/shannon_agents) - [Company](https://kocoro.ai) --- **For AI Agents**: This documentation covers Shannon's architecture, API reference, deployment guides, and tutorials. The platform supports custom tool development via Python, OpenAPI specs, and MCP protocol. All code examples are production-ready. For questions about specific components, see the Architecture section. For integration patterns, see Tutorials.