05 · 如何通过实际项目研究 Agent 的工程实现？ - Case Studies

所属知识库：Agent 全栈技术地图
所属领域：02 · Agent
所属章节：03 · 如何设计、构建和测试 Agent？ - Development & Practice
文档类型：真实项目技术案例研究
版本：v2.0（重写版）
更新日期：2026 年 10 月 28 日
核心问题：三个具有不同执行环境的真实开源 Agent 项目，如何将任务目标转换为模型决策、工具行动、环境反馈和可验证结果？其实现中的控制权、状态、边界与可靠性机制有何异同，哪些设计能够迁移？
研究状态：源码与文档定向核验版，非完整复现版。 本文基于截至研究日检索到的公开仓库文件与项目文档，分析 SWE-agent、OpenHands、browser-use 三个真实项目。引用具体文件路径、类、函数及可核查代码行为；没有声称在本地完整安装运行这三个项目、完成端到端基准或审计最新版本的全部源码。仓库 main 分支会变化，文中路径和 API 应按引用时的版本核对；正式复现时须记录提交 SHA。附带代码只用于复现本篇的跨案例工程决策模型和契约测试，不是三项目的替代实现。

本专题属 Development & Practice，版本 v2.0（相对 v1.1 重写：主体改为 SWE-agent、OpenHands、browser-use 的定向源码研究）。

一、为什么必须重写：从「案例研究方法」转向「真实项目研究」

v1.1 的主要问题，是用了大部分篇幅解释如何研究案例，却没有真正深入研究任何一个可追溯的开源工程。尤其是自行构造的固定检索与自适应检索实验，虽能说明控制策略差异，却不能替代对真实 Agent 软件的架构、源码与失败路径分析。本版将研究主体改为三个项目：

SWE-agent：将 GitHub issue 转化为代码修改，重点研究 Agent–Computer Interface（ACI）、行动解析、沙箱命令执行、轨迹与提交。
OpenHands：面向软件工程任务的 Agent 系统，重点研究 Action–Observation、EventStream、Runtime 与沙箱之间的职责划分，并辨识项目架构演进。
browser-use：将自然语言任务转化为浏览器操作，重点研究浏览器状态获取、动态动作 Schema、模型输出、工具执行与会话生命周期。

选择这三个案例不是为了排名，而是因为它们分别暴露出 Agent 工程的三类难题：代码修改的执行接口、代码执行的运行时隔离、动态网页的状态与动作映射。三个项目都包含模型决策与外部环境互动，但它们的工具抽象、状态载体、风险边界和完成标准不同。

1.1 证据等级与研究边界

证据等级	证据内容	本篇是否具备	能支持的判断
E1	官方架构文档与项目说明	是	项目宣称的架构与设计目标
E2	指定仓库路径的源码与接口定义	是，部分关键路径	当前所见实现中的结构与控制逻辑
E3	在受控环境中实际运行目标项目	否	不能声称项目已被本地复现
E4	生产轨迹、统计样本、故障报告	否	不能声称实际可靠性或成功率

以下分析严格将「源码可见事实」「基于代码的工程解释」「仍需实验的假设」分开。尤其注意：OpenHands 旧版架构文档与当前多仓库架构不应未经说明就混为同一个版本。

二、案例 A：SWE-agent - - 用 ACI 约束代码修改 Agent 的行动空间

2.1 任务与工程问题

SWE-agent 面向软件工程问题修复：给定问题描述及代码仓库，让模型探索文件、执行命令、修改代码，最终产生可提交的补丁。这个任务的核心不在于生成一段正确代码，而在于完成一个与仓库真实状态交互的多步闭环：定位问题、读取上下文、修改、执行验证、处理反馈、提交结果。

传统单次代码生成难以处理大型仓库中不断出现的新信息。SWE-agent 的研究贡献之一，是把模型可用的计算机接口视为设计对象，即 Agent–Computer Interface（ACI）：不是让模型直接面对无组织的终端输出，而是提供便于浏览、编辑和执行的命令及反馈格式。项目官方背景文档将 ACI 作为核心研究方向。参考：SWE-agent 项目背景。

2.2 实际源码入口及其职责

路径 / 标识	已见职责	研究价值
`sweagent/run/run_single.py`	单任务入口	任务与 Agent 如何启动
`sweagent/run/run_batch.py`	批量运行入口	任务集合与评测运行
`sweagent/agent/agents.py`	`AbstractAgent`、`DefaultAgent`、`RetryAgent`	运行循环、异常处理、轨迹与重试
`sweagent/environment/swe_env.py`	`SWEEnv`	Agent 与隔离执行环境的接口
`tools/`	工具 bundle	模型可用命令与环境能力
`sweagent/inspector/`	轨迹查看	行动与观察的可追溯性

以上入口由项目仓库的开发者概述直接列出，见：project-overview.mdc。

2.3 关键调用链：模型建议不等于命令执行

源码中的 DefaultAgent 接收 templates、tools、history_processors、model 等依赖；step() 与 run() 分离，使单步行为和完整循环能够分别控制。handle_action(step) 是行动进入环境执行的关键路径，公开源码中可以看到以下机制：

先调用 self.tools.should_block_action(step.action) 判断行动是否应阻止；
对 exit 等特殊命令处理终止语义；
通过 self.tools.guard_multiline_input(step.action) 处理输入；
调用 self._env.communicate(input=..., timeout=..., check=...) 执行命令；
捕获 CommandTimeoutError，累计连续超时并尝试中断会话；
形成 step.observation，更新执行时间与环境状态；
通过 handle_submission(step) 识别提交结果。

该路径见：agents.py / DefaultAgent.handle_action。由此可以确认，模型输出行动与环境实际执行之间存在程序控制层。但不能仅凭 should_block_action 的存在，推断它实现了完整的权限沙箱；具体允许什么、如何隔离，还需继续研究 ToolHandler、SWEEnv 与容器配置。

text

问题描述 + 仓库
    ↓
DefaultAgent：构造历史、调用模型
    ↓
行动解析 / ToolHandler
    ↓
should_block_action / guard_multiline_input
    ↓
SWEEnv.communicate（环境执行）
    ↓
Observation + 环境状态 + 轨迹
    ↓
继续决策 / 提交补丁 / 错误终止

2.4 ACI 的实现不只是工具列表

项目的工具以 bundle 组织。官方工具文档展示了 bin/ 可执行命令、config.yaml、install.sh、README.md、pyproject.toml 等结构，工具配置包含签名与说明。见：Configuring tools。

这意味着 ACI 同时涉及三个接口：给模型看的行动描述、解析器理解的命令形式、环境中真正执行的程序。三个接口任意一个不一致，都可能产生失败。例如模型学会了某条命令的语法，但执行环境缺少对应可执行文件；或者工具升级改变了输出格式，历史解析器不再能提取关键反馈。

工程启示是：工具设计不仅影响「模型能做什么」，还影响模型能否可靠地表达行动与能否理解环境返回的信息。研究工具有效性时，不能只看工具数量，应观察无效命令比例、解析失败率、重复检索、无意义编辑和修复所需的步数。

2.5 轨迹与重试：为何它们是独立的工程机制？

RetryAgent 并非简单地对一次模型请求进行 HTTP 重试。所见代码中，RetryAgent 维护尝试次数、候选配置、总成本、子 Agent、重试循环及轨迹文件。_next_attempt() 会调用环境的 hard_reset()，再准备下一次尝试；run() 中按 StepOutput.done 驱动尝试，并记录轨迹与评审结果。见同一 agents.py。

这揭示了两个不同层级的重试：

请求级重试：一次模型调用或工具调用因暂时性错误失败，可能在不改变任务状态的情况下重试。
任务级重试：整个修复尝试已经修改环境，需要恢复仓库与执行环境，再进行新尝试，并控制总成本。

如果没有环境重置，第二次尝试可能在第一次留下的修改上继续运行，无法判断新策略是否真正独立。反过来，环境重置也会增加启动时间，并可能清除本应保留的有价值状态。选择哪一种策略取决于任务语义。

2.6 失败路径与验证设计

针对 SWE-agent，至少应验证：非法命令被拒绝；命令超时后会话能被中断；补丁文件不存在时不会伪造提交；成本达到上限时不再继续；任务级重试是否真的恢复原始仓库；模型给出看似完成的回答但补丁未通过测试时如何处理。

这些是根据已见实现提出的验证项目，并非本文已经完成的目标仓库实验。

2.7 案例结论

SWE-agent 展示的关键模式是：围绕任务构造可学习、可解析、可执行、可观察的行动接口；再由程序控制环境交互与失败处理。这对于代码修改、数据分析和命令行自动化具有迁移价值。但其接口形式、沙箱约束与重试策略必须按任务风险重新设计，不能直接把终端执行权限复制到高风险业务 Agent。

三、案例 B：OpenHands - - Action–Observation 与运行时边界

3.1 项目范围与版本演进必须先辨认

OpenHands 是面向软件工程任务的开源项目。版本差异是本案例的第一项研究结论：检索到的旧架构文档将后端描述为 Agent、EventStream、Runtime 与 ActionExecutionClient 的组合；而当前仓库说明将系统划分为 OpenHands/OpenHands 前端 Agent Canvas、OpenHands/software-agent-sdk Agent Server/SDK、TypeScript Client 与 Automation 等仓库。二者反映了不同阶段的组织方式，不能将旧文件路径当成新架构的权威入口。

来源：旧版后端架构说明、当前仓库 README。

3.2 旧版架构文档中的明确职责

旧版后端文档中的结构可以归纳为：

text

用户 → 前端 → 后端
                ├── Agent / LLM Provider
                ├── EventStream
                ├── Storage
                └── Runtime 接口
                      ├── Docker Runtime
                      ├── Local Runtime
                      └── Remote Runtime
                            ↓
                      Action Execution Server
                            ↓
                    Bash / Jupyter / Browser

旧版运行时文档进一步说明：后端生成 Action，经 EventStream 传递到 Runtime，容器内的 ActionExecutor 执行操作并返回 Observation；Docker Runtime 通过客户端 - 服务端通信及 REST API 交换行动与观察。见：Runtime Architecture。

可由文档支持的事实：系统有意将 Agent 决策与执行环境隔开，Action 和 Observation 是连接两者的重要信息单元。

工程解释：这样可以让 Agent 不直接依赖某一种 shell、浏览器或执行主机；运行时可替换，也能独立处理隔离、资源和执行结果。

尚不能证明的结论：所有部署模式都具备同等级安全隔离，或旧版接口在最新 SDK 中完全不变。尤其 Local Runtime 与容器隔离的安全属性不同。

3.3 为什么运行时是关键架构边界？

对代码 Agent 而言，执行 shell 命令不是普通的信息检索。它可能修改文件、安装依赖、运行不可信脚本，甚至访问执行主机资源。把运行时作为独立模块，至少带来四个设计机会：

执行隔离：在受控环境中运行高风险操作，而不是让模型直接调用宿主机 shell。
协议隔离：把 Action 转换为环境操作，把执行结果转换为 Observation。
环境管理：管理工作目录、依赖、会话、插件和执行生命周期。
可观测性：将模型意图与环境实际结果分别记录，便于定位错误来源。

但「使用 Docker」本身并不自动保证安全。仍需核查容器权限、宿主机挂载、网络访问、密钥注入、镜像可信度、资源上限和逃逸风险。对于使用本地运行时的部署，更应明确哪些资源可被直接访问。

3.4 一条典型执行链与四种失败

根据旧版架构文档，可将典型流程解释为：

text

用户提出代码任务
→ Agent 根据历史生成 Action
→ EventStream 发布 Action
→ Runtime Client 向 Action Execution Server 请求执行
→ Bash / Browser / Python 环境执行
→ 返回 Observation
→ Agent 根据 Observation 决定继续或结束

需要分别验证四类故障：

决策错误：Agent 选择了不必要或危险的行动。
协议错误：Action 序列化、路由或解析失败。
环境错误：执行器、依赖、文件系统或网络异常。
观察错误：实际执行成功，但返回的 Observation 不完整或被截断，导致模型后续判断错误。

如果只看最终任务失败率，无法分辨这四种原因。因此 Action ID、Observation ID、执行时间、环境标识和错误类型应在轨迹中关联。

3.5 当前多仓库架构带来的新研究问题

当前仓库 README 表明：Agent Canvas 主要承担 UI、后端选择和本地开发栈编排；Agent Server/SDK 承担 Agent、工具、会话、工作空间、事件与服务端 API；Automation 负责计划任务、Webhook、运行历史与分发。来源：OpenHands 仓库。

这使得研究必须分开两个层次：

Agent 行为机制：模型、工具、工作空间、会话和运行事件如何协作。
产品/平台机制：UI、多个后端、定时任务、自动化分发和组织级运行。

本篇主要研究前者；后者是 Agent System 和 Agent Platform 的重要衔接内容。不能把 Automation Server 的调度能力当成单个 Agent 的内部 Planning 能力。

3.6 案例结论

