Repository navigation
V1 Operations and Migration
简体中文 | English
适用版本:LightAgent v1.0.0。普通调用可保持原样,持久状态和外部集成则要分别验收。不要把当前分支上的改动、PyPI 分发或历史开发记录混为这个标签的能力证明。
基础包的直接依赖是 OpenAI SDK、HTTPX、jsonschema 和 PyYAML。原生 Agent、Python 工具、Skills、核心工作流(LightFlow / LightDAG)、本地 Trace 和内置记忆协议均不要求 extras;没有 skills extra。基础包本身不会安装模型服务。
pip install lightagent
pip install 'lightagent[mcp,langfuse]'
pip install 'lightagent[all]'第一条装基础包;第二条只追加 MCP 和 Langfuse 相关依赖;第三条追加下表全部 SDK。已经装过基础包的环境也可以补装 extra。用 PyPI 的 ==1.0.0 固定版本,或直接从 GitHub 标签安装:
pip install 'lightagent[all]==1.0.0'
python -m pip install 'lightagent[all] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'下表依据 PyPI v1.0.0 和 该标签的包配置。表中的 SDK 都是可选的。
| Extra | Python 依赖 | 何时需要 |
|---|---|---|
mcp |
mcp |
连接 MCP 工具服务器或提供 MCP stdio 服务;Codex 动态工具桥本身不需要它。 |
mem0 |
mem0ai |
使用 Mem0 记忆后端;自定义记忆和 SharedMemoryPool 不需要它。 |
langfuse |
langfuse |
发送 Trace 到 Langfuse;本地 Trace 不需要它。 |
litellm |
litellm |
使用 LiteLLM 模型路由;常规 OpenAI 兼容连接不需要它。 |
oss 或 nos
|
boto3 |
使用对应对象存储工具;两组安装的是同一个 SDK。 |
signing |
cryptography |
验证 Ed25519 Provider 签名。 |
all |
以上 SDK 的合集 | 需要多个集成或准备完整开发环境;生产建议只装实际用到的 extras。 |
all 只安装 Python 依赖,不会启用集成或写入凭据;不会安装 Codex CLI、Docker、浏览器、外部服务或 LightResearch。仍需按所用功能配置服务地址、授权和凭据。
git clone --branch v1.0.0 --depth 1 https://github.com/wanxingai/LightAgent.git
cd LightAgent
python -m pip install -e '.[signing]'
python example/13.runtime_v010.py
python example/14.dynamic_dag.py
python example/15.durable_execution.py
python example/16.jobs_and_history.py
python example/17.signed_providers.py这些示例分别验证本地 RAG、动态 DAG、普通持久任务、子代理及历史重连、签名失效。它们都无需真实模型。其他模型、Mem0、MCP 和浏览器示例分别有额外依赖、外部服务和凭据要求。
- 发布对应的 CI 通过 Python 3.10、3.11、3.12、3.13 以及 MCP 1.12.4、1.30.0、2.3.0。核心矩阵包括基础无 MCP 的安装验证、锁定依赖下的核心套件、构建 wheel 和仓库外安装烟测;并不等于每个可选依赖、OS 或生产服务组合都过了。
- Docker/真实 Worker、长负载、真实 Codex、真实 Mem0 Graph、用户自己的远端 MCP、LightResearch 联合验收要分别看记录,不能把默认跳过算作通过。15 分钟 soak 是有界本地负载,不是 24 小时稳定性保证。
- 干净矩阵在独立容器用
tests/acceptance/clean_matrix.py输出版本、锁、JUnit、wheel 摘要和日志;无 Docker 时可在干净的虚拟环境用tests/acceptance/verify.py,传入已构建的核心 wheel。步骤、约束和产物见 干净环境验收 和 历史验收记录。
-
先区分普通调用和长任务。 现有
run()、arun()、流式、Tools、Hooks、Guardrails、Memory、LightFlow、LightSwarm、LightDAG 的常规入口仍可用。不要用ExecutionService替代所有对话。调整安装时给真正使用的 SDK 补 extras。 -
先停所有写入者再做备份。
HistoryBundle.capture(source, backup, quiescent=True)将受控本地历史备份到新目录;HistoryBundle.restore(backup, candidate)恢复到另一个新目录。保留原始历史,不在原目录覆盖数据库。SQLite 一致性备份、权限与哈希校验不构成不信任输入导入机制。 -
在副本验证。 核对 Job、Subagent、Session、消息回执、预算和产物;应用重新绑定可信实例和执行配置。历史未建立完整性链时记录状态,明确核对后才用
SqliteSessionStore.anchor_legacy(...)建锚。配置、权限、路径或历史摘要不一致时停止,不能手改摘要假装兼容。 - 处理未知结果。 读取外部回执,区分已处理、未处理和不明状态。不明任务由宿主显式核对,不能批量自动重放已经可能发生的副作用。
- 准备回退。 旧版本只读回退副本应从迁移前备份恢复,不能直接写入已加锚的新副本。真实操作前按 Job 与历史迁移 演练冻结旧 wheel 的恢复。
研究循环、研究聊天、报告搜索、研究评估和参考面板属于单独的 LightResearch,不是核心包的一部分。旧 mode="persistent" 保留研究语义,宿主安装兼容 LightResearch 后调用 LightResearch.enable_legacy_api() 才启用;普通长任务直接用 ExecutionService。仅支持旧 LightAgent 预发布版本的 LightResearch wheel 不能直接用于 1.0.0。
联合验收明确传 --research-source ../LightResearch 或 --research-wheel /path/to/lightresearch.whl,不会自动搜索同级目录。生产服务自行提供鉴权、租户隔离、后台管理、监控和 UI;核心没有分布式调度、生产界面或 exactly-once 外部副作用保证。可参考 研究迁移说明 和 服务模板。
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing