一、概念界定:什么是 Agent Harness
业界目前最广为引用的定义来自 Addy Osmani:Agent = Model + Harness——”如果你不是模型,那你就是 harness”。Harness 指模型之外的一切执行层代码:
– Agent loop:收集上下文 → 采取行动 → 验证结果 → 循环,直到任务完成 – 工具定义与执行:工具 schema、执行环境、结果回填 – 上下文管理:历史裁剪、压缩(compaction/condenser)、笔记/计划落盘、子代理隔离 – 权限与沙箱:审批流、容器隔离、危险命令拦截 – 扩展机制:MCP、hooks、skills、插件 – 可恢复性:会话持久化、断点续跑、确定性重放
与相邻概念的分层(Winder.AI / LangChain 的共识):模型(推理)→ Harness(运行单个 agent)→ Framework(编排多个 agent)→ Platform(跨团队长期运行)。一句话:Frameworks compose agents. Harnesses run them.
本文的研究对象是:用 Python 编写、开源、且核心价值在于”运行 agent 的执行层”的项目。既包括完整的 coding harness(如 OpenHands、mini-swe-agent),也包括提供了 harness 级原语的 agent 框架(如 Pydantic AI、AgentScope)。
—
二、全景格局
2.1 两大阵营
– TS/Claude Code 阵营:Claude Code(专有)、OpenCode(开源事实领袖)、Pi、Codex(Rust/TS)、Goose(Rust)——多为”终端交互式 coding harness”。 – Python 阵营:OpenHands、mini-swe-agent、smolagents、Pydantic AI、AgentScope、nanobot 等——多走”评测驱动 + SDK 化”路线,与学术界(Princeton、Berkeley)和数据/训练生态衔接更深。
分野的实质不是语言,而是产品形态:TS 阵营卖”装好的终端产品”,Python 阵营卖”可编程的执行层 + 可复现的评测”。
2.2 第一代 Python 编程 agent 的覆灭(2023 届)
| 项目 | 结局 |
|---|---|
| gpt-engineer(55k★) | 已归档,创始人转向 Lovable |
| GPT Pilot(33.7k★) | 停止维护,转向商业产品 Pythagora.ai;2025-08 遭供应链蠕虫投毒(恶意提交窃取凭证,潜伏至 2026-06 才被发现) |
| Open Interpreter(68k★) | Python 版已死,原仓库转为 OpenAI Codex 的 Rust fork;Python 经典版移交社区 fork |
| aider(48.7k★) | 半死不活:2026-02 后近 7 个月零发版,续命靠社区 fork aider-ce |
教训:“代码生成器”形态被”agent harness”形态淘汰。2025 年后的分水岭是:工具循环 + 权限系统 + 上下文工程 + subagent,缺一项就出局。
2.3 现役 Python 阵营主力(2026-09)
| 项目 | 定位 | Stars | 许可证 | 状态 |
|---|---|---|---|---|
| OpenHands(software-agent-sdk) | 全功能 coding harness SDK | 86k(主仓)/ 1k(SDK) | MIT | 主力开发 |
| mini-swe-agent | 极简 coding harness | 6.9k | MIT | 主力开发 |
| smolagents | CodeAct 极简 agent 库 | 29.1k | Apache-2.0 | 缓慢维护 |
| AgentScope 2.0 | Claude Code 式 harness 框架 | 30.6k | Apache-2.0 | 最活跃(日更) |
| Pydantic AI 2 + pydantic-ai-harness | 类型安全框架 + harness 层 | 19.7k / 0.9k | MIT | 高频迭代 |
| OpenAI Agents SDK(Python) | 多 agent SDK | 29.2k | MIT | 0.x 迭代中 |
| Qwen-Agent | Qwen 模型配套框架 | 17.1k | Apache-2.0 | 2026 中后放缓 |
| SWE-agent | 研究型 harness(ACI 奠基) | 20.2k | MIT | 维护模式(被 mini 取代) |
| Agent-S | GUI 自动化 agent | 12.2k | Apache-2.0 | 低速维护 |
| Letta | ~~Python 记忆 agent 平台~~ | 24.6k | — | 已转 TypeScript(letta-code) |
对照组(明确排除在”Python 现役”之外):claude-agent-sdk-python(Anthropic 官方,开源 SDK 皮 + 捆绑闭源 CLI)、pi(TS)、Goose(Rust)、nanobot(Python 极简,HKUDS)。
—
三、核心项目深度档案
3.1 OpenHands V1(software-agent-sdk)——工程化程度最高的全功能 harness
2024 年以 OpenDevin 起家(V0 是 Web GUI + 事件流单体),2025-09 宣布重构,2026 年主仓转型为 Agent Canvas(自托管”编码 agent 控制中心”,可经 ACP 协议接入 Claude Code、Codex 等第三方 agent)。真正的 harness 内核在 software-agent-sdk(附论文 arXiv:2511.03690)。
架构精髓:事件溯源(Event Sourcing)
– Agent 是无状态、不可变、可序列化的配置对象,通过 on_event() 回调发出结构化事件
– 一切交互都是不可变 Event 追加进日志;ConversationState 是唯一可变组件
– 事件逐条存 JSON,支持确定性重放与断点恢复——这是四者中唯一生产级的可恢复性设计
– 动作先经 SecurityAnalyzer 评级,默认高危动作需人工确认(ConfirmationPolicy)
上下文管理:Condenser(无状态压缩器)——超限时删事件换成摘要,以 CondensationEvent 入库、全量日志保留,默认 LLMSummarizingCondenser 降低 API 成本约 2 倍。
工具与沙箱:Pydantic 定义 Action–Execution–Observation;官方工具 TerminalTool / FileEditorTool / TaskTrackerTool + 浏览器;MCP 一等公民(支持 OAuth)。沙箱 Local/Docker/K8s 三态,本地转远程只需改两行;Agent Server 提供 REST + WebSocket,官方镜像捆绑 VSCode Web、VNC、Chromium;SecretRegistry 自动掩码敏感输出。
成绩:SWE-bench Verified 72.8%(Sonnet 4.5);SDK README 口径 77.6%。经 LiteLLM 支持 100+ 模型。
优劣:优势是唯一具备事件溯源/恢复/安全审查/多租户完整工程化的 Python harness;劣势是仓库碎片化后定位漂移(Canvas 转型引发社区困惑),V0 时代曾背”140+ 配置字段”的复杂度债务。
3.2 mini-swe-agent——”极简主义”流派的旗手
Princeton 原班人马对 SWE-agent 复杂 ACI 路线的公开反叛:”如果 agent 简单 100 倍但效果几乎不降呢?” Agent 核心类 default.py 约 100 行,环境/模型/run 脚本各约 100 行。
三个激进设计决定:
1. 除 bash 外没有任何工具,甚至不用模型的 tool-calling 接口(任何模型都能跑);
2. 不维护有状态 shell 会话——每步动作通过独立 subprocess.run 执行,天然隔离,沙箱化只需换成 docker exec;
3. 无 condenser、无压缩——上下文线性增长,赌模型长上下文。
设计红利:消息历史与发给 LM 的内容完全一致,轨迹纯净,是微调/RL 训练的理想 baseline(不会过拟合特定 scaffold)。
成绩:SWE-bench Verified >74%,Claude Opus 4.5 下 76.8%——与复杂 harness 相当甚至更高。用户含 Meta、NVIDIA、IBM、Anyscale;Ramp 的商业评测由它驱动。
优劣:优势是极简、快、轨迹纯净、可 hack;劣势是无浏览器/GUI 工具、无上下文压缩、单 agent、无 MCP/hooks。
3.3 SWE-agent——ACI 概念的奠基者(已入维护模式)
NeurIPS 2024 论文(Agent-Computer Interfaces)约 2500 次引用,核心遗产是 ACI 方法论:接口设计对 LM 如同 prompt 设计。
– 文件查看器每轮只显示 100 行(实验最优)+ 滚动/搜索 – edit 命令内置 linter,语法错误直接拒绝写入 – 搜索只返回文件名不展示上下文(实验证明展示反而让模型困惑) – 整个行为由单个 YAML 驱动(模板、工具、history processor) – 执行由姊妹项目 SWE-ReX 承担(Docker/远程 modal/AWS,持久 shell 会话)
SWE-agent 1.0 + Claude 3.7 曾达 SWE-bench Verified SOTA(约 62%)。官方 README 明确宣布被 mini-swe-agent 取代,仅建议在”实验不同工具接口”时使用。它留下的最重要启示:Princeton 自己用实验证明了自己的复杂路线过度设计。
3.4 AgentScope 2.0——定位上最接近”开源 Claude Code”的 Python 框架
阿里出品,2026 年最活跃(调研前一天仍在推送)。0.x(多 agent 消息平台)→ 1.0(2025-08,转向 ReActAgent 中心)→ 2.0(2026),哲学:”利用模型自身的推理与工具能力,而非用固化编排约束它”。
2.0 构建块(对标 Claude Code 的程度惊人):
– ReAct agent:结构化输出、实时中断与恢复、批量顺序/并发工具调用 – Toolkit 自带 Bash/Grep/Glob/Read/Write/Edit + task/plan 工具——即 Claude Code 的完整工具集 – Context 层:自动 compaction、tool-result offload、中间件注入 – Permission & HITL:细粒度工具确认 + bypass 模式 – 六层 Middleware 钩子(reply/reasoning/acting/model calling/permission/context compression) – Sandbox:local/Docker/Apple Container/Bubblewrap/E2B/OpenSandbox/Daytona/K8s 八种 – MCP & Skill Hub(对接 GitHub MCP Registry)、Agent Service(FastAPI 多租户后端 + Web UI + leader-worker 编排)、Console(终端运行界面)、Channels(飞书/Discord/钉钉)
定位:launch_console(agent) 即得终端体验——Claude Code 给你装好的产品,AgentScope 给你 Claude Code 的全部内脏让你自建。劣势:抽象层多、上手重于单文件工具;终端产品化打磨仍逊于 Claude Code/OpenCode。
3.5 Pydantic AI 2 + pydantic-ai-harness——”capability 化”的 harness 新范式
Pydantic 官方团队出品,v2.0 稳定版 2026-06-23 上线(当前 2.38.0,迭代最频繁)。核心是类型安全:Agent(model, deps_type=..., output_type=...),结构化输出验证失败自动回喂重试;复杂控制流走 pydantic-graph(类型化图状态机,可持久化恢复)。
v2 的关键演进:Capability 原语 + 官方 Harness 库——这是 2026 年最值得注意的抽象创新:
– instructions、tools、hooks、model settings 捆绑为单一 capability,可常驻也可 defer_loading=True 像技能一样按需加载(与 Claude Code 的 Skills 同构)
– pydantic-ai-harness(官方,2026-03 创建)提供开箱 harness:Coder() = FileSystem(路径穿越防护)+ Shell(命令白名单 + 剥离 LLM API key 环境变量)+ RepoContext(自动加载 AGENTS.md)+ Planning + 只读 explorer sub-agent + 上下文控制(ClearToolResults、WarnNearLimits、ToolOutputLimits)
– Code Mode:在 Monty 沙箱中用一个 Python 脚本批量调 N 个工具——解决 tool-call JSON 的 token 膨胀(与 CodeAct 思路合流)
– durability 是独门卖点:Temporal / DBOS / Prefect 官方共同维护,agent 运行可跨进程崩溃恢复;Logfire(OTel)可观测
劣势:抽象层次多、v2 有迁移成本;无自动分层记忆(哲学是显式 message_history + history processors)。
3.6 smolagents——CodeAct 路线的极简代表
HuggingFace 出品,”barebones library for agents that think in code”,核心逻辑约 1000 行。
– CodeAct 是最大卖点:CodeAgent 不用 JSON tool calling,LLM 每步直接写一段 Python 作为 action,解释器执行后结果回填(Thought → Code → Observation)——源自 ICML 2024 论文(arXiv:2402.01030,精度提升最高约 20%)
– 论据:代码可组合(变量复用、嵌套、任意控制流)、省 token、工具更少效果更好(曾以小模型登顶 GAIA)
– 沙箱:默认本地执行(安全风险),生产用 E2B 云沙箱/Docker/Pyodide(Wasm 浏览器内)
– 多 agent:manager 模式,编排本身也写在生成的代码里,灵活性极高
– 局限:无持久化、无分层记忆、无上下文压缩,需自建;企业级 durability/可观测缺失;2026 年中后发版放缓
3.7 OpenAI Agents SDK(Python)——平台化 SDK,2026 年开始 harness 化
前身是实验性 Swarm,2025-03 发布。核心抽象:Agent(instructions + tools + guardrails + handoffs + 类型化 output_type),Runner.run() 驱动扁平循环(非图状态机)。
– 编排两种原语:handoff(控制权整体交接)与 agents-as-tools
– 内置全链路 tracing(默认上传 OpenAI dashboard,可导出 Logfire/Galileo)、并行 guardrails、Realtime/Voice pipeline
– Sessions(SQLite/SQLAlchemy/Redis)做会话持久化;durable execution 走 Temporal
– 2026-04 关键转向:加入 Sandbox agents(SandboxAgent + Manifest + GitRepo + Docker/本地沙箱客户端),使 SDK 能做长时程 coding 任务——明显吸收 Codex 的 harness 技术回馈到 SDK
劣势:0.x API 不稳定;最佳体验绑定 OpenAI 平台;无长期记忆原语。
3.8 其他值得记录的项目
– Letta(原 MemGPT):MemGPT 式三层自编辑记忆(core/recall/archival,”记忆即工具”)+ sleep-time compute(空闲期离线记忆巩固,arXiv:2504.13171)是其核心遗产;但 2026 年 Python 线已终止,活跃开发转入 TypeScript 的 letta-code。对 Python 用户而言是断档。 – Qwen-Agent:阿里官方框架,现直接作为 Qwen Chat 的后端(生产背书);技术亮点是 1M token 超长文档 RAG 与 Docker 沙箱 code interpreter;但本质是模型配套框架而非 harness,无权限系统/compaction/subagent,2026 中后更新乏力。 – Agent-S(Simular):唯一 GUI 自动化 agent,OSWorld 上以 bBoN(Behavior Best-of-N,并行 rollout 择优)达 72.6%,2025-12 宣布首个超越人类水平的 computer-use 成绩;不面向代码仓库任务。 – nanobot(HKUDS):约 4000 行的 Python 极简 harness,自比”agent 内核层”,极简流派的另一选手。 – claude-agent-sdk-python(Anthropic 官方):wheel 里直接捆绑 Claude Code CLI,SDK 只是驱动子进程的 async 薄层。代码 MIT 但运行受商业条款约束——“闭源 harness + 开源 SDK 皮”,与全开源替代品有本质区别,选型时需清醒。
—
四、架构维度横向对比
4.1 Agent Loop 设计
| 项目 | Loop 形态 | 状态管理 |
|---|---|---|
| OpenHands SDK | 事件驱动单循环 | 事件溯源,可重放可恢复 |
| mini-swe-agent | 线性消息 append | 轨迹 = 消息历史,零差异 |
| AgentScope 2.0 | ReAct 循环 + 中断恢复 | Memory 可插拔(ReMe/Mem0) |
| Pydantic AI | 固定循环 + 图状态机 | message_history 显式传入 + 持久化后端 |
| smolagents | CodeAct 循环 | 仅循环内历史 |
| OpenAI Agents SDK | Runner 扁平循环 + handoff | Sessions 抽象 |
| SWE-agent | YAML 驱动单循环 | HistoryProcessor 压缩 |
4.2 工具系统与”代码即动作”的合流
三条技术路线:
1. JSON tool calling(主流):OpenAI Agents SDK、AgentScope、Pydantic AI——schema 驱动,兼容一切模型,但长工具列表 token 膨胀; 2. CodeAct / code-as-action:smolagents、OpenHands(CodeAct 统一动作空间)、pydantic-ai-harness 的 Code Mode——把编排写在生成的代码里,可组合、省 token;Anthropic 官方也在其工程博客中合流到同一观点(“code is precise, composable, infinitely reusable”); 3. bash-only 极简:mini-swe-agent——不用 tool-calling 接口,一个 shell 走天下,换取模型无关性。
一个被反复验证的事实:工具接口设计就是 prompt 设计(SWE-agent 的 ACI 论文):查看器行数、linter 拒写、搜索输出裁剪,每个细节都有可测量的性能影响。
4.3 上下文管理四流派
| 流派 | 代表 | 机制 |
|---|---|---|
| 压缩器 | OpenHands Condenser | 超限删事件换摘要,全量日志保留,成本降 ~2x |
| 自动 compaction | AgentScope 2.0 / Claude Code | 阈值触发摘要 + tool-result offload |
| 显式上下文工程 | Pydantic AI history processors | 用户自写截断/摘要策略,ClearToolResults(0.7) 等 |
| 放弃压缩 | mini-swe-agent | 线性增长,赌长上下文窗口 |
| 结构化持久 | aider repo-map(历史方案)/ planning-with-files | tree-sitter 符号图 PageRank 裁剪;task_plan.md/findings.md/progress.md 三文件落盘 |
值得注意的是 planning-with-files(26.5k★)代表的”harness 模式即插件”流派:Manus 风格的文件化计划(hash 校验、压缩后可恢复)可以叠加到任意 harness 上,说明上下文工程正在从框架内部实现解耦为可移植模式。
4.4 沙箱与权限
– 最完整:AgentScope(八种沙箱)+ OpenHands(SecurityAnalyzer 动作评级 + ConfirmationPolicy) – 最小可行:mini-swe-agent(独立 subprocess,换 docker exec 即沙箱) – 代码执行特化:smolagents(E2B/Monty/Pyodide)、pydantic-ai-harness Shell(命令白名单 + 密钥环境变量剥离——细节很讲究) – 教训(Winder.AI):沙箱管住了文件系统不等于管住了账单和网络;权限模型要按”爆炸半径”设计
4.5 扩展机制(MCP / hooks / skills)
– MCP 一等公民:OpenHands(含 OAuth)、AgentScope(Skill Hub)、Pydantic AI(capabilities=[MCP(...)] 一行接入)、OpenAI Agents SDK
– MCP 的反思同样重要:Anthropic 自己提出 “code execution with MCP”(按需加载工具,上下文开销从 26% 降到 1.6%);极简派指出 Playwright MCP 开场即耗 13.7k tokens,主张 CLI 工具 + README 的渐进披露
– Skills 化:Pydantic AI 的 deferred capability 与 Claude Code 的 Skills 同构;OpenHands 有 Skills/插件市场——“能力按需加载”是 2026 年 harness 的共同演进方向
—
五、实证:Harness 本身就是最大的性能变量
这是本次调研中最重要的横向发现——同一模型在不同 harness 下成绩差异可达 5-30 个百分点:
– arXiv 论文 “The Scaffold Effect in Coding Agents”:同一模型下 OpenHands-SDK 69% vs Goose/OpenCode 仅 38% – Terminal-Bench 2.0:同一 Opus 模型在不同 harness 中名次差距 25 位 – SWE-bench Verified 榜单 99/100 为自报分数 – 反例:Letta Code 凭持久记忆在 HAL 上 59.1% 超过 Claude Code 的 41.6%(同为 Anthropic 模型)——证明复杂特性在特定负载下有真实收益
为此 Princeton 建了 HAL(Holistic Agent Leaderboard) 在受控条件下对比 harness。选型启示:任何”模型 X 达到 Y%”的解读都必须先问 harness 是什么;反过来,自建 agent 产品时,投在 harness 上的工程收益可能大于换模型。
极简 vs 全功能的裁决(截至 2026-09,未决):极简派的弹药是 mini-swe-agent 76.8% 不输复杂 harness、Pi 四工具即可打;全功能派的证据是事件恢复、安全审批、记忆在长时程/生产环境不可替代。目前的合理结论:基准分数上极简不输,生产工程上全功能仍有护城河;模型越强,harness 该越薄。
—
六、选型建议
六维选型框架
1. 形态匹配:要”装好的终端工具”还是”可编程执行层”?Python 阵营几乎全是后者; 2. 模型耦合度:供应商中立(mini/AgentScope/Pydantic AI)vs 平台绑定(OpenAI SDK 最佳体验在 OpenAI); 3. 上下文工程自主度:显式控制(Pydantic AI)vs 自动化(OpenHands/AgentScope)vs 无(mini); 4. 可恢复性/durability:长时程任务是否需要崩溃恢复?(OpenHands 事件溯源 / Pydantic AI Temporal 是最强) 5. 安全模型:权限粒度、沙箱隔离范围、审计; 6. 可评测性:能否进 HAL/SWE-bench 复现,自建 evals 成本(mini 轨迹最纯净,最适合 RL/微调闭环)。
按场景推荐
| 场景 | 首选 | 理由 |
|---|---|---|
| 学习 harness 原理 / 二次开发起点 | mini-swe-agent | 100 行核心,每一行都是设计决定 |
| 构建生产级 agent 产品(全功能) | OpenHands SDK 或 AgentScope 2.0 | 前者工程化最深(事件溯源),后者工具集/权限/compaction 最像 Claude Code 且最活跃 |
| 类型安全 + 长事务 durability 的企业后端 | Pydantic AI 2 + harness | Temporal/DBOS 官方维护,capability 抽象最新 |
| 快速原型 / 科研实验 / GAIA 类任务 | smolagents | CodeAct 省 token,与 HF 生态无缝 |
| 训练/微调/RL 数据闭环 | mini-swe-agent | 轨迹与 LM 输入完全一致,无 scaffold 过拟合 |
| GUI/电脑操作自动化 | Agent-S | OSWorld 超人类水平,无同级对手 |
| 深度绑定 Qwen 生态 | Qwen-Agent | 模板级配合 + 1M RAG,但接受其更新放缓 |
| 愿意接受闭源内核换开箱即用 | claude-agent-sdk-python | 注意:闭源 harness + 商业条款 |
三条决策启发法
1. 别比功能清单,比预设假设——功能已趋同,差异在各 harness 替你做了哪些决定; 2. 选型期按 18 个月算——这个领域洗牌速度(参考第一代覆灭史)不支持五年规划; 3. harness 只会移动不会消失——compaction、重试逻辑会随模型升级作废,而沙箱、权限、审计规则不会;自建时优先把后者握在自己手里。
—
七、结语:三个趋势判断
1. 收敛于”代码即动作”:smolagents、OpenHands、pydantic-ai-harness Code Mode,连 Anthropic 官方都在同一论点上合流——JSON tool calling 的霸权正在被侵蚀; 2. harness 层的”薄化”与”能力按需加载”并行:模型越强核心 loop 越薄(mini/pi 路线),而 skills/deferred capability 让重量级能力变成按需挂载的插件(Pydantic AI、Claude Code Skills); 3. Python 阵营的独特生态位是评测、训练与 SDK 化:TS 阵营赢得终端产品,Python 阵营承接”把 harness 变成可复现、可训练、可嵌入产品的基础设施”。Letta 的离场说明这个生态位并非安全,但 OpenHands SDK、AgentScope 2.0、Pydantic AI 三线并进的势头表明,2026 年的 Python harness 战争才刚刚进入正赛。
—
附:主要信息源
– OpenHands / software-agent-sdk · V1 路径博客 · SDK 论文 arXiv:2511.03690 – mini-swe-agent · SWE-agent · ACI 论文 arXiv:2405.15793 · HAL – AgentScope · Pydantic AI v2 · pydantic-ai-harness – smolagents · CodeAct 论文 arXiv:2402.01030 · OpenAI Agents SDK – Addy Osmani: Agent Harness Engineering · Mario Zechner: Pi · Anthropic: Claude Agent SDK · Anthropic: 长时程 harness · Simon Willison: Designing agentic loops – Winder.AI harness 对比 · Scaffold Effect 论文 · Agent-S · Letta sleep-time compute