OpenHands 最值得迁移的设计思想是：把 Agent 的行动决策与外部执行环境通过明确的 Action–Observation 契约连接起来，并将运行时当作独立工程边界。对于需要执行代码、操作文件或调用复杂工具的 Agent，这比把所有逻辑写进一个模型循环更便于治理和测试。但实际安全性必须依据具体部署模式、权限与环境配置验证。

四、案例 C：browser-use - - 动态页面状态与结构化动作的闭环

4.1 为什么浏览器 Agent 不等于普通工具调用？

浏览器任务的输入经常是不稳定的：页面加载、弹窗、导航、登录状态、元素位置、异步请求和动态 DOM 都会改变下一步可执行的动作。Agent 不能只在任务开始时列出完整步骤，往往需要在每次行动后重新观察环境。

browser-use 是研究这种闭环的合适对象。其代码把 Agent、BrowserSession、Tools、MessageManager、AgentState 等职责分开；浏览器会话同时提供事件驱动和直接 CDP/Playwright 操作能力。来源：Agent service.py、BrowserSession。

4.2 实际源码结构

路径	关键标识	已见职责
`browser_use/agent/service.py`	`Agent`	任务入口、模型、工具、状态、历史和执行设置
`browser_use/browser/session.py`	`BrowserSession`	浏览器会话与底层浏览器交互
`browser_use/tools/service.py`	`Tools`	动作定义与工具调用组织
`browser_use/tools/registry/views.py`	`ActionModel`	动作 Schema 的结构表示
`browser_use/agent/message_manager/service.py`	`MessageManager`	模型输入与消息历史
`browser_use/agent/views.py`	`AgentState`、`AgentOutput` 等	Agent 状态与结构化输出

项目仓库的开发者文档也描述了 service/views/events 的组织方式，见：CLAUDE.md。

4.3 从构造函数看 Agent 的实际配置边界

Agent.__init__ 接收 task、llm、browser_session、tools、skill_ids、sensitive_data、initial_actions、max_failures、max_actions_per_step、llm_timeout、step_timeout、fallback_llm、message_compaction、loop_detection_enabled 等参数。由此可见，浏览器 Agent 的配置不仅包含模型，还包含浏览器会话、动作数量、失败限制、上下文管理与循环检测。

这些参数不是独立的：max_actions_per_step 改变一次模型输出可能执行的动作数量；message_compaction 影响模型能看见的历史；step_timeout 影响等待页面稳定的机会；loop_detection_enabled 用于识别重复行为。单独调大某一参数可能改善部分任务，却可能增加错误动作或成本。

4.4 动态 ActionModel：工具描述如何变成模型输出约束？

源码中的 _setup_action_models() 先从 self.tools.registry.create_action_model() 生成当前动作集合的模型，再依据 flash_mode、use_thinking 等设置构造不同的 AgentOutput 类型；另有仅包含 done 动作的 DoneActionModel。来源：service.py / _setup_action_models。

这段实现非常重要，因为它表明工具注册表不仅负责实际执行，还参与生成模型可以表达的结构化行动空间。工具变化会改变模型输出 Schema，因此可能影响提示词、输出解析、动作验证和最终执行。

工程上至少存在三层：

text

工具注册表（动作定义、参数）
    ↓
ActionModel / AgentOutput（模型可表达的动作）
    ↓
模型产生结构化行动
    ↓
Tools + BrowserSession（实际执行与浏览器状态）
    ↓
ActionResult / 新页面状态 / 历史

注意：从 ActionModel 的存在只能证明有结构化动作约束；是否严格阻止越权页面访问，仍需查看工具执行、域名限制和浏览器环境策略。

4.5 BrowserSession：为什么会话状态不能当成普通上下文文本？

BrowserSession 的类说明明确区分两层：面向 Agent/Tools 的高层事件处理，以及底层 CDP/Playwright 浏览器操作。浏览器配置保存在 profile，Session 保留会话身份与运行状态。来源：session.py。

浏览器状态至少包括：当前 URL、页面 DOM/可交互元素、标签页、Cookie/登录态、滚动位置、加载状态和执行后的变化。这些状态并不完全存在于 LLM 上下文中。模型可能只看到某次观察的快照，而浏览器已经异步变化。因此需要区分：

真实环境状态：浏览器当前实际情况；
观察快照：模型这一步被提供的页面摘要或截图；
Agent 历史：先前行动、结果、错误和压缩后的记忆。

三者不一致时，Agent 可能点击错误元素、重复提交或误判完成。工程验证应检查观察到执行之间的状态变化，而不只是模型输出格式。

4.6 工具权限与高风险动作

