AgentSPEX：用 YAML 声明式语言指定与执行 LLM Agent 工作流 AgentSPEX: An Agent SPecification and EXecution Language
提出 YAML 声明式 Agent 工作流语言，统一子模块抽象与显式上下文管理
前置知识
ReAct 范式
ReAct 让 LLM 在单一系统提示下，以推理+工具调用的循环交替方式自主决定下一步行动，依赖模型的内在能力处理控制流与中间状态。流程对模型不透明，难以复现和调优。
AgentSPEX 的对照基线之一就是 ReAct。理解 ReAct 的反应式流程才能体会为什么把工作流从 prompt 中抽离、由解释器强制执行会带来系统性提升。
Model Context Protocol (MCP)
MCP 是连接 LLM 与外部工具的标准化协议，模型以结构化消息描述工具调用，客户端负责实际调用并回传结果。AgentSPEX 的执行器在每轮迭代中调用 MCP 客户端执行工具。
理解 MCP 才能明白 AgentSPEX 如何集成 50+ 工具并以统一接口处理多轮 tool-use，这是构建可复用 Agent 系统的关键。
Mustache 模板
Mustache 风格模板用双花括号如 {{variable}} 在文本中占位，运行时由上下文变量替换。AgentSPEX 用它让 step 指令引用上下文变量和 save_as 输出，实现数据流。
Mustache 是 AgentSPEX 中上下文变量流动的语法基础，读懂它才能理解工作流的参数传递与子模块调用机制。
检查点与回放
检查点记录工作流执行的完整状态，包括已完成步骤 ID、上下文变量、指标、沙盒状态等，以便中断后从断点恢复。回放则可选择性加载先前 trace 的前 N 步并继续执行。
AgentSPEX 的耐久性机制依赖这两个概念，理解它们的工作方式对把握论文如何支持长时任务稳定运行至关重要。
Docker 沙盒
沙盒通过容器化提供隔离的执行环境，内置浏览器、文件系统与代码执行能力，限制 Agent 的破坏半径。AgentSPEX 每个工作流运行在独立 Docker 沙盒中并支持会话再连接。
沙盒是 Agent Harness 安全性与可恢复性的物理基础，理解其对工具执行隔离的作用，才能体会 harness 比裸 ReAct 多的工程保障。
显式上下文管理
显式上下文管理指由开发者直接控制每一步接收的对话历史与变量，避免反应式框架下历史无脑累积造成的「上下文腐烂」问题。AgentSPEX 通过 task/step 抽象与 save_as 变量实现。
论文在 ELAIPBench 等长上下文任务中取得显著提升的关键原因即为显式上下文管理。理解这一概念对评估作者归因的解释至关重要。
研究动机
现有 LLM Agent 框架普遍存在两类痛点。第一类以 ReAct 等反应式提示范式为代表：在单一系统提示中塞入任务描述，让模型自身决定工具调用顺序，依赖模型的内部推理能力承担控制流与状态管理。这种范式在长时任务、需要分支与迭代的场景下表现不稳定，且复现性和可控性差，论文中以 ELAIPBench 上 ReAct 比 CoT 反低 3.4% 为佐证。第二类以 LangGraph、DSPy、CrewAI 等编排框架为代表：虽然提供状态图、优化 pipeline、多 Agent 协作等结构，但工作流逻辑与 Python 强耦合，陡峭的学习曲线阻碍非程序员修改与分享。论文进一步点出黑盒框架如 Codex CLI skills 与 Claude Code skills 虽然上手快，但把控制流、状态、执行语义完全交给模型，可复现性与可控性进一步恶化。共同的下游问题是：长程任务中的「上下文腐烂」，对话历史无脑累积导致性能下降，而当前框架均缺乏原生机制应对。
本文的目标是本文的核心目标是设计一种声明式的 Agent 规范与执行语言 AgentSPEX，使用人类可读的 YAML 语法把工作流的控制流、模块组合、并发、状态管理显式化，并配套一个可定制的 Agent Harness 提供工具访问、隔离沙盒、检查点、回放与日志能力，使 LLM Agent 工作流既能像代码一样被版本控制、评审、共享，又不会像 Python 编排框架那样把业务逻辑与运行时耦合在一起。具体目标包括：提供统一子模块抽象（skills 与 agents 都用同一套 workflow 表示）允许自由组合，提供显式对话历史管理让用户控制每步上下文，提供可视化编辑器降低使用门槛，并在 7 个学科、数学、写作、论文理解、软件工程基准上验证其有效性。
与已有工作不同的是，本文的独特切入角度是同时填补反应式范式与代码耦合框架两个极端之间的真空。已有工作如 ADL（自然语言工作流但不显式管理上下文）、PDL（自然语言但仅部分支持显式上下文）、n8n 与 LangFlow（图形界面但完全不用自然语言）都只覆盖一个维度。AgentSPEX 首次同时满足三个维度：自然语言描述、显式上下文管理与可视化编辑，且配套 harness 把控制流逻辑从模型推理中卸载至解释器执行，这一点通过 ReAct 与 AgentSPEX 在同一工作流 prompt 下截然不同的表现（如 ChemBench 上 77.80% vs 83.30%）得到了直接验证。
核心方法
AgentSPEX 的整体思路是把工作流的「是什么」和「怎么执行」用同一套 YAML DSL 显式表达，并由一个统一的 Agent Harness 负责运行。直觉上，开发者先用类似自然语言的方式声明步骤顺序、分支、循环、并发与参数绑定，Harness 的解释器把 YAML 解析成可执行图，执行器在 Docker 沙盒内通过 MCP 与 LLM 进行多轮对话与工具调用，每一步结束自动落检查点，并通过回放机制支持 prompt 迭代。这与传统反应式范式的关键区别在于：控制流不再藏在大模型的生成中，而是被解释器强制执行；与传统编排框架的关键区别在于：业务逻辑与 Python 运行时解耦，workflow 是单一可读文本文件，方便 diff 与版本管理。
核心创新可归结为五条。第一，YAML 作为可执行规范本身，统一 task/step/if/while/for_each/call/parallel/set_variable/input/return 等十余种原语。第二，统一子模块抽象：skills 与 agents 都被建模为 workflow，既可被静态 call 调用，也可注册为动态 tool 让 Agent 在运行时自行选择。第三，显式对话历史管理：task 起新对话、step 持续累加，配合 save_as 上下文变量，让用户能精细控制每步看到什么。第四，Agent Harness 提供带沙盒的隔离执行环境、检查点、轨迹回放与潜在的形式化验证能力。第五，可视化编辑器支持 graph 与 YAML 双向同步编辑。论文的核心新颖性在于把控制流从模型的「软推理」中卸载到解释器，这是 ReAct 与 AgentSPEX 在同一 workflow 下表现分化的根本原因。
方法步骤详情
完整执行流程分为四层。解释层读入 workflow 文件，校验结构与配置，按层级为每个操作分配 step ID（如 3.2.1），用于检查点与日志追溯。执行层对 task/step 操作启动多轮循环，每轮把当前消息历史发给模型，用 MCP 客户端执行工具调用，结果追加到历史继续，直到模型不调用工具或达到配置的 tool-call / token 上限。task 起新对话、step 复用历史，让用户精准控制上下文流向。并发层由 parallel 节点触发并行操作、gather 汇聚结果，call 节点把任意 workflow 作为子模块调用并接收返回值；set_variable 与 increment 在上下文中维护状态。耐久性层在每个 step 完成后写入检查点（步 ID、上下文、指标、沙盒状态），失败后可从断点恢复；trace replay 可选择性加载前 N 步后从该点继续执行，避免改一条指令就重跑整个工作流。每个 workflow 运行在独立 Docker 容器，可访问文件系统、浏览器与 50+ 工具，异常不会影响宿主。
技术新颖性
技术新颖性体现在四个层面。一是形式层面，YAML DSL 把十余种工作流原语塞进可读结构，比 ADL/PDL 更接近工程可用状态。二是抽象层面，用统一的 workflow 抽象同时覆盖 skill（被动工具）与 subagent（主动 Agent），省去框架内两套 API 的分裂。三是执行层面，控制流由解释器强制实现，作者在消融中明确指出把同样的 workflow 给 ReAct 跑，ChemBench 反比 CoT 低 1.1%，ELAIPBench 反低 3.4%，验证了「显式执行」是效果增益的关键来源。四是工程层面，检查点 + trace replay 解决了 prompt 调试中的高昂重跑成本，formal verification（基于 Lean/Isabelle 谓词）也首次被纳入 Agent 框架的潜在路径。
实验结果
作者在 7 个基准上全面领先。SciBench / StemEZ / ChemBench 上比 ReAct 分别提升 2.8 / 1.9 / 5.5 个百分点，达 $90.61\%$ / $86.57\%$ / $83.30\%$。AIME 2025 取得 $100.0\%$，超过 CoT+Python（99.6%）与无工具 CoT（94.6%）。ELAIPBench 提升最显眼：CoT $37.22\%$ → $43.70\%$，比 ReAct $33.80\%$ 高近 10 个百分点，源于显式上下文管理让 Agent 不必背负全量历史。WritingBench 提升温和（$81.0\%$ vs $80.3\%$），SWE-Bench Verified 以 $77.1\%$ 超过 mini-SWE-agent（76.2%）。另一关键发现：仅把 workflow 塞给 ReAct 在 ChemBench 与 ELAIPBench 上反比 CoT 更差，说明「workflow 塞进 prompt 但不强制执行」无效甚至有害，必须由解释器强制执行才能把控制流优势转为性能增益。
查看结构化数据
| 任务 | 指标 | 本文 | 基线 | 提升 |
|---|---|---|---|---|
| SciBench (化学子集) | 准确率 | 90.61%（GPT-5） | 87.79%（ReAct） | +2.82 个百分点 |
| StemEZ | 准确率 | 86.57%（GPT-5） | 84.72%（ReAct） | +1.85 个百分点 |
| ChemBench | 准确率 | 83.30%（GPT-5*） | 78.90%（CoT） | +4.40 个百分点（vs ReAct +5.50） |
| AIME 2025 | 准确率 | 100.0%（GPT-5） | 99.6%（CoT + Python） | +0.40 个百分点 |
| ELAIPBench | 准确率 | 43.70%（GPT-5*） | 37.22%（CoT） | +6.48 个百分点（vs ReAct +9.90） |
| WritingBench | 综合得分 | 81.0%（Claude-Sonnet-4.5-Thinking） | 80.3%（ReAct） | +0.70 个百分点 |
| SWE-Bench Verified | 通过率 | 77.10%（Claude-Opus-4.5/4.6* 平均） | 76.20%（mini-SWE-agent） | +0.90 个百分点 |
局限与改进
作者坦承与隐含的局限有几点。第一，用户研究 23 人规模偏小，且只对比 LangGraph 一个对手，结论「AgentSPEX 易用性更好」的统计学强度有限，参与者明确表示对支撑复杂工作流信心不足。第二，在 WritingBench 上提升仅 0.7 个百分点，说明 AgentSPEX 的控制流优势在主观开放式写作任务上的边际收益有限，可能因为此类任务本身就缺少清晰的「步骤」概念。第三，作者明确指出现有形式化验证仅停留在「潜在路径」层面，并未给出基于 Lean/Isabelle 的实际验证结果。第四，论文未充分评估 harness 本身的工程开销（Docker 沙盒启动延迟、检查点 IO、MCP 调度）对延迟敏感场景的影响，且为端到端跨多个 token 量级 benchmark 提供 cost/latency 数字。第五，对 ReAct 与 AgentSPEX 同一 workflow 分化现象的解释依赖作者推断，缺乏严格的隔离实验（例如只切换执行模型不切换 prompt）。
独立分析的弱点
可独立指出四点弱点。其一，DSL 与 harness 强绑定带来可移植性代价：workflow 语义依赖解释器对 task/step/parallel/call 等原语的实现细节，跨框架迁移需要 rewrite，削弱了论文宣称的「workflow 即规范」价值。其二，YAML 嵌套结构在大型 agent（如 AI Scientist 这种多阶段写作与并行引用工作流）下会膨胀到难以维护，论文未提供模块化拆分粒度指南。其三，沙盒级别的可恢复性意味着每个 workflow run 都伴随 Docker、checkpoint、MCP 的全链路运维成本，对小型一次性任务性价比偏低。其四，形式化验证被轻描淡写地放在附录 C，未给出真实 predicate 库或案例，目前还停留在「未来可以做」的宣言层面，无法判断其在复杂工作流下是否可行。建议方向包括：抽象更细的模块拆分粒度与跨框架语义映射、用 checkpoint 压缩与沙盒复用削减运维成本、把形式化验证落地到至少 1-2 个具体 demo 中。
未来方向
作者在结论中明确提出的方向有四个：1）基于 Lean/Isabelle 的形式化验证落地；2）训练模型自动生成与消费 workflow；3）把端到端 Agent 训练 pipeline 整合进 harness；4）多 Agent 协作更丰富的抽象。基于成果可延伸的方向包括：把 workflow DSL 编译为可移植中间表示（类似 LLVM IR）以摆脱对单一一 harness 实现的依赖；与学术论文中的 step-level provenance 标注结合，使得 Agent 决策可被实验复现审计；把 trace replay 扩展为差分回放，在改动一个节点的指令后对比两次轨迹用于 prompt A/B 评测；引入基于因果推断的可解释性，识别哪些步骤对最终结果贡献最大。
复现评估
复现情况总体偏正面但有缺口。代码与 workflow 已开源：https://github.com/ScaleML/AgentSPEX 提供完整实现，三个 Demo（Deep Research、AI Scientist、AI Advisor）的 workflow YAML 与视频可在 https://anonymous.4open.science/r/AgentSPEX_video_demo-DC49/ 获取，附录 A 还提供了每个 benchmark 的子集选择与评测方法说明。复现难度集中在两点：一是实验主要使用 GPT-5、Claude-Sonnet-4.5-Thinking、Claude-Opus-4.5/4.6 等高阶闭源模型，需要相应 API 访问；二是 Harness 涉及 Docker、50+ 工具和 MCP 客户端，部署门槛较高。论文没有公开每个 benchmark 的 cost、token 消耗与 wall-clock 时间，也没有公开 user study 的具体问卷与统计检验细节，限制了端到端可重复性。
论文图表
