W-Agent

借鉴 Spring 的 IoC、AOP 与生命周期思想，开发你自己的 Harness。

English · 文档 · 快速入门 · 扩展开发 · 路线图

W-Agent 是面向 Python 开发者的本地开源 Harness 开发框架。目标是通过统一容器、依赖注入、切面和生命周期，让你用注解、配置或显式代码自由装配执行体系。ReAct、Workflow、客服/编码模板与 CLI/TUI 是可选实现，而不是框架本身的边界。

**版本范围：**2.1.0 纳入已完成 M0–M5 验收的 Harness 开发核心。验收基线包含 259 项相关测试、离线制品、隔离安装与三示例仓库外 Python/CLI/无显示 TUI。见发布说明和证据与限制。上传状态以 PyPI 为准。

它提供组合能力的协议和实现，不要求你采用固定 Harness，也不需要托管平台账户。

为什么使用 W-Agent

• 模块可替换：从 Provider 到 Agent Loop 都有公开扩展接口；Python、装饰器、YAML 引用和 entry point 汇入统一插件注册表。
• 链路可组合：单 Agent ReAct/tool loop 与 DAG、状态图、Python Workflow 可以通过适配器组合。
• 模型不绑定厂商：提供通用 HTTP 请求映射，以及 OpenAI、Anthropic、Gemini、Ollama、DeepSeek、GLM、Qwen、Turbo 模板；厂商专有参数可通过扩展接口处理。
• 执行边界明确：工具权限、逐调用审批、Docker 沙箱和显式授权的本地执行相互独立；隔离不可用时不静默降级。
• 运行过程可观察：Run/Session、输入输出 Token、可配置预算、事件回放和本地评测，为调试与迭代提供基础。

安装

需要 Python 3.11+。建议在项目自己的虚拟环境中安装。以下命令固定到正式版 2.1.0：

python -m pip install "wagent-framework==2.1.0"

按需添加依赖，不必安装所有模块：

# HTTP 模型接入与终端界面
python -m pip install "wagent-framework[models,tui]==2.1.0"

# PDF / DOCX / XLSX / PPTX 解析
python -m pip install "wagent-framework[knowledge-documents]==2.1.0"

其他 extras 包括 mcp、media-preview、testing、fastapi、langchain、opentelemetry 和平台受限的 wasm。参见安装指南。

快速入门

以下示例使用 2.1.0 框架核心。先按上方命令安装 wagent-framework==2.1.0，也可从匹配源码安装 python -m pip install -e .；TUI 是可选依赖。仍使用 2.0.0 时请看此前基础组件教程。

保存为 hello_harness.py，然后执行 python hello_harness.py。它不使用模型、ReAct 或工具注册表，也不需要 API Key：

import asyncio

from w_agent import (
    AgentComponent, ApplicationOperation, ApplicationProject,
    PostConstruct, PreDestroy, ServiceComponent, compile_decorated,
)


@ServiceComponent("formatter")
class Formatter:
    def format(self, text: str) -> str:
        return text.strip().upper()


@AgentComponent("hello", scope="run")
class HelloHarness:
    def __init__(self, formatter: Formatter):
        self.formatter = formatter
        self.ready = False

    @PostConstruct
    def initialize(self):
        self.ready = True

    async def run(self, text: str) -> str:
        if not self.ready:
            raise RuntimeError("Harness not initialized")
        return self.formatter.format(text)

    @PreDestroy
    def close(self):
        self.ready = False


async def main():
    plan = compile_decorated([Formatter, HelloHarness])
    project = ApplicationProject(plan, {"run": ApplicationOperation("hello")})
    async with project.open() as host:
        print(await host.invoke("run", "hello framework"))


asyncio.run(main())

预期输出为 HELLO FRAMEWORK。注解只声明组件；compile_decorated 编译依赖和作用域，ApplicationContext 管理实例与生命周期，ApplicationHost 执行公开操作。这里的 Run 组件每次调用初始化，并在返回时清理，不是固定 Agent 基类。

三条完整开发链路见开发自己的 Harness：

示例使用确定性离线模型替身，不代表真实 LLM 质量。默认 ReAct、Workflow、Provider、工具和预算仍可按需加入，见默认装配。examples 不包含在 wheel 中；安装用户需从匹配源码或 sdist 复制示例及伴随 JSON，不能把教程文件当成库运行时依赖。

按你的方式装配

以下是职责关系，不是必须经过的固定管线：

注解 / 显式 Python / 允许目录中的配置
                 ↓
        AssemblyPlan（依赖与作用域校验）
                 ↓
 ApplicationContext（实例、DI、AOP、生命周期）
                 ↓
  你的 Harness 或可选 ReAct / Workflow 装配
                 ↑
 ApplicationProject / Host ← Python / CLI / TUI

CLI 与 TUI

安装 tui extra 后：

wagent --help
wagent init
wagent tui

w-agent 是同一 CLI 的别名。TUI 提供大字符标识与颜文字、运行和审批、会话/用量查看等入口。

2.1.0 还提供 wagent application run --entry module:create_project --input-file call.json --confirm-code 与 TUI 的 Application 页，共用公开项目执行入口。项目是受信 Python 代码，确认加载不等于工具副作用批准；完整操作见三条教程。

wagent init 只创建本地 .wagent 目录和空的 config.json，已有配置不覆盖；不会配置模型或发起请求。实际运行前按Runtime 配置示例填写配置，再明确授权模型调用。TUI 不替代这些授权边界。

能力状态与安全

2.1.0 提供 Harness 开发框架核心；可选高级能力仍可能标记为 Experimental。见版本范围与路线图。

• 普通 Python 工具和插件是受信宿主代码，不是安全沙箱；不可信代码需要隔离执行。
• 工具权限不等于逐调用审批；导入分享码不自动安装、执行代码或授予权限。
• 模型目录声明不证明连接、鉴权或生成质量；未知用量和价格不表示为零。
• 恢复只保证文档明确支持的边界，不恢复任意 Python 调用栈，也不自动重放结果未知的副作用。
• 多 Agent、分布式 Workflow、在线插件市场等保留或计划项，不是当前开箱即用能力；框架不提供多租户托管服务。

文档与贡献

从使用指南开始，或查阅文档目录、架构、公共 API与1.x 迁移。

欢迎通过 Issues 提交问题与提案。报告问题时请附 Python/W-Agent 版本、最小复现和脱敏日志；新增能力请先说明扩展点、授权边界，并同步中英文文档。贡献约定见开发者指南。

许可证

MIT