项目工具文档展示了通过 @tools.action(...) 注册自定义动作，以及 allowed_domains 等参数；默认动作包括导航、点击、输入、上传文件、标签页管理、内容提取等。来源：AGENTS.md。

浏览器操作中的 click 并不总是无害：点击可能提交订单、发送消息、删除记录或改变权限。因此高风险动作的安全边界不能只按「工具名称」判断，还需考虑页面、目标元素、用户身份和副作用。例如同样的 click，点击“展开详情”和点击“确认付款”风险完全不同。

合理的工程做法是：将敏感动作与可读操作区分，在真正执行副作用之前进行策略检查和必要的人工确认；对于重复提交风险，需要幂等性、结果核验或明确的中止策略。这里是从任务风险推导出的工程建议，不表示已经证实 browser-use 在所有场景中实现了这些措施。

4.7 典型失败与测试设计

失败类型	示例	应观察的信号	建议测试
页面变化	元素索引失效	点击目标与观察不一致	动态 DOM 更新
等待失效	页面尚未加载	超时或空状态	慢速网络与异步加载
重复行为	多次导航同一页面	循环检测触发	无法找到目标元素
登录过期	操作返回登录页	会话状态变化	会话过期与恢复
副作用重复	重复提交表单	两次实际提交	超时后的幂等检查
上下文失真	摘要丢失关键信息	历史与当前页面冲突	长任务与消息压缩

这些是可实施的验证方案；本文未实际运行目标浏览器环境，因此不报告通过率。

4.8 案例结论

browser-use 展示的核心模式是：通过动态动作 Schema 将工具能力暴露给模型，通过 BrowserSession 保留真实环境状态，通过多轮观察 - 行动闭环适应网页变化。其可迁移价值在于一切状态快速变化的交互任务，但浏览器自动化的风险高度依赖真实页面副作用，不能只用动作格式正确来判断系统安全。

五、跨案例对照：三个项目究竟在解决什么不同问题？

维度	SWE-agent	OpenHands	browser-use
主要任务	仓库问题修复	软件工程 Agent 执行	浏览器交互任务
模型可表达行动	ACI 命令与工具约定	Action（旧版架构）	动态 ActionModel
环境接口	SWEEnv / 命令执行	Runtime / Action Executor	BrowserSession / Tools
环境状态	仓库、shell、补丁	工作空间、容器/本地运行时	页面、标签页、会话
主要反馈	命令输出、状态、补丁	Observation	页面状态、ActionResult
典型终止	提交/退出/失败	任务完成/失败	`done`/失败/取消
关键风险	错误修改、命令执行	运行时隔离、环境副作用	页面变化、重复提交
关键研究价值	ACI 与任务级重试	决策 - 执行边界	动态动作空间与观察

该表仅汇总本篇已核查的代码或官方文档中可见的机制；不构成对三个项目全部安全能力、生产可靠性或性能的排名。

5.1 共性一：所有项目都需要「模型意图 → 可信执行」转换层

模型可以建议行动，但真实副作用发生在执行层。SWE-agent 使用工具处理器和环境接口；OpenHands 通过 Runtime 执行 Action；browser-use 将结构化动作交给 Tools/BrowserSession。这说明 Agent 不能简单定义为「LLM + Prompt + Tools」：真正决定可靠性的是工具接口契约、执行权限、状态反馈和终止机制。

5.2 共性二：Observation 是决策质量的一部分

Agent 后续行为不仅依赖模型推理能力，还依赖返回给模型的环境反馈。如果 shell 输出过长被截断、浏览器快照过期、Runtime 错误没有清晰分类，即使模型能力强也可能持续失败。研究 Agent 质量时，应分别衡量模型决策、工具执行和观察质量。

5.3 共性三：终止条件必须由工程系统定义

三个项目都存在某种完成或退出机制，但「模型认为任务完成」与「外部验收标准满足」不是同一个概念。编程 Agent 的补丁提交不等于测试通过；浏览器 Agent 的 done 不等于目标业务动作成功；软件工程 Agent 的最后一条消息不等于文件系统符合预期。生产系统应在可能时引入独立验收器。

5.4 关键差异：状态的真实来源不同

代码任务的真相主要在仓库文件、测试输出和执行环境；浏览器任务的真相主要在活跃页面及后端业务状态。前者常需要可重置沙箱和补丁比较；后者更需要实时观察、页面稳定性与防重复提交。不能将同一套 Memory、Retry 和 State 设计不加修改地应用到所有任务。

