Code as Agent Harness: Toward Executable, Verifiable, and Stateful Agent Systems

Paper: arXiv:2605.18747 Code: YennNing/Awesome-Code-as-Agent-Harness-Papers（官方 companion repo：文献清单、网页与图资源；不是可执行实现） Code reference: main @ 06b0d447 (2026-05-20)

1. Motivation（研究动机）

这篇 102 页 survey 的核心动机是：LLM agent 的瓶颈已经不只是“模型会不会写代码”，而是“模型被放在什么样的可执行、可检查、可持久化的软件环境里工作”。传统 code-generation 视角把 code 当作最终输出：模型写一段程序，评测器检查是否正确。论文指出，在真实 agentic systems 中，code 越来越像 agent 的 operational substrate：它承载推理过程、动作接口、环境状态、执行反馈、测试、日志、权限、记忆和多 agent 协作，而不仅是任务结束时交付的 artifact。

现有研究的断裂点在于，很多工作分别讨论 Program-of-Thought、tool use、software engineering agent、GUI agent、robot policy、multi-agent coding、sandbox、memory、test feedback，但缺少一个把它们放进同一系统层的框架。论文借用“agent harness”这个概念：harness 是包在 LLM 外面的软件层，包括 tools、APIs、sandboxes、memory、validators、permission boundaries、execution loops 和 feedback channels；它把无状态模型变成能长期执行任务的 agent。本文进一步强调，agent 自己创建、执行、观察、修改和持久化的 code artifact，是这个 harness 中最关键但相对缺少统一讨论的一层。

为什么这个问题值得研究？因为真实 agent 的可靠性通常不是靠一次生成决定的，而是靠闭环：计划下一步、读写 repo 或环境、运行命令、观察错误、保存状态、触发验证、必要时回滚或请求人类批准。如果把 code 只看成 output，就会漏掉 agent 的实际控制面；如果把 harness 只看成“工具列表”，又会漏掉 code 的三个独特属性：executable（可以运行并得到外部反馈）、inspectable（中间状态可被读取、审计和复用）、stateful（任务进展能以文件、repo、trace、test、memory 的形式持久存在）。这也是论文标题中 executable、verifiable、stateful 的来源。

Figure 1 解读：这张 taxonomy 图把全文组织成三层。第一层 Harness Interface 解释 code 如何把模型连接到 reasoning、acting 和 environment modeling；第二层 Harness Mechanisms 解释 planning、memory、tool use、PEV control 和 adaptive optimization 如何让 agent 在长程任务中保持可靠；第三层 Scaling the Harness 解释多个 agent 如何围绕 shared code artifacts、tests、logs、blackboards 和 workflow states 协作。图的重点不是列一个 agent 工具箱，而是说明 code 正在成为 agent 系统的“运行介质”。

2. Idea（核心思想）

核心思想可以概括为：code 不只是 LLM 生成的程序，而是 agent harness 的可执行、可检查、可持久化中介层。模型通过 code 外化推理、发起动作、表示环境、保存状态、接受执行反馈，并把这些 artifact 交给 tests、validators、human review 或其他 agents 继续处理。这个视角把“agent 能力”从模型内部推理扩展到模型—代码—工具—环境—反馈构成的完整闭环系统。

论文的主要创新不是提出一个新模型或新 loss，而是提出一个统一 taxonomy：先看 code 如何作为 interface 进入 agent loop；再看 planning、memory、tool use、PEV loop、telemetry 和 harness optimization 如何把 interface 变成可靠机制；最后看 shared code artifacts 如何支撑 multi-agent coordination、review、verification 和 convergence。这个 taxonomy 覆盖 450+ cited works，把过去分散在 code reasoning、software agents、GUI/OS automation、embodied agents、scientific discovery、personalization 和 multi-agent systems 中的技术放到同一张系统图里。

