问题背景
当前 LLM Agent 开发面临两个极端：
极端 A：纯 ReAct 式提示——一条 system prompt 驱动 Agent 开放式地执行工具调用序列。实现简单，但控制流隐式、行为难以预测，长链任务（需要分支和迭代）表现不稳定。
极端 B：Python 工作流框架——LangGraph、DSPy、CrewAI 等提供了更强的结构控制，但工作流逻辑深度耦合 Python 代码，学习曲线陡峭，非程序员无法修改，维护成本高。
AgentSPEX 的定位是中间路径：声明式语言 + 明确控制流 + 自然语言指令。
核心设计
工作流语言
AgentSPEX 用 YAML 描述工作流，支持以下构件：
| 构件类型 | 关键词 | 说明 |
|---|---|---|
| 调用 | task / step | task 开新对话，step 保留历史 |
| 控制流 | if / switch / while / for_each | 分支和循环 |
| 并发 | parallel / gather | 并行执行多个操作 |
| 组合 | call | 调用另一个工作流作为子模块 |
| 状态 | set_variable / save_as | 显式上下文管理 |
每个工作流包含 name、goal、config（工具集、模型配置）、workflow（操作序列）。变量用 Mustache 语法引用：{{variable_name}}。
name: "research_assistant"
goal: "Research a topic and write a summary"
config:
model: "gpt-5.4"
enabled_tools: ["web_search", "file_write"]
workflow:
- task:
instruction: "Generate search queries for {{topic}}"
save_as: "search_queries"
- call:
module: "modules/search_and_summarize.yaml"
parameters:
queries: "{{search_queries}}"
save_as: "paper_summary"
- task:
instruction: "Write a report at {{file_path}} based on: {{paper_summary}}"
task vs step 的关键区别
task 每次开启全新对话，适合将中间结果通过变量传递给后续步骤；step 在同一对话中累积历史，适合需要多轮工具调用和推理的任务。这个设计给工作流作者提供了对上下文可见性的直接控制——决定每个步骤"看到什么"而不是让模型自行管理。
执行环境（Agent Harness）
沙箱执行
每个工作流在 Docker 容器中运行，提供隔离的浏览器、文件系统访问，以及通过 MCP（Model Context Protocol）连接的 50+ 工具，覆盖文件操作、网络搜索、代码执行、浏览器自动化等。
持久化与恢复
面向长时间运行的工作流，AgentSPEX 提供：
- Checkpoint：每步完成后保存状态（变量值、步骤输出、沙箱状态），支持从任意断点恢复
- 执行轨迹追踪：记录完整执行轨迹，包括模型响应、工具调用结果、对话状态
- 选择性重放：修改某个步骤的 instruction 后，可复用之前步骤的轨迹跳过重新执行，只重跑修改点之后的部分
可视化编辑器
提供双向同步的图形界面：工作流显示为可交互流程图，每个节点对应一个操作。用户可以拖拽节点或直接编辑 YAML，两个视图实时同步，修改后可直接在编辑器中执行。
评测与用户研究
团队基于 AgentSPEX 构建了三个即开即用的 Agent：
- Deep Research：多层次搜索策略，生成 Markdown 研究报告，类似 OpenAI Deep Research
- AI Scientist：生成新颖学术研究提案（基于 TinyScientist 实现）
- AI Advisor：对研究提案进行 Rubric 式评审
在 7 项基准上（涵盖科学、数学、写作、论文理解、软件工程）进行测试，并与 LangGraph 等现有框架对比。用户研究显示 AgentSPEX 提供了"更易于解读和修改的工作流编写范式"。
与现有框架的定位差异
AgentSPEX 不是要替代 LangGraph 或 DSPy，而是填补"谁来写和改 Agent"的协作空白：领域专家用 YAML 和自然语言指令表达工作流逻辑，工程师负责工具集成和基础设施。工作流文件独立于执行代码，可以版本控制、diff、共享，不依赖工程师每次修改 Python。