六、深入技术分析：一个 Agent 执行回路应如何建模？

基于三案例，可提炼如下分析模型，而非声称三个项目采用完全相同的实现：

S_{t + 1} = T (S_{t}, a_{t}, o_{t}, e_{t})

其中 $S_{t}$ 是 Agent 内部状态， $a_{t}$ 是模型提出的行动， $o_{t}$ 是环境反馈， $e_{t}$ 是错误、预算或审批等控制事件。外部环境另有状态 $W_{t}$ ，执行动作可能改变它：

(W_{t + 1}, o_{t}) = E x e c u t e (W_{t}, a_{t}, P o l i c y_{t})

这个区分很关键：Agent 的消息历史不等于外部环境的真实状态。如果外部状态改变而内部状态未更新，就会产生失配。

6.1 五个必须独立检查的契约

Action Contract：模型输出能否被明确解析？字段、枚举、参数是否校验？
Authorization Contract：当前主体对当前资源和副作用是否真的有权执行？
Execution Contract：执行器如何处理超时、取消、重复调用与失败？
Observation Contract：返回的结果是否完整、可关联、可信且有错误分类？
Completion Contract：何时完成、何时拒绝、何时需要人工介入？

一个 Agent 即使 Action Contract 完美，也可能因为授权错误、观察失真或终止误判而失败。研究应逐层验证，而非只测最终回答。

6.2 重试的三种语义

类型	重试对象	状态处理	典型风险
模型请求重试	同一决策请求	通常保留当前环境	生成不同动作、成本上升
工具操作重试	同一外部行动	必须判断幂等性	重复提交、重复写入
任务级重试	整个任务尝试	需要重置或恢复环境	污染前次结果、成本失控

SWE-agent 的 RetryAgent 为任务级重试提供了一个具体源码观察点。对于 browser-use，重复点击或提交的副作用往往更难自动撤销。因此「重试」不能设计成单个全局整数参数。

七、真实项目研究应怎样完成工程验证？

本篇完成的是定向源码核验，没有伪造三个项目的真实运行结果。为了将其升级为「工程验证完成」，下一阶段应执行以下实验矩阵。

7.1 SWE-agent 验证计划

固定仓库提交与 issue，记录工具 bundle 和模型版本。
采集逐步 Action、Observation、命令耗时、补丁差异和最终测试结果。
对照 ACI 配置：默认工具 vs 精简工具；比较非法动作、调用次数和修复质量。
注入命令超时、无效文件路径和失败测试，检查错误处理与退出。
任务级重试时检查环境是否恢复到相同初始提交。

7.2 OpenHands 验证计划

先确定具体研究版本与仓库：旧架构 Runtime 或当前 SDK/Agent Server，不混用。
固定执行环境镜像、权限、挂载和网络策略。
跟踪 Action ID 到 Observation 的关联及错误传播。
比较容器环境与受控本地环境的行为差异，但不将本地模式视为同等级隔离。
测试命令失败、工作空间重置、执行器不可达、任务取消。

7.3 browser-use 验证计划

搭建受控本地网页，不使用真实账户或真实支付。
测试 DOM 改变、异步加载、弹窗、标签页切换与会话过期。
对照不同 max_actions_per_step、历史压缩和循环检测设置。
用可观测的服务端计数器验证「点击一次」与「实际提交一次」是否一致。
统计误点击、重复提交、完成误判和工具错误分类。

7.4 指标与数据要求

对每个项目，应同时记录任务成功率、合规率、工具失败率、错误恢复率、平均/分位延迟、调用次数、费用与人工介入次数。必须保存逐任务结果与轨迹，不仅保留总体均值。对于模型随机性，应重复实验并提供不确定性范围；对于不同项目，不应在任务集不同的情况下直接比较成功率。

八、配套代码：不是模拟 Agent，而是「工程契约审查器」

本版不再把人为设计的模拟任务成功率当成案例主体。配套研究包可下载：05-Agent-Case-Studies-v2.0.zip（内含 case_contract_audit.py、sample_trace.jsonl 等）。审查器用于把真实项目的执行轨迹结构转换为统一的审查视图，检查动作 - 观察关联、终止状态、预算、执行授权标记和潜在重复副作用。它是供后续真实复现时复用的研究工具，输入使用明确的通用 JSONL 契约；需要为不同项目分别编写轨迹转换适配器。

运行：

bash

python3 case_contract_audit.py --test
python3 case_contract_audit.py sample_trace.jsonl