与普通 code-generation survey 的根本差别在于，本文不把“程序正确性”当作唯一终点，而把“程序作为 agent 所处世界的一部分”当作研究对象。以 SWE-agent / OpenHands / Claude Code 这类系统为例，关键并不是模型一次性生成 patch，而是 harness 是否能提供 repo evidence、shell、tests、logs、permission tier、memory summary、review gate 和 rollback path。以 Voyager / CaP / GUI agents 为例，code 也不是最终答案，而是可执行 policy、skill library 或 DOM/API action interface。

3. Method（方法）

3.1 Overall framework：三层 code-as-harness taxonomy

论文的整体方法是 survey taxonomy construction，而不是训练算法。它把“code as agent harness”拆成三层，并在每层内部继续细分出机制、代表方法和开放问题。为了便于理解，可以把一个 code-centric agent loop 记成： ${\text{state}}_{t+1}=V(E(P(\text{goal},{\text{memory}}_t,{\text{code}}_t,\text{tools}))),$ 其中 $P$ 表示 planning / orchestration，把 goal 转成可执行意图；$E$ 表示 sandboxed execution / tool action，让 code 或工具改变环境；$V$ 表示 verification / sensors，用 tests、linters、traces、human review 等检查新状态。这个式子是笔记中的概念化记法，不是论文给出的 formal loss；论文强调的是这种 closed-loop harness view。

3.2 Harness Interface：code 作为 reasoning、acting、environment modeling 的接口

Figure 2 解读：这张图解释 interface 层：code 把 LLM 的自然语言意图变成可执行结构。左侧是 reasoning substrate，例如 Program-of-Thought / PAL 把中间计算交给 Python interpreter；中间是 action interface，例如 robot policy、GUI command、tool call、shell command；右侧是 environment representation，例如 repository state、execution trace、simulator、test suite 和 structured world model。三者共同说明：code 的价值不是语法本身，而是它能被执行、被检查、被持久化。

Code for Reasoning

Code for Reasoning 指 model 把推理过程外化成程序，由 interpreter、symbolic solver 或 runtime trace 给出反馈。Program-delegated reasoning 的代表是 Program-of-Thought / PAL：LLM 负责构造逻辑，具体算术、搜索或状态更新交给程序执行，从而减少纯自然语言 Chain-of-Thought 的计算错误。Formal verification 和 symbolic reasoning interface 则把 graph-of-thought、symbolic planner、SAT/SMT-like checks 或 visual control-flow representation 纳入 harness，让中间状态能 branch、merge、reuse 和 verify。Iterative code-grounded reasoning 进一步把 execution trace 当作训练或修正信号，使 reasoning 不是一次性文本输出，而是生成—执行—观察—修复的轨迹。

Code for Acting

Code for Acting 关注 code 如何把高层意图落成外部世界动作。这里的 code 不是最终答案，而是 action policy：在 embodied setting 中可能是 robot control script、behavior tree、API sequence；在 GUI/OS setting 中可能是 DOM event、accessibility action、adb command、Playwright script；在 software setting 中可能是 shell commands、file edits、test invocation。论文把这部分分成 grounded skill selection、programmatic policy generation 和 lifelong code-based agents。前者从已有 skill/API 中选择可行动作；中者直接生成可执行 policy；后者把生成过的 policy 和 skill library 持久化，让 agent 随任务积累能力。

Code for Environment Modeling

Code for Environment Modeling 把环境本身表示成可执行或可检查的程序状态。Structured world representations 用 repo structure、knowledge graph、scene graph 或 formal state 表示环境对象与约束；execution-trace world modeling 从 runtime traces 中学习或预测状态转移；code-grounded evaluation environments 把 benchmark 变成交互式 runtime，例如 InterCode / SWE-bench / CRUXEval 类环境，其中 action 是 code 或 command，observation 是 execution feedback，success 由 tests 或 validators 给出；verifiable environment construction 则强调构造能被 oracle / tests / simulator 检查的任务世界。

Figure 3 解读：这张 roadmap 按时间和角色列出 interface 层的代表工作。它展示了一个演化趋势：早期 code 主要服务数学/逻辑 reasoning；随后进入 robot、GUI、tool-use action；再进入 repository、simulator、test suite 和 execution traces 构成的 environment model。也就是说，code 在 agent 系统中的角色从“帮模型算东西”扩展到“定义模型能看见什么、能做什么、如何被检查”。

3.3 Harness Mechanisms：planning、memory、tool use 与 PEV control

Figure 4 解读：这张图把机制层分成 planning、memory/context、tool use、verification/control 和 adaptive harness engineering。它的重点是：一旦 code 进入 agent loop，问题就不再是单次生成正确程序，而是如何治理一个会不断读写状态、调用工具、运行测试、压缩上下文、修复失败的长程系统。

Planning as harness control

Planning 在这里不是模型内部“想一想”，而是 harness artifact：它把用户目标转成下一次状态转移的 contract，包括要读哪些文件、允许改哪些组件、保持哪些 invariants、如何验证、哪些操作需要 rollback 或 human approval。论文区分四类 planning：linear decomposition planning 把任务拆成串行步骤；structure-grounded planning 用 dependency graph、repo graph、circuit graph 或 knowledge graph 约束行动顺序；search-based planning 用 tree search / MCTS / multiple candidate trajectories 分配 inference-time compute；orchestration-based planning 通过角色分工、阶段路由和 feedback loop 组织多 agent 或多模块系统。

Figure 5 解读：这张图把 planning 从简单 step list 推到更系统的 harness control。linear plan 适合短任务，但容易在失败后卡死；graph-grounded plan 能利用代码结构；search-based plan 能保留多条候选路径；orchestration-based plan 则把 planning 变成 workflow topology 的一部分，例如 manager/planner/coder/tester/reviewer 的流转。

Memory and context engineering

Memory 的核心问题不是“能存多少 token”，而是“哪些状态应该留在 active context，哪些应该 offload 到 durable artifacts”。论文把 memory 分为 working memory、semantic memory、experiential memory、long-term memory、multi-agent memory，以及跨类别的 context compaction / state offloading。Working memory 保存当前任务轨迹中的关键失败、文件、约束和下一步；semantic memory 检索 repo-specific evidence，如 class/function/config/docs/issue；experiential memory 复用跨任务失败案例和 repair trajectory；long-term memory 解决压缩失真、漂移和长期检索治理；multi-agent memory 则让 planner、coder、tester、reviewer 共享意图、证据和状态。

Figure 6 解读：这张图展示 memory 不等于一个 vector DB。对 code agent 来说，memory 包括当前 shell/test 状态、repo 语义证据、过去调试经验、长期任务状态、多 agent shared memory 和 context compaction。真正困难的是 memory governance：如何保证被压缩或检索出的状态仍然忠实、可验证、可追踪。

Tool use as action and observation layer

Tool use 是 harness 的 action/observation 层。Function-oriented tools 补足 API、library、documentation 等模型知识缺口，减少 hallucinated API；environment-interaction tools 让 agent 真正进入 repo、shell、browser、IDE 或 simulator；verification-driven tools 把 compiler、tests、linters、static analyzers、runtime traces 当作 deterministic sensors；workflow-orchestration tools 负责什么时候检索、什么时候编辑、什么时候测试、什么时候升级权限或请求人类批准。论文的判断是：tool use 正从“给模型加 API”演化为“用工具治理一个可执行闭环”。

Figure 7 解读：这张图把 tools 按边界和用途分层。单个 API search 只能减少知识缺口；repo/shell/browser tools 让 agent 能行动；tests/linters/trace tools 让行动可被检查；workflow tools 决定这些能力如何串成闭环。对于真实 agent，最后一类往往决定可靠性，因为它控制权限、上下文、重试和停止条件。

Plan-Execute-Verify loop

PEV loop 是论文最像“控制系统”的部分。Plan 阶段外化目标、scope、validation criteria 和 rollback point；Execute 阶段在 sandbox / permission tier 中执行状态转移；Verify 阶段用 deterministic sensors 和 human-review gates 检查结果。论文强调 verification 不只是末尾打分，而是 repair、reflection、termination 和 escalation 的证据来源。失败的 test trace、lint warning、security alert、coverage gap 或 runtime exception 应该决定 agent 是继续本分支、检索新证据、重写 patch、转交 reviewer，还是停止。

Figure 8 解读：这张图把 debugging 重新解释为 harness-level control。传统 debugging 像是模型犯错后再读错误；PEV 视角下，计划、沙盒执行、权限边界、测试、静态分析、human approval 都是同一个控制回路的组件。它也解释了为什么 agent harness 需要 read-only / sandbox-edit / full-access 等权限层，而不是给模型一个无限制 shell。

Agentic Harness Engineering (AHE)

AHE 把 harness 本身当作可优化对象。Prompt engineering 改 instructions；context engineering 改 evidence packing；AHE 则改 tool schema、planning artifact、memory policy、retrieval strategy、sandbox config、verification sensor、permission tier、routing rule、multi-agent workflow 和 human-review gate。论文提出 deep telemetry 作为 AHE 的基础：记录 prompts、retrieved context、token/cost、tool latency、tool args、permission requests、edited files、sandbox snapshots、commands、test results、stack traces、branch decisions、rejected alternatives、human interventions 和 final outcome。Evolution Agent 可以基于这些 traces 诊断失败、提出 harness mutation、在 held-out tasks 或 replayed traces 上验证，再用 regression suite 和 HITL gate 推广。

Figure 9 解读：这张图展示了“优化 agent”不是只调 prompt。Telemetry 先把 agent 失败定位到 retrieval、memory、tool schema、sandbox、permission、verification 或 workflow；Evolution Agent 再提出 harness change；最后需要用 regression tests 和 human governance 防止 harness 自我修改引入更大风险。这里的核心风险是 regression-free improvement：不能为了解决新任务 silently break 旧任务。

3.4 Scaling the Harness：multi-agent orchestration over shared code

单 agent 在复杂代码任务中会遇到三个限制：context window 容不下完整 codebase、长历史和 execution trace；一个 generalist 同时做 planning/synthesis/testing/review/debugging 效率低；缺少 shared state 时，任务一长就容易发生隐性状态分叉。论文因此把 multi-agent systems 看作 code-centric harness 的扩展：多个角色围绕 shared artifacts 协作，包括 source files、diffs、tests、logs、schemas、blackboards、review comments 和 workflow states。

Figure 10 解读：这张图显示 multi-agent harness 的基本模式：manager/planner/coder/reviewer/tester/security/human 等角色不只是互相聊天，而是围绕同一个可执行状态工作。代码、测试、日志和环境反馈提供客观共同参照；如果只有 message passing，没有共享程序状态和验证信号，multi-agent 很容易变成多轮主观讨论。

Role specialization、interaction modes 和 topology

论文把 multi-agent code systems 的角色分成 program synthesis agents、program understanding agents、verification agents、execution agents 和 planning agents。Interaction modes 包括 collaborative synthesis、critique and repair、adversarial validation、reasoning debate 等。Workflow topology 则决定谁和谁通信、按什么顺序、循环几次：pre-defined heuristic topology（waterfall、iterative、hierarchical、star）容易实现但僵硬；objective-driven / adaptive topology 会根据任务状态、失败信号或 verifier feedback 动态调整 agent 路由。

Figure 11 解读：这张 roadmap 把 multi-agent 扩展拆成四类问题：workflow collaboration、shared repository state、execution verification 和 adaptive coordination。它说明“多 agent”不是数量更多，而是 harness 要解决状态同步、冲突检测、验证收敛和拓扑选择。图中纵向结构也提醒读者：如果没有 shared harness representation，多 agent 系统只能靠消息历史维持一致性。

Shared-harness synchronization 和 convergence

Shared-harness synchronization 的难点是让多个 agent 对程序状态有一致视图。最简单的是 sequential handoff：每个 agent 只接前一个 artifact；更复杂的是 shared blackboard、parallel branches with merge、structured context scheduling、hierarchical memory 和 agent pool scaling。论文进一步提出 shared code-centric harness substrate：不仅保存文件，还要保存 read set、write set、assumptions、version dependencies、verifier obligations 和 conflict policy。Convergence 也不应只靠“大家同意”或迭代次数，而应由 executable substrate 提供的 signals 决定：test-gated correctness、security convergence、performance convergence、score-based convergence、consensus convergence 和 implicit convergence。

3.5 Applications and open problems

Figure 12 解读：这张图把 code-as-harness 放进应用场景。Code assistants 最直接，因为 repo、tests、CI 和 PR review 天然是 code harness；GUI/OS agents 面对的是 DOM、accessibility tree、event loop 和 rendered state；embodied agents 用 policy code、skills 和 simulator/robot feedback 连接物理世界；scientific discovery agents 把 hypothesis、experiment、analysis 和 reporting 变成可执行 pipeline；personalization agents 则把用户偏好和反馈变成可编辑、可治理的 state artifact。

开放问题主要有七类。第一，harness-level evaluation：只看 final task success 不足以区分 base model、retrieval、tool schema、retry policy、sandbox 和 verifier 的贡献。第二，oracle adequacy：可执行反馈可能给人虚假的正确感，unit tests、GUI checkers、scientific scripts 和 robot simulators 都可能不完备。第三，self-evolving harnesses without regression：harness 自动优化必须有 regression suite 和审计。第四，transactional shared program state：多 agent 协作需要读写集、版本、假设和冲突策略，而不只是共享聊天记录。第五，HITL safety/accountability：部署、网络、credential、finance、healthcare、robot control 等高风险动作必须成为 harness state 和 approval gate。第六，multimodal code-harness systems：GUI screenshot、depth、tactile、plot、microscope image 等非文本状态需要和 code/test 共同对齐。第七，harness engineering science：需要能暴露长程失败、可审计 telemetry 和可比较设计原则的 benchmark。

3.6 Code search and companion-repo mapping

