W-Agent

English | 简体中文

面向本地开发者的开放、可组合 Python Agent 框架。自由装配模型、工具、单 Agent 循环、Workflow、知识库和状态存储；既可嵌入自己的应用，也可使用 CLI / TUI。不是托管平台，也不绑定固定 Harness。

本文面向 2.0.0，要求 Python 3.11+。版本是否已发布可安装，以 PyPI 版本页为准。基本交付范围和候选验收门禁见基础清单 B01–B12；增强项后续推进，不再新增 alpha。源码测试、制品安装、线上发布与真实服务验收是不同状态。

从一个完整的小例子开始

在自己的虚拟环境与同版本源码根目录：

python -m pip install -e .
python -m examples.basic_development support
python -m examples.basic_development coding

两个示例默认离线，实际完成“模板 → 注册工具 → 权限检查 → 工具结果 → 最终输出”。客服查询带来源的本地样例知识；编码读取宿主提供的源文本，不执行或修改代码。确定性模型替身用于验证组合，不代表真实模型质量。

基础开发教程提供完整代码、模型替换和资源关闭规则。examples 是源码资产，不是 wheel 模块；wheel 用户请从同版本源码复制 basic_development.py 到自己的项目，再运行 python basic_development.py support。

本地候选验收期间，制品生成后可安装实际 wheel，例如：

python -m pip install ./dist/wagent_framework-2.0.0-py3-none-any.whl

按需安装可选依赖，例如源码环境的 python -m pip install -e ".[models,tui,knowledge-documents]"。安装会访问配置的软件源，不等于授权模型调用。不要用未固定版本的线上安装推断已获得本文对应代码。

基础能力

设计边界

• 通过公开协议组合，内置实现可替换；配置引用不自动导入代码或授予权限。
• 模型调用、工厂加载、文件读取、Embedding、远端写入和逐调用审批分别授权。模板提示词不是权限控制。
• 沙箱不可用时失败关闭，不静默降级到宿主执行。普通 Python 工具和插件本身不是沙箱。
• 恢复只覆盖文档明确支持的边界；副作用结果未知时不自动重放。未知用量/费用不表示为零。
• 不提供多租户、组织或云计费控制面，不自动执行分享码中的第三方代码。

文档与下一步

• 基础开发教程 · 使用指南 · 完整文档索引
• 架构 · 开发扩展 · 公共 API
• 本地 Runtime · 知识同步入口 · CLI/TUI
• 2.0.0 范围与验证说明 · 1.x 迁移 · 历史 a9 发布说明 · 验收记录
• 路线图：Implemented 表示实现存在；Experimental 仍有限制；Planned 是计划，Reserved 是保留设计，不能当成已实现；Deprecated 仅为迁移保留。

语义分块、归档 GC、跨库原子事务、高级远端恢复、多 Agent/分布式编排等不扩张本次基础发布范围。定向测试与本机 Docker 实测不代表所有外部服务、系统或生产场景通过验收，具体证据以对应记录为准。

许可证

MIT