AgentRun 实战：用 DSL 把 AI Agent 工作流变成可检查、可重跑的流程
AI Agent 一旦从“回答问题”进入真实业务，最难维护的往往不是模型，而是流程：先搜索什么、什么时候让模型判断、失败后是否重试、何时升级给人工，都散落在业务代码里。流程一复杂，调试、复现和权限控制就会变得困难。
AgentRun 是 Parcha Labs 发布的一套工作流 DSL。它把步骤、状态、输入输出契约和决策节点放进可检查的工作流文档中，再由宿主应用提供工具、模型访问、权限与预算。项目当前 README 标注为 0.1.0-beta.3，采用 Apache-2.0 许可证，适合用来理解“Agent 编排层”应该怎样与业务代码分工。
先看它解决什么问题
| 需求 | 直接写 Agent 循环 | AgentRun |
| — | — | — |
| 固定步骤 | 散落在回调和条件分支中 | 用节点和状态路径表达 |
| 模型判断 | 手动解析自然语言 | 用带 schema 的 judge 节点 |
| 失败处理 | 每个项目各写一套重试 | 工作流内声明重试、循环和升级 |
| 复现测试 | 依赖线上模型输出 | 可先用 scripted fixtures 运行 |
| 审查流程 | 很难看清 Agent 走了哪条路 | 工作流文档可检查、可重跑 |
关键点是：AgentRun 不替你管理模型和工具。它更像一层“可执行流程定义”，把不稳定的 Agent 行为放进明确的边界里。
安装并跑通第一个示例
项目要求 Node.js 22.19+。新建目录后安装 beta 包：
npm install @parcha/agentrun-dsl@beta npx agentrun demo
这个 demo 使用脚本化的决策和响应，不需要 API Key，也不会给客户发送消息。若想运行仓库中的完整支持流程，可以这样操作：
git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.git cd agentrun npm ci --ignore-scripts npm run build npm run demo:support
示例会把请求分成“直接返回帮助答案”“调用 Agent 调查”“升级人工复核”等路径。它还提供 npm run test:support，方便在接入真实模型前先验证流程本身。
场景一：让判断节点拥有明确的输出
AgentRun 的工作流可以把工具调用和判断分开。例如先调用搜索工具得到 Candidate，再让 Jev 判断答案是否满足条件：
{
node: 'call', label: 'find-answer', via: 'tool',
tool: 'help.search', args: { request: '{request}' },
out: 'Candidate', as: 'answer', deadline_s: 10,
},
{
node: 'judge', label: 'check-existing-answer',
state: { request: '{request}', answer: '{answer}' },
out: 'Fit', as: 'fit',
}
官方支持示例要求判断结果为 yes，并且置信度至少为 0.8；否则允许 Agent 调查一次，再次检查，仍不满足就进入人工复核。这个设计比“让模型自由输出一段判断理由”更容易测试，因为下游只消费约定好的字段。
场景二：把并行研究封装成可重用流程
除了线性步骤，文档还展示了嵌套工作流、并行研究、证据筛选和报告生成。一个研究任务可以先拆出多个子问题，再并行调用不同工具，最后由筛选节点选择证据并交给报告节点。
这类流程最适合保存为项目级定义：输入是问题和约束，输出是带证据的报告，中间状态则记录每一步的结果。以后更换模型或工具适配器时，流程结构仍然可复用。
场景三：接入已有 Agent，而不是重写整个应用
接入自己的应用时，AgentRun 要求宿主提供三类适配器：用 runEffect 连接工具，用 runNode 连接现有 Agent，再用 createJevRunner() 作为判断节点的 runJudge。完成工作流后，可以把 runWorkflow 注册成 Agent 的一个工具。
实时 Jev 调用需要单独的 TYPESAFE_API_KEY；不包含 Jev 判断的工作流则不需要这个密钥。权限、取消和恢复策略也应由宿主应用决定，这一点很重要：DSL 能验证状态路径，却不能自动证明答案事实正确，也不能替你创建安全沙箱。
最佳实践与边界
- 先 fixtures，后真实模型。 先用脚本化响应覆盖成功、重试和升级路径，再接入线上模型。
- 把阈值写进契约。
yes/no/uncertain、置信度和 deadline 都应成为显式条件，而不是藏在提示词里。 - 把权限留在宿主。 README 明确提醒，代码节点以进程权限执行；不可信工作流作者需要由宿主控制沙箱。
- 不要把 DSL 当作事实核验器。 类型和 schema 能约束形状，不能保证模型输出真实。
AgentRun 的价值不在于再造一个聊天 Agent，而在于给 Agent 行为加上一层可读的流程边界。如果你的项目已经出现大量重试、人工升级和多步研究逻辑，用 DSL 固化路径，再让宿主掌握模型、工具和权限，通常比继续堆条件分支更容易维护。
相关链接