代码搜索结论：arXiv abstract 和 project page 都指向官方 GitHub YennNing/Awesome-Code-as-Agent-Harness-Papers；该 repo 是 companion reading-list / figure repository，包含 README.md、figs/*.png、MISSING_URLS.md 等，不包含模型训练、agent runtime、benchmark runner 或可执行实现。因此本文没有 released implementation 可以用于训练配置、loss、reward、agent loop 或 paper-vs-code formula 对齐；笔记不写基于实现的伪代码，也不声称 repo 是 executable implementation。代码搜索日志保存在本次 scratch dir 的 code_search_log.md。

Code reference: main @ 06b0d447 (2026-05-20) — official companion repo only; no executable implementation found

Paper Concept	Source File	Key Class/Function
Overall taxonomy / citation / project links	README.md	# Awesome Code as Agent Harness Papers, badges, BibTeX block
Harness Interface literature organization	README.md	## 🧩 Harness Interface, Code for Reasoning, Code for Acting, Code for Environment Modeling headings
Harness Mechanisms literature organization	README.md	## 🛠️ Harness Mechanisms, planning, memory, tool usage, feedback-guided debugging headings
Scaling multi-agent harness taxonomy	README.md	## 👥 Scaling the Harness: Multi-Agent Code-Centric Systems and subheadings for roles, topology, synchronization, convergence
Application taxonomy	README.md	## 🚀 Applications and Emerging Fields, code assistants, GUI/OS, embodied, scientific, personalization headings
Companion visual assets	figs/*.png	overview / harness_interface / harness_mechanism / scaling_harness / applications images for the project page

论文公式与 released code 实现差异：本文是 survey，几乎没有算法 loss 或 training recipe；官方 GitHub 又不是实现仓库，所以不存在可逐项 grep 的 loss/code gap。需要显式记录的 gap 是 paper-vs-repo role gap：paper/arXiv 把 GitHub 作为 companion artifact 发布，但 repo 内容是文献 taxonomy 与图资源，不是 agent harness implementation。复现或工程实现不能从该 repo 期待训练脚本、agent loop、sandbox 或 verifier 代码。

4. Experimental Setup（实验设置）

本文没有传统意义上的实验设置：没有新模型训练、没有 baseline comparison、没有 benchmark leaderboard、没有 reported accuracy / pass rate / ablation 指标。它是 survey / position-style taxonomy paper。可被视为“设置”的部分是文献组织范围：截至 2026 年，论文围绕 450+ cited works，把 code-centric agentic AI 分成 Harness Interface、Harness Mechanisms、Scaling the Harness 三层，并在应用层覆盖 coding assistants、GUI/OS agents、autonomous embodied agents、scientific discovery agents 和 personalization / recommendation agents；摘要和网页还把 DevOps、enterprise workflows 等放入更广义应用范围。

因此，本节按 survey 口径记录：

• Data / corpus：论文引用并组织 450+ works；PDF 102 pages；arXiv primary categories 为 cs.CL 与 cs.AI；官方 project page 与 GitHub companion repo 提供 taxonomy / reading-list 入口。
• Baselines：无传统 baselines。论文对比的是研究范式：code-as-output / tool-use-as-addon / message-passing MAS 等旧视角，相对本文的 code-as-harness 视角。
• Metrics：无数值指标。论文反复强调 future harness evaluation 不应只看 final task success，还应评估 intermediate state、trace quality、repair attempts、oracle adequacy、safety gates、shared-state consistency 和 regression-free improvement。
• Artifacts：arXiv PDF/source、project webpage、官方 GitHub reading list；没有 released executable implementation。

5. Experimental Results（实验结果）

因为本文是 survey，没有实验表格结论；“结果”主要是 taxonomy findings 和 research agenda。最重要的结论是：code 在 agent 系统中的角色已经从 final output 演化为 harness substrate。它可以作为 reasoning trace、action policy、environment representation、memory artifact、tool boundary、verification target、shared multi-agent state 和 harness-optimization object。这个结论把许多看似不同的研究方向连接起来：Program-of-Thought、Voyager skill library、SWE-bench-style repo environment、OpenHands/SWE-agent tool loop、GUI/OS automation、scientific discovery pipeline、multi-agent coder-reviewer-tester workflow，都可以被解释为不同层级的 code harness。

第二个结论是，可靠 agent 的关键不是“工具越多越好”，而是工具、记忆、权限、执行和验证是否形成可治理闭环。PEV loop 给出一个清晰的系统模式：plan 必须变成可检查 contract；execute 必须在 sandbox 和 permission tier 中发生；verify 必须通过 deterministic sensors / human review 产生可用于修复或停止的证据。这个视角也解释了为什么现代 agent 工程越来越重视 AGENTS.md、hooks、test gates、context compaction、scratch files、review packets、CI logs、rollback 和 audit trail。

第三个结论是，多 agent 的难点不在“让更多模型说话”，而在 shared harness state。Planner、coder、tester、reviewer、security agent 和 human 需要围绕同一个 executable substrate 协作，并且每次修改都应带有读写集、版本依赖、验证义务和冲突策略。否则，多 agent 只是把单 agent 的上下文漂移和状态不一致放大。论文把 shared code-centric harness substrate 作为下一代多 agent intelligence 的核心抽象，这一点对 repo-level software agents 尤其重要。

最后，论文的开放问题很实际：evaluation 需要超越最终成功率；verification oracle 必须处理不完备 tests 和语义正确性；harness 自动优化不能破坏已有能力；multi-agent state 需要 transaction / conflict resolution；高风险动作需要 HITL safety 和 accountability；多模态 agent 需要把 screenshot、sensor、plot、robot state 等和 code/test 对齐；整个领域需要从 prompt tricks 走向可测量、可审计、可复现的 harness engineering science。对于工程读者，这篇 paper 的最大价值是给了一个诊断 checklist：当 agent 失败时，不要只问“模型不够强吗”，还要问 planning artifact、memory boundary、tool schema、permission tier、sandbox、verifier、telemetry、review gate 和 shared state 哪一层出了问题。