本地确定性单元测试 10 项全部通过；示例审查输出 passed: true。注意示例轨迹不是三个开源项目的真实运行记录。

输入示例：

json

{"run_id":"r1","seq":1,"event":"action","action_id":"a1","name":"read_file","authorized":true,"side_effect":false}
{"run_id":"r1","seq":2,"event":"observation","action_id":"a1","ok":true}
{"run_id":"r1","seq":3,"event":"finish","status":"completed","verified":true}

审查器检查：

每个 action ID 是否唯一；
每个 observation 是否能关联到一个 action；
是否存在没有返回结果的行动；
是否出现未授权行动或未验证完成；
同一 idempotency_key 是否出现重复的副作用调用；
工具调用数量是否超过配置预算。

审查器不能推断真实项目的全部安全性：authorized、verified 必须由可信适配器或独立验证器提供，不能直接采信模型自己写下的布尔值。其作用是让后续真实项目实验具备一致的审计字段与可自动验证的不变量。

九、研究产物如何沉淀进知识库？

完成案例研究后，至少产出三类不同知识：

项目事实档案：项目、版本、源码路径、调用链、关键配置、运行条件、失败轨迹及证据等级。它必须允许别人定位到同一份实现。

工程模式条目：将项目具体实现抽象为适用条件、机制、收益、代价与验证方法。例如：

对可能修改外部环境的 Agent，应在模型决策与环境执行之间建立可审计的行动契约与可信执行层；当任务允许重复执行时，需显式定义状态恢复与幂等边界。

未解决问题与验证任务：哪些结论仍是推断？哪些版本差异尚未核查？哪些机制只在文档中出现而未完成实测？这类内容应进入研究待办，而不是被包装为已验证结论。

9.1 可迁移工程原则

模型不是执行权限的最终裁决者。 真实行动必须经过可信执行器与策略边界。
观察质量决定闭环质量。 工具返回内容、错误分类与状态快照应作为工程接口设计。
环境状态必须独立于对话历史管理。 文件系统、浏览器、会话与业务状态不能只靠 Prompt 记忆。
完成需要外部可验证条件。 模型发出 done 不等于任务已成功。
重试必须考虑状态与副作用。 模型请求、工具调用和整个任务重试不能混为一谈。
比较必须控制任务条件。 不能因三个项目面向不同任务就直接比较性能优劣。

十、质量审核与后续研究计划

质量要求	本版状态	尚需完成
至少三个真实项目	已满足	可扩展更多任务类型
官方文档与真实源码定位	部分满足	固定提交 SHA、补充更多调用点
关键控制流与接口分析	已覆盖主要路径	用调用图与断点进一步核验
失败路径研究	已提出可验证机制与测试	执行真实故障注入
可运行研究工具	已提供	增加真实项目轨迹适配器
真实项目本地复现	未完成	安装、锁定依赖并运行
真实模型对照评测	未完成	固定数据集、多次运行、统计
生产级可靠性结论	不作声称	需生产数据与安全审计

本版相比 v1.1 的关键提升，是让真实工程项目与源码机制成为文章主体，并明确哪些事实已核查、哪些是工程解释、哪些需要实验。它可以作为知识库的「真实案例源码研究版」，但按照严格质量门槛，只有完成固定版本的本地复现和实证测试，才能标记为「工程验证完成」。

本专题与同章 Agent Design、Agent Configuration、Agent Implementation、Agent Testing 形成闭环：前四篇提供任务契约、配置、实现与测试方法；本篇用真实开源项目检验这些方法在工程中的落点。完成本章后，可进入 Agent System 研究运行基础设施与协作架构。

参考来源（按项目分组）

引用说明： 上述链接指向官方项目仓库及其 main 分支，属于可导航的研究入口，不是不可变的版本锁定证据。后续复现应保存具体 commit SHA、源文件快照、依赖锁文件和运行清单。文中的源码描述对应本次查阅到的页面内容；未来版本可能调整结构与 API。

05 · 如何通过实际项目研究 Agent 的工程实现？ - Case Studies ​

一、为什么必须重写：从「案例研究方法」转向「真实项目研究」 ​

1.1 证据等级与研究边界 ​

二、案例 A：SWE-agent - - 用 ACI 约束代码修改 Agent 的行动空间 ​

2.1 任务与工程问题 ​

2.2 实际源码入口及其职责 ​

2.3 关键调用链：模型建议不等于命令执行 ​

2.4 ACI 的实现不只是工具列表 ​

2.5 轨迹与重试：为何它们是独立的工程机制？ ​

2.6 失败路径与验证设计 ​

2.7 案例结论 ​

三、案例 B：OpenHands - - Action–Observation 与运行时边界 ​

3.1 项目范围与版本演进必须先辨认 ​

3.2 旧版架构文档中的明确职责 ​

3.3 为什么运行时是关键架构边界？ ​

3.4 一条典型执行链与四种失败 ​

3.5 当前多仓库架构带来的新研究问题 ​

3.6 案例结论 ​

四、案例 C：browser-use - - 动态页面状态与结构化动作的闭环 ​

4.1 为什么浏览器 Agent 不等于普通工具调用？ ​

4.2 实际源码结构 ​

4.3 从构造函数看 Agent 的实际配置边界 ​

4.4 动态 ActionModel：工具描述如何变成模型输出约束？ ​

4.5 BrowserSession：为什么会话状态不能当成普通上下文文本？ ​

4.6 工具权限与高风险动作 ​

4.7 典型失败与测试设计 ​

4.8 案例结论 ​

五、跨案例对照：三个项目究竟在解决什么不同问题？ ​

5.1 共性一：所有项目都需要「模型意图 → 可信执行」转换层 ​

5.2 共性二：Observation 是决策质量的一部分 ​

5.3 共性三：终止条件必须由工程系统定义 ​

5.4 关键差异：状态的真实来源不同 ​

六、深入技术分析：一个 Agent 执行回路应如何建模？ ​

6.1 五个必须独立检查的契约 ​

6.2 重试的三种语义 ​

七、真实项目研究应怎样完成工程验证？ ​

7.1 SWE-agent 验证计划 ​

7.2 OpenHands 验证计划 ​

7.3 browser-use 验证计划 ​

7.4 指标与数据要求 ​

八、配套代码：不是模拟 Agent，而是「工程契约审查器」 ​

九、研究产物如何沉淀进知识库？ ​

9.1 可迁移工程原则 ​

十、质量审核与后续研究计划 ​

参考来源（按项目分组） ​

SWE-agent ​

OpenHands ​

browser-use ​

05 · 如何通过实际项目研究 Agent 的工程实现？ - Case Studies

一、为什么必须重写：从「案例研究方法」转向「真实项目研究」

1.1 证据等级与研究边界

二、案例 A：SWE-agent - - 用 ACI 约束代码修改 Agent 的行动空间

2.1 任务与工程问题

2.2 实际源码入口及其职责

2.3 关键调用链：模型建议不等于命令执行

2.4 ACI 的实现不只是工具列表

2.5 轨迹与重试：为何它们是独立的工程机制？

2.6 失败路径与验证设计

2.7 案例结论

三、案例 B：OpenHands - - Action–Observation 与运行时边界

3.1 项目范围与版本演进必须先辨认

3.2 旧版架构文档中的明确职责

3.3 为什么运行时是关键架构边界？

3.4 一条典型执行链与四种失败

3.5 当前多仓库架构带来的新研究问题

3.6 案例结论

四、案例 C：browser-use - - 动态页面状态与结构化动作的闭环

4.1 为什么浏览器 Agent 不等于普通工具调用？

4.2 实际源码结构

4.3 从构造函数看 Agent 的实际配置边界

4.4 动态 ActionModel：工具描述如何变成模型输出约束？

4.5 BrowserSession：为什么会话状态不能当成普通上下文文本？

4.6 工具权限与高风险动作

4.7 典型失败与测试设计

4.8 案例结论

五、跨案例对照：三个项目究竟在解决什么不同问题？

5.1 共性一：所有项目都需要「模型意图 → 可信执行」转换层

5.2 共性二：Observation 是决策质量的一部分

5.3 共性三：终止条件必须由工程系统定义

5.4 关键差异：状态的真实来源不同

六、深入技术分析：一个 Agent 执行回路应如何建模？

6.1 五个必须独立检查的契约

6.2 重试的三种语义

七、真实项目研究应怎样完成工程验证？

7.1 SWE-agent 验证计划

7.2 OpenHands 验证计划

7.3 browser-use 验证计划

7.4 指标与数据要求

八、配套代码：不是模拟 Agent，而是「工程契约审查器」

九、研究产物如何沉淀进知识库？

9.1 可迁移工程原则

十、质量审核与后续研究计划

参考来源（按项目分组）

SWE-agent

OpenHands

browser-use