Metadata-Version: 2.4
Name: wagent-framework
Version: 2.0.0
Summary: Open, composable Python framework for building agents
Home-page: https://github.com/LuckyStar2456/W-Agent-FrameWork
Author: LuckyStar2456
Author-email: lucky_star_2456@example.com
License: MIT
Project-URL: Bug Reports, https://github.com/LuckyStar2456/W-Agent-FrameWork/issues
Project-URL: Source, https://github.com/LuckyStar2456/W-Agent-FrameWork
Keywords: agent framework AOP IOC sandbox
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic
Requires-Dist: structlog
Requires-Dist: cryptography
Requires-Dist: msgpack
Requires-Dist: zstandard
Requires-Dist: pyjwt
Requires-Dist: asgiref
Requires-Dist: redis
Requires-Dist: packaging>=23
Requires-Dist: pyyaml>=6
Requires-Dist: typer<1,>=0.12
Requires-Dist: rich<15,>=13
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == "fastapi"
Requires-Dist: uvicorn; extra == "fastapi"
Provides-Extra: langchain
Requires-Dist: langchain; extra == "langchain"
Provides-Extra: models
Requires-Dist: httpx<1,>=0.27; extra == "models"
Provides-Extra: mcp
Requires-Dist: httpx<1,>=0.27; extra == "mcp"
Provides-Extra: tui
Requires-Dist: textual<9,>=0.70; extra == "tui"
Provides-Extra: media-preview
Requires-Dist: Pillow<13,>=12; extra == "media-preview"
Provides-Extra: knowledge-documents
Requires-Dist: pypdf<7,>=6; extra == "knowledge-documents"
Requires-Dist: python-docx<2,>=1.2; extra == "knowledge-documents"
Requires-Dist: openpyxl<4,>=3.1; extra == "knowledge-documents"
Requires-Dist: python-pptx<2,>=1; extra == "knowledge-documents"
Provides-Extra: wasm
Requires-Dist: wasmer-sdk<0.2,>=0.1.2; platform_system != "Windows" and extra == "wasm"
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-api; extra == "opentelemetry"
Requires-Dist: opentelemetry-sdk; extra == "opentelemetry"
Requires-Dist: opentelemetry-exporter-otlp; extra == "opentelemetry"
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-asyncio; extra == "testing"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# W-Agent

[English](./README_EN.md) | 简体中文

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

本文面向 **2.0.0**，要求 Python **3.11+**。版本是否已发布可安装，以 [PyPI 版本页](https://pypi.org/project/wagent-framework/2.0.0/)为准。基本交付范围和候选验收门禁见[基础清单 B01–B12](./docs/stable-release-baseline.md)；增强项后续推进，不再新增 alpha。源码测试、制品安装、线上发布与真实服务验收是不同状态。

## 从一个完整的小例子开始

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

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

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

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

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

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

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

## 基础能力

| 模块 | 当前路径 |
| --- | --- |
| 模型与路由 | 可替换 Provider、HTTP/厂商模板、事件流、路由与分层探测 |
| Agent 与工具 | ReAct 工具循环、客服/RAG 与编码模板、Python/MCP 工具接入、精确审批、取消和预算 |
| Workflow | DAG、状态图、Python 定义，Agent 双向组合，支持的节点边界暂停恢复 |
| 知识/RAG | 文件与可选 PDF/Office 解析、版本快照、可追溯分块、关键词/BM25/混合检索、显式 Embedding/索引同步与原始归档 |
| 状态与观测 | Run/Session 持久化、事件回放、输入/输出 Token、可配置费用/共享预算、独立服务用量账本 |
| 扩展与执行 | 统一注册表、可撤销插件生命周期、Docker 隔离、独立授权宿主执行、装配分享与本地评测 |
| 开发入口 | Python API、`wagent` CLI（别名 `w-agent`）、Textual TUI、最小 1.x 兼容桥 |

## 设计边界

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

## 文档与下一步

- [基础开发教程](./docs/basic-development.md) · [使用指南](./docs/guide.md) · [完整文档索引](./docs/README.md)
- [架构](./docs/architecture.md) · [开发扩展](./docs/developer.md) · [公共 API](./docs/api.md)
- [本地 Runtime](./docs/local-runtime.md) · [知识同步入口](./docs/knowledge-sync-entries.md) · [CLI/TUI](./docs/tui.md)
- [2.0.0 范围与验证说明](./docs/releases/2.0.0.md) · [1.x 迁移](./docs/migration-1x.md) · [历史 a9 发布说明](./docs/releases/2.0.0a9.md) · [验收记录](./docs/README.md#验证与历史)
- [路线图](./docs/roadmap.md)：`Implemented` 表示实现存在；`Experimental` 仍有限制；`Planned` 是计划，`Reserved` 是保留设计，不能当成已实现；`Deprecated` 仅为迁移保留。

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

## 许可证

[MIT](./LICENSE)
