Metadata-Version: 2.4
Name: wagent-framework
Version: 2.0.0a9
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 :: 3 - Alpha
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: 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) | 简体中文

a9 新增共享 Token/费用预留、实耗结算与 Provider 包装器，以及内存/SQLite 预算控制器，可让摘要和主 Agent 显式共用预算并持久化票据；另有宿主确认的未知/遗留预留对账及不可覆盖回执。Runtime/Provider 支持具名绑定；CLI run/run-resume/evaluate/provider-probe 与 TUI 运行/审批恢复/评测/探测支持独立确认的预算工厂和池快照展示。2.0.0a9 Experimental，验证范围见 a9 发布说明。可靠上界、证据与存储边界见[共享预算](./docs/shared-budget.md)。

a9 新增可替换的 SQLite 摘要用量观察器，支持显式初始化、事务内幂等记录和重开读取；2.0.0a9 Experimental，验证范围见 a9 发布说明。见[持久化计量说明](./docs/context-accounting.md)。

W-Agent 是面向本地开发者的 Python 开源 Agent 开发框架，不是托管平台或固定 Harness。核心协议稳定且可扩展，模型、路由、Agent Loop、Workflow、工具、状态、沙箱和界面均可自由装配与替换。

稳定版为 `1.5.2`，本版 Alpha 为 `2.0.0a9`。新增能力为 `Experimental`；验证范围见 [a9 发布说明](./docs/releases/2.0.0a9.md)。Alpha 不代表框架开发完成或所有外部服务已验收。

相比 a7，本版新增：

- 可替换本地检索/抽取式摘要模板、CLI/TUI 独立变换确认，以及 Python 异步历史准备和取消，见 [Session 文档](./docs/sessions.md)。
- 输入 `name/metadata` 的独立发送、记录、历史复用与只读披露，默认关闭，见[本地 Runtime](./docs/local-runtime.md)。
- TUI Replay 受信缓存导入续读与显式新文件导出，与 CLI 缓存互通，见 [TUI 文档](./docs/tui.md)。
- 独立 Agent Run 的可计量模型摘要，以及摘要/主 Run Token 和分组费用的显式归集，见[用量归集](./docs/context-accounting.md)。这不是共享调用前硬预算。

保留 a7 媒体输入/记录/回放、类型化工具续执行、Workflow 双层审批、Run Token/费用预算、插件安装、大字符/颜文字 TUI 和 1.x 工程底座。剩余实现项与保留设计见[路线图](./docs/roadmap.md)。

## 状态标记

| 标记 | 含义 |
|---|---|
| `Implemented` | 源码已经存在，并有相应测试或可执行入口 |
| `Planned` | 已决定实现，已进入明确路线图 |
| `Reserved` | 协议或扩展点会保留，但尚未承诺实现版本 |
| `Experimental` | 可以试用，但接口与行为可能变化 |
| `Deprecated` | 仅为迁移保留，不再扩展 |

## 项目定位

W-Agent 遵循以下原则：

- 核心协议稳定且可扩展，具体策略全部可替换。
- 内置实现只使用公开扩展接口，不享有私有能力。
- 显式 Python 装配、装饰器、配置文件和 Python entry point 最终进入同一个注册表。
- Agent Loop 与 Workflow 互通但不强行合并。
- 本地开发优先，不内置租户、计费或托管控制面。
- 默认执行不可信代码时使用沙箱；宿主机执行必须由用户明确授权。
- 已实现、计划实现和仅保留设计的能力必须在文档中区分。

## 当前能力

以下能力在 1.5.2 源码中为 `Implemented`：

- `BaseAgent.arun()` 基础抽象。
- IOC 容器、组件扫描、生命周期与依赖注入。
- AOP、重试、断路器、超时和舱壁隔离。
- 动态配置、事件总线、健康检查、日志、指标和链路追踪。
- Wasm 与 nsjail 技能沙箱，后端不可用时失败关闭。
- Skill 加载、签名校验、MCP JWT 认证、Redis 分布式锁。
- LangChain 工具适配、FastAPI 示例集成和测试辅助设施。

以下 Phase 1 能力在`2.0.0a4` 源码中为 `Implemented`：

- `PluginSpec`、装饰器、YAML 引用与 Python entry point 发现。
- 统一、版本感知、分作用域的能力注册表与不可变快照。
- 插件依赖解析、生命周期、失败回滚、级联卸载和可撤销注册。
- `Application → Workspace → Session → Agent → Run → Step` 作用域。
- `publish`、`first`、`serial` 和 `pipeline` 事件模式。

以下 Phase 2A 能力在当前源码中也为 `Implemented`：

