Lumen — Observability and Reliability for Agents
Replay · Crash Recovery · Cost Tracking — three tools in one for agents
Prerequisites
- Preferred: Python 3.9+ (
pip install lumen-ai) - Optional CLI: build
lumen-clifrom source with Rust 1.93+ - A Lurus API KeyAPI KeyA secret credential for accessing the API, much like a password. Each Key can have its own quota and permissions.Learn more → (how to get one)
What is Lumen?
Lumen is an all-in-one reliability toolkit for AI Agent developers — Replay (zero-cost replays) + Crash Recovery (microsecond-level crash recoveryCheckpointA complete in-memory state snapshot written to disk. On crash recovery, the WAL is replayed starting from the most recent Checkpoint.) + Cost Tracking (real-time cost tracking). Delivery forms: Python SDK first (pip install lumen-ai, the top choice for LangGraph/Agents) + Rust engine (lumen-core performance foundation) + optional CLI (lumen-cli v0.1.0). Philosophy: Illuminate your AI agents. Never lose a run. Never burn tokens blindly.
pip install lumen-ai
from lumen_ai import LumenTracer, LumenCheckpointer, CostTracker
# 三行代码接入 — LangGraph 原生集成
graph = workflow.compile(
checkpointer=LumenCheckpointer(), # 崩溃恢复
callbacks=[LumenTracer()] # 执行追踪 + 成本追踪
)Powered by the underlying Rust engine (lumen-core), the Python SDK provides a friendly interface that connects the Kova Agent engine with the Python ecosystem.
All-in-one reliability
Replay, recovery, cost — all ready with a single integration.
Replay — zero-cost deterministic replay
Replay any execution from a trace JSON without calling the LLM and without spending money, and start from a specific step to pinpoint issues precisely. lumen replay TRACE_ID (full) / --from 5 (from step 5).
Crash Recovery — microsecond-level crash recovery
A complete implementation of LangGraph CheckpointSaver, a drop-in replacement for the native SQLite/Redis Checkpointer. Two-tier memory + disk, atomic writes, recovery via engine-level WAL replay, with zero external service dependencies.
Cost Tracking — real-time cost tracking
Built-in pricing tables for 30+ models (Claude / GPT-4o / Gemini / Llama / DeepSeek), with estimates even when the LLM does not return costs. Automatically alerts when a single call exceeds 2x the average. lumen cost --last 24h / lumen traces.
More features
| Feature | Description |
|---|---|
| Agent management | Create, start, stop, and delete Agents |
| Workflow debugging | Run workflows locally and debug step by step |
| Log viewing | View Agent execution logs in real time |
| Deployment | Deploy Agents to a Kova cloud instance |
| MCP management | Install and configure MCP tool services |
| Interactive REPL | Chat with the Agent directly in the terminal |
Installation
pip install lumen-ai # Python SDK（推荐）
curl -fsSL https://get.lurus.cn/lumen | sh # CLI macOS/Linux
# Windows (PowerShell): irm https://get.lurus.cn/lumen.ps1 | iex
# 从源码（Rust 1.93+，首次编译约 2-3 分钟）：
git clone https://github.com/hanmahong5-arch/lumen.git && cd lumen && cargo build --release
# 二进制在 target/release/lumenVerify: lumen --version (→ lumen 0.1.0); lumen doctor (checks Lurus API connected / Kova optional).
Quick start
# 初始化项目（结构: agent.toml / prompts/system.md / tools/search.yaml / workflows/main.yaml）
lumen init my-agent && cd my-agent
# 配置 API Key
lumen auth login # 浏览器登录授权自动配置
lumen config set api_key sk-your-lurus-key # 或直接设置
# 本地运行 Agent
lumen run --interactive # 交互模式
lumen run "分析这段代码的性能问题" --file ./main.py
lumen run "翻译这段文本" --model gpt-4o # 指定模型
# 工作流调试
lumen workflow run main --input topic="AI trends"
lumen workflow run main --step-by-step # 逐步调试（每步暂停）
lumen workflow history main --last # 上次运行结果Common commands
# Agent 管理
lumen agent list / create researcher / info researcher / logs researcher / delete researcher
# MCP 工具
lumen mcp list / install github / test github / remove github
# 部署
lumen deploy --target kova # 或 --target docker
lumen deploy status
# 配置
lumen config list / set api_key xxx / get api_keyConfiguration file
agent.toml is the core configuration of an Agent project:
[agent]
name = "my-researcher"
model = "deepseek-chat"
max_iterations = 20
[agent.llm]
base_url = "https://api.lurus.cn/v1"
temperature = 0.7
max_tokens = 4096
[tools]
builtin = ["web_search", "file_read", "file_write"]
[[tools.mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
[deploy]
target = "kova"Relationship with Kova
Developer command-line tool — local development, debugging, and deployment. A lightweight runtime that runs out of the box with lumen run.
Agent runtime engine — durable execution, WAL, and cluster management. After lumen deploy, you gain full durability and cluster capabilities.
For local development, use the lightweight runtime (lumen run); after deploying to Kova (lumen deploy), you gain full durability and cluster capabilities.
Comparison with other solutions
Comparison
| 维度 | Lumen | Temporal | LangGraph Checkpointer | Conductor |
|---|---|---|---|---|
| Replay | Zero-cost LLM replay | Event replay | Partial | Workflow replay |
| Integration cost | 3 lines of code | Worker + SDK | Configuration | Worker |
| Cost tracking | Built-in | None | None | None |