HarnessX Skill 技能

HarnessX — 库优先的 Python LLM Agent 工具包

harnessx 是一个面向生产环境的 Python Agent 框架，主打"以库优先、不锁供应商"。它不像传统框架那样把开发者绑死在固定的状态机图或角色提示词里，而是给出一组可组合的构件：实时流式输出、带 schema 推断的类型化工具注册、懒加载 Skills、多 Agent 委派、4 级记忆、沙箱代码执行、原生 MCP 工具桥接、LangSmith 追踪与评估套件。HarnessX 由 datagol 维护，第一个版本即支持 Anthropic、OpenAI、Gemini、OpenRouter、Azure OpenAI 五家供应商，仅需一个配置字段即可切换。

核心能力

• 零图谱样板：用普通 async Python 函数写 Agent，不再手写状态机；Agent() 一行实例化，开箱即用流式 run_stream。
• 供应商无关：内置 Anthropic、OpenAI、Gemini、OpenRouter、Azure OpenAI 一等公民支持；provider="openai" + model="" 即可切换。
• 多模态原生：单个 turn 可携带图像、PDF、音频作为内容块，简化工具调用链。
• 流式优先：run_stream 输出类型化事件，方便前端接 WebSocket / SSE。
• 懒加载 Skills：通过 YAML frontmatter 的 SKILL.md 包按需加载专项指南，减少首轮 token 消耗。
• OKF 知识包：指向文件夹或 git 仓库即可做 BM25F 检索、概念读取、链接遍历，所有结果带出处。
• 4 级记忆 + 多 Agent 委派：支持 short-term、long-term、entity、procedural 等多层级记忆，并允许把子任务交给其它 Agent。
• 沙箱与权限护栏：迭代预算 + 工具执行后端（subprocess / Docker / macOS Seatbelt / NVIDIA OpenShell）可插拔，避免误删文件。
• MCP 原生：3 行代码接入任意 Model Context Protocol 服务器（stdio 子进程或远程 HTTP，含 SSE fallback）。
• 可观测与评估：零开销生命周期 hook、中间件变换、原生 LangSmith 追踪、benchmark 评估套件。
• 可选决策 SDK：Jev SDK 提供 Choice 路由/分类、Score 评分、Noul 证据检查，用于结构化决策。

安装配置

1. 添加依赖（推荐 uv）：uv add harnessx 或 uv add "harnessx[all]"（一次性安装全部集成）；pip 方案：pip install harnessx。
2. 按需启用 extras：例如 [openai]、[azure]、[gemini]、[openrouter]、[jev]、[mcp]、[postgres]、[temporal]、[docker]、[openshell]、[langsmith]、[server]，按实际场景勾选。
3. 配置供应商密钥：在根目录 .env 中填 ANTHROPIC_API_KEY=sk-ant-...（Anthropic）或对应供应商 key；.env.example 提供模板。
4. 可选本地依赖：PostgreSQL、Temporal、Redis 仅在对应示例需要时启动；docker compose up --build 一次性拉起完整测试栈（应用监听 http://localhost:8765）。
5. 升级迁移：从旧的 datagol-agent-harness 升级时改 import 为 harnessx（无兼容 alias），并查阅仓库 CHANGELOG。

使用步骤

1. 实例化 Agent：from harnessx import Agent; agent = Agent(provider="anthropic")（或 provider="openai"、provider="gemini" 等）。
2. 注册类型化工具：用 Python 装饰器把 async 函数声明成工具，框架自动推导 JSON schema，省去手写 schema。
3. 流式对话：async for event in agent.run_stream("…") 拿到 token、工具调用、决策事件；前端可直接接 SSE/WebSocket。
4. 按需加载 Skills：把 SKILL.md 放进指定目录，Agent 在收到相关请求时按 YAML frontmatter 自动懒加载对应指南。
5. 接入知识库（OKF）：KnowledgeBundle.from_folder("./kb") 或 .from_git(url)，Agent 检索时会返回带来源的内容块。
6. 桥接 MCP：用 MCP.from_stdio(["npx","-y","@some/mcp-server"]) 或 MCP.from_http(url) 接入任意 MCP 工具，3 行代码完成。
7. 沙箱执行危险操作：把 ShellTool 后端设为 docker 或 openshell，Agent 的 shell/文件工具就跑在隔离环境里。
8. 可观测与评估：启用 langsmith extra 后所有调用自动上报；eval/ 目录提供 benchmark 套件，跑 pytest -q 即可回归。

适用场景

• 企业级多供应商 Agent 平台：想用一套代码同时接 Anthropic / OpenAI / Gemini，按业务路由最便宜的供应商。
• 代码与文档助手：把"代码生成 + 文档检索 + 工具调用"组合在一起，做 IDE 内的编程 Agent。
• 数据 / 报表 Agent：用 OKF 知识包把企业知识库喂给 Agent，自动回答业务问题并附出处。
• 自动化运维 Agent：接入 MCP 桥接 Shell / Kubernetes / 数据库工具，用沙箱后端隔离执行。
• 多 Agent 协同任务：把检索 Agent、规划 Agent、执行 Agent 编排起来，harnessx 支持父子 Agent 委派与共享记忆。
• 科研与教育：跑 benchmark / 评估套件，对比不同 LLM 在同一任务上的表现。

适用人群

• 用 Python 构建 LLM Agent 的后端 / 平台工程师；
• 想要"零图谱、可组合"替代 LangGraph / AutoGen 的研发团队；
• 需要原生 MCP 桥接 + 沙箱执行 + LangSmith 追踪的 AI Infra 团队；
• 在多个 LLM 供应商之间做成本 / 性能优化的 AI 产品经理；
• 做 Agent 评估与基准测试的研究者。

工作原理

HarnessX 把 Agent 拆成四块协作构件：Provider 适配层统一 Anthropic / OpenAI / Gemini / OpenRouter / Azure OpenAI 的消息协议；Tool Registry用 Python 类型注解自动推导工具 schema，注册即用；Skill Loader根据请求上下文懒加载 SKILL.md YAML 包，避免一次性灌入所有指令；MCP Bridge把 stdio 子进程或 HTTP/SSE 远端 MCP 服务挂载成普通工具，3 行接入。Memory分 4 级（短期 / 长期 / 实体 / 程序）配合 multi-agent delegation 做上下文共享；Sandbox通过 subprocess / Docker / macOS Seatbelt / NVIDIA OpenShell 四种后端执行危险操作。Observability走 LangSmith + 中间件 hook，所有调用带 trace。所有构件均可独立替换，因此可以渐进式迁移：先替换 Provider，再加 Skill，再加 MCP 桥接，不必重写。

官方链接

• PyPI 包：https://pypi.org/project/harnessx/
• GitHub 仓库：https://github.com/datagol/agent-harness-x
• 安装命令：uv add harnessx 或 pip install harnessx
• 文档与示例：仓库 examples/ 目录与 https://www.datagol-harness.dev/docs/