- Provider 中立的消息、能力、请求、响应和严格流事件协议。
- 统一 `ModelRegistry`、可替换 `ModelProvider` 和协作式取消令牌。
- 可解释的 Python 加权路由与安全 YAML 路由规则。
- L1 端点可达性嗅探、L2/L3 Provider 检查、显式授权的 L4/L5 主动探测、缓存和周期调度器。
- 严格配置化 Provider 的独立无副作用装配，以及 CLI/TUI 安全目录检查与显式授权主动生成探测。
- 可替换传输的 OpenAI-compatible Chat Completions Provider，适用于声明兼容接口的本地或远程服务。
- 可插拔的通用 HTTP 请求映射层与 JSON/SSE/NDJSON 传输。
- Anthropic、Gemini、Ollama、Qwen 原生模板，以及 DeepSeek、GLM、Qwen-compatible、Turbo AI/SIAM.AI 模板注册表。
- 同时支持完整收集和逐事件透传的 `ModelExecutor`；默认单次调用，可显式启用有界重试/故障转移，并记录不含 Prompt 的逐尝试 Token/失败审计。
- 注册即安全探测的 `ModelRegistrationProbeService` 与外部路由健康桥接；直接调用 `ModelRegistry.register()` 仍保持无副作用。
- 工具 Definition/Binding/Registry 分层、Python/HTTP/无 Shell 命令模板、MCP 绑定与 2026-07-28 stdio/Streamable HTTP 客户端、参数校验、权限/逐调用审批、超时/取消和 Prompt-free 审计。
- 可替换 `AgentLoop` 协议与有界单 Agent `ReactAgentLoop`，覆盖模型→工具→结果→模型闭环、显式可选文本增量 RunEvent、调用前可插拔 Token/费用估算与重放包络、实报 Token/费用预算、软阈值事件、JSONL RunEvent/尝试账本记录和审批断点恢复。
- 应用提供的版本化价格表、普通/缓存输入与输出费用计量、失败关闭的 Run 费用预算，以及 Session/Checkpoint/评测和按 Agent 跨 Session 的费用可见性。
- 统一 `WorkflowRegistry`、可替换 `WorkflowEngineProtocol` 与 `LocalWorkflowEngine`，支持静态 DAG、状态图、Python 入口、节点事件、取消，以及内存/JSONL 节点边界暂停恢复。
- 统一 `SandboxProvider`/`SandboxRegistry`、Docker/OCI 生命周期后端、显式运行时授权的 `UnsafeLocalSandboxProvider`，以及受工具策略保护的 `sandbox_command_tool()`。
- Agent/Workflow 双向适配器，以及可完全覆盖的客服/RAG 与编码 Agent 模板。
- `CompositionManifest` 的确定性编码、安全预览，以及冲突安全的本地版本和别名管理。
- 本地 Session 创建/列表/归档、JSON 持久化、跨 Run 文本上下文、审批恢复协调，以及不含 Prompt/输出的按 Agent 跨 Session 用量/费用汇总。
- 严格本地 JSON 装配的文本 Agent CLI/TUI 运行入口，使用环境变量凭据引用、逐次调用确认、可见 Token/费用预算与计量。
- 确定性脚本化 Model Provider、显式授权的 JSONL 录制/顺序回放、本地评测运行器、版本化客服/编码套件与脱敏 JSON 报告。

当前 `BaseAgent` 仍是简单的 1.x 抽象；`LegacyAgentAdapter` 已能把它严格桥接为文本 Workflow 节点，新的 ReAct Runtime 独立提供。`2.0.0a4` 已有可替换的离线装配依赖计划、独立 YAML 插件引用的安全预览/确认加载/TUI 卸载、专用 OpenAI Responses/vLLM 差异适配、显式有界的可替换文本流前缀恢复，以及显式调用前费用估算/重放包络；宿主锁目录驱动的 Sandbox 包安装/独立插件加载、MCP 2025 协商、显式有界异步 DAG 并行，以及 Provider 原生游标续传的可替换协议/执行器接线、ReAct 显式装配与调用前费用包络仍在`2.0.0a4`。在线来源发现/自动更新、内置厂商原生游标适配、跨进程续流、富内容界面和嵌套 Workflow 仍为 `Planned` 或 `Reserved`，不能当作现成功能使用。Docker 后端已有模拟 CLI 生命周期测试，但不代表当前机器已安装或启动 Docker；厂商模板经过模拟传输测试，也不代表所有远程型号已经在线验证。

`2.0.0a4`另外新增已持久化 RunEvent 的只读游标分页 API，以及 `wagent run-events` CLI 命令和 TUI Checkpoints 分页入口；默认界面只展示白名单计数、状态和费用摘要，不显示模型正文或工具参数/结果。它不重新执行模型或工具，也不等同于完整的多模态/工具事件回放；Python API 的原始事件仍需应用自行控制读取权限。

`2.0.0a4`还提供独立的 `emit_tool_call_deltas` Agent 开关，把模型工具参数片段作为原始 RunEvent 持久化并交给授权的应用事件订阅者；它默认关闭，也不会随文本增量自动开启。CLI/TUI 的安全投影仍隐藏 Call ID、工具名和参数内容。

已有 `RunEventProjector` 与 `projected_page()`：默认投影移除模型/工具内容，应用可显式替换为自己的 JSON 投影。CLI/TUI 分页直接消费安全投影页；原始 `page()` 保持兼容但仍需调用者控制读取权限。自定义投影器不是安全沙箱。

常见场景可使用默认拒绝的 `FieldPolicyRunEventProjector`，按精确事件类型或 `*` 回退显式允许、固定掩码顶层字段。`2.0.0a4`另有 `NestedFieldRunEventProjector`，通过显式源路径、目标路径与复制/固定掩码动作选择和重命名嵌套对象/数组值；任意计算和业务授权仍由自定义投影器处理。

`2.0.0a4`还新增显式 `emit_output_blocks`：仅在 Agent 主动开启时，`StandardMultimodalEventEncoder` 才把 Provider 无关的图片/音频输出保存为 `MODEL_OUTPUT_BLOCK`。`MultimodalRunEventProjector` 提供 `metadata`、`references`、`content` 三档披露；默认 CLI/TUI 仍不展示 URL 或内联内容。编码器、投影器与外部 Blob 存储策略均可替换。

Gemini 原生模板在`2.0.0a4`另新增可替换的响应 Part Mapper，支持把 `inlineData`/`fileData` 图片和音频输出映射为中立内容块；其余内置厂商的多模态输出映射仍在计划中。

Workflow 在`2.0.0a4`新增可替换的节点调用策略，可显式使用 `ThreadedWorkflowNodeInvoker` 运行同步节点，避免占用事件循环；取消会等待同步调用退出，详见[Workflow 文档](./docs/workflows.md)。

`2.0.0a4`新增 `WorkflowPauseController` 与可替换请求源：应用可按 Run ID 在节点/批边界请求暂停，保存已提交结果后通过原有入口恢复。TUI 已增加针对本界面恢复任务的暂停按钮、后台运行与可选同步节点线程执行；`2.0.0a5`进一步新增 SQLite 本地跨进程暂停请求、只读请求源组合，以及 CLI/TUI 显式监听入口，针对性回归通过。详见 [Workflow 文档](docs/workflows.md)。

`2.0.0a5`新增 `approval_agent_workflow_node()` 与未完成节点挂起：Workflow 内 Agent 等待审批时保留子 Run 引用，恢复需新的精确 Call ID 授权，不把待批节点标为完成。针对性回归通过；任意深度递归审批仍待实现；界面接线见`2.0.0a6`说明，详见 [Workflow 审批桥](docs/workflows.md)。

TUI Home 页另提供六行字符拼接的 `W-AGENT` 欢迎标识与可爱颜文字，窄窗口自动切换紧凑标题；本版包含宽屏、窄屏与恢复窗口尺寸的冒烟验证。

## 下一代模块图

`2.0.0a5`提供审批关联的 CLI/TUI 只读查询与 `WorkflowApprovalGrants` 宿主一次性授权模板（针对性回归通过）。`2.0.0a6`新增 `checkpoint workflow-approve-resume` 与显式异步工厂装配、检查点复核和操作结束授权清理（针对性回归通过）。匹配快照不代表授权；TUI 已接入同一工厂服务（针对性回归通过），详见 [Workflow 审批操作](docs/workflows.md)。

```text
应用与模板       客服模板 / 编码模板 / 用户自定义装配
运行时           Agent Loop / Workflow / Session / Checkpoint
能力             Models / Router / Tools / RAG / Memory / Sandbox
微内核           Plugin / Registry / Lifecycle / Scope / Events
基础设施         Storage / Telemetry / CLI / TUI / Evaluation
```

下一代 API 直接从 `w_agent` 导出，不引入 `w_agent.v2` 命名空间。已实现的最小兼容层保留必要的 1.x Agent 复用路径。

## 安装现有版本

```bash
pip install wagent-framework
```

安装最新 Alpha：

```bash
pip install --pre wagent-framework==2.0.0a9
```

可选依赖：

```bash
pip install "wagent-framework[fastapi,langchain,opentelemetry]"
pip install "wagent-framework[models]"
pip install "wagent-framework[wasm]"
pip install "wagent-framework[tui]"
```

PyPI 1.x 支持 Python 3.9+；`2.0.0a3`、`2.0.0a4` 源码与后续 2.x 版本要求 Python 3.11+。

## 1.x 最小示例

```python
import asyncio

from w_agent import AgentComponent, BaseAgent, BeanFactory


@AgentComponent(name="hello_agent")
class HelloAgent(BaseAgent):
    async def arun(self, prompt: str) -> str:
        return f"Hello, {prompt}!"


async def main() -> None:
    factory = BeanFactory()
    factory.register_bean("hello_agent", HelloAgent())
    agent = await factory.get_bean("hello_agent")
    print(await agent.arun("W-Agent"))


asyncio.run(main())
```

这段代码只展示 1.x 兼容用法，不会自动接入新的 ReAct、模型或工具运行时。

## 本地开发体验

当前源码已提供：

```text
wagent init
wagent profile list
wagent probe <endpoint>
wagent provider-probe --mode safe|active|capability [--confirm-active-probe]
wagent doctor
wagent tui
wagent composition export
wagent composition inspect|save|list
wagent session create|list|show|usage|archive|unarchive
wagent run "hello" --confirm-model-call --json
wagent evaluate cases.json --confirm-model-call --report report.json
```

CLI 和 TUI 只调用公开 Python API。当前 CLI/TUI 基础标记为 `Experimental`：已覆盖初始化、模板列表、安全/主动端点探测、装配管理/离线预览与依赖计划、本地 Session 生命周期、按 Agent 跨 Session 的安全用量/费用汇总、需逐次确认的配置化 Agent 运行与 Token 汇总、Agent/Workflow Checkpoint 脱敏列表、Catalog 工具选择、权限授予、精确 Call ID 审批恢复、精确版本 Workflow 恢复、通用插件无导入预览/确认加载/TUI 卸载、脱敏实时 RunEvent，以及支持版本化内置套件与独立评测工具加载确认的本地评测。Workflow 恢复、离线依赖计划、内置评测套件、跨 Session 汇总与通用插件操作属于 `2.0.0a4` 的能力；锁定插件安装计划、Docker/显式授权本地 Sandbox 安装与独立加载确认仍在`2.0.0a4`。在线来源发现、自动升级和签名信任仍为 `Planned` 或 `Reserved`。

## 工程装配分享

`Implemented`：开发者可以给框架装配命名和版本化，导出为可复制编码，并在无网络、无导入、无执行的阶段完成校验和风险预览。本地 Store 支持多版本与别名且拒绝静默覆盖冲突内容。`2.0.0a4` 还能通过可替换 Resolver 和显式候选清单生成环境/插件离线计划。`2.0.0a4`新增宿主精确版本、完整 SHA-256 wheel 闭包和来源映射生成安装请求；安装必须绑定精确请求摘要，在 Docker 或显式授权的不隔离本地 Sandbox 中执行，完成后仍需独立授权才能把已校验安装树加载进插件生命周期。框架不会自行发现来源、解析未锁依赖、自动升级或替用户确认代码执行。

装配编码只携带可移植清单，不携带密钥，不默认打包任意源码，也不会在导入时自动执行不可信插件。详细设计见[工程装配分享](./docs/project-sharing.md)。

## 文档

- [文档索引](./docs/README.md)
- [架构设计](./docs/architecture.md)
- [路线图与能力状态](./docs/roadmap.md)
- [使用指南](./docs/guide.md)
- [开发者指南](./docs/developer.md)
- [API 状态与规划](./docs/api.md)
- [插件系统](./docs/plugin-system.md)
- [模型、路由与接口探测](./docs/model-routing.md)
- [HTTP Provider 与厂商模板](./docs/provider-templates.md)
- [工具注册、策略与执行](./docs/tools.md)
- [Agent Runtime 与 ReAct Loop](./docs/agents.md)
- [Session 生命周期与跨 Run 上下文](./docs/sessions.md)
- [本地配置化 Agent Runtime](./docs/local-runtime.md)
- [Workflow 与节点恢复](./docs/workflows.md)
- [沙箱与本地执行](./docs/sandbox.md)
- [CLI 与 TUI](./docs/tui.md)
- [本地测试、模型回放与评测](./docs/testing-evaluation.md)
- [1.x 迁移](./docs/migration-1x.md)

## 明确不做

- 不提供 W-Agent 托管平台或云控制面。
- 首版不内置租户、组织、计费和 SaaS 管理系统。
- 不把某一种 ReAct、Workflow 或模型协议写死为唯一实现。
- 不在未经确认的情况下自动安装、升级或执行第三方插件。

## 许可证

本项目采用 [MIT 许可证](./LICENSE)。
