简介:本教程面向希望让大模型从"一问一答"升级为"持续干活"的开发者、独立开发者与运维人员,系统讲解长时程 Agent 执行框架(harness)的选型、搭建、配置、验证与排查方法,覆盖沙箱隔离、工具权限、记忆持久化、技能版本化、子 Agent 编排与自修复闭环,帮助读者跑通一个可稳定运行数十分钟到数小时的自动化任务流程。
本教程要交付的不是一段”能聊天的脚本”,而是一个可持续执行任务的最小可用执行框架。
完成本教程后,你应当能够做到:
适合读者:已有基础编程能力、调用过模型 API、写过多步骤脚本或流水线的开发者;负责内部自动化平台选型的运维人员;需要评估长时程自动化投入产出的技术负责人。
长时程框架的价值只在”任务本身需要多个步骤、多种工具、并且中间结果会互相影响”时才成立。典型场景包括:
反过来,如果任务一次调用模型就能回答,引入框架只会增加延迟、成本和故障面。
环境层面:一台可运行的开发机或云主机;支持容器运行时的环境(用于隔离执行);可用的版本控制仓库用于保存技能定义与配置。
能力层面:一个可访问的模型服务接口(自建推理服务或云上托管的模型服务均可);如需处理图像、语音类产出,还需确认对应模态的服务可用。
权限层面:仅申请任务真正需要的最小权限。原则是只读优先、写操作显式授权、删除类操作默认禁用。
知识层面:理解 Agent、工具调用(tool calling)、函数描述、上下文窗口、沙箱、幂等这几个概念即可,不必提前掌握具体框架。
依赖层面:对象存储(用于存放中间产物与归档)、消息队列(用于解耦长任务与触发方)、日志服务与监控告警、容器平台——这些都可以在自建或云上完成,例如百度智能云等云平台均提供上述通用类目能力,选择时以接口标准化程度、配额与成本为主要依据。
一次模型调用是一次”无状态计算”:输入上下文,输出文本,然后一切结束。而长时程任务有三个特征会让单次调用失效。
一是状态跨步延续。任务执行到第 40 步时,第 1 步的结论不能丢失,否则会重复劳动甚至自相矛盾。二是动作产生外部影响。写文件、调接口、跑命令都会改变世界状态,而文本输出不会——框架必须把”想做的事”翻译成”被允许执行的动作”。三是失败是常态而不是异常。长时间运行中必然遇到超时、工具报错、上下文溢出,框架的职责是让失败后能继续,而不是整体重来。
因此一个长时程执行框架的最小构件是六件事:沙箱(安全地执行动作)、工具(可调用的能力集合)、记忆(跨步状态)、技能(可复用的能力单元)、子 Agent(任务并行与上下文隔离)、消息网关(与人和其他系统交互)。后续所有搭建步骤都是围绕这六件事展开。
开源生态中存在多个成熟的长时程 Agent 框架,功能重叠度较高。建议用下面的维度做横向评估,而不是只看社区热度。
| 维度 | 需要确认的问题 | 高风险信号 |
|---|---|---|
| 任务跨度 | 是否支持数十步以上的任务与断点续跑 | 只能在单次会话内循环 |
| 隔离机制 | 是否默认在容器中执行工具调用 | 直接在宿主环境运行命令 |
| 记忆设计 | 是否区分短期上下文与长期持久化存储 | 只把全部历史塞进上下文 |
| 技能扩展 | 技能是否为独立文件、可版本化、可回滚 | 技能硬编码在提示词里 |
| 编排能力 | 是否支持子 Agent 派生与结果汇总 | 单一线性循环 |
| 可观测性 | 是否输出每一步的输入、输出、耗时与 token 消耗 | 只有一条最终日志 |
| 许可协议 | 是否采用宽松型开源许可,是否允许商用 | 许可条款含商用限制 |
| 失败恢复 | 技能失败时是否有修复或降级路径 | 失败即终止 |
关于许可协议要额外提醒:社区热度高不代表可用于你的场景。在正式引入前,务必以仓库自带的许可文件原文为准,确认商用、闭源分发、专利与再许可条款,这一步无法通过阅读宣传性描述替代。
先写清楚”什么算完成”。这一步决定了后面所有编排逻辑的终点。
示例判据:”任务成功” = 目标仓库中目标测试全部通过 且 变更行数不超过设定阈值 且 未修改受保护目录。
为什么先做:没有可判定的成功条件,Agent 会陷入无限重试或过早收敛。判据要可被程序检查,不能是”看起来合理”这类主观描述。
为每个任务创建独立的工作目录并绑定到容器实例,宿主机只挂载必要的读写路径。
task_workspace/├── input/ # 只读挂载,任务输入├── output/ # 任务产出,可归档到对象存储├── scratch/ # 临时文件,任务结束即销毁└── meta/ # 任务元数据与断点状态
要点:容器内不注入长期凭证;网络出口按域名白名单限制;CPU 与内存设上限,避免单次任务拖垮宿主;任务结束后销毁容器,仅归档 output/ 与 meta/。
框架需要一个模型适配层,把不同供应商的接口差异收敛成统一调用。建议在框架外维护一个独立的适配模块,暴露统一的方法签名。
# 伪代码:统一模型适配层def call_model(role, messages, tools=None, max_tokens=None):"""role: planner / coder / reviewer / summarizer统一超时、重试、限流与计费记录"""return retry_with_backoff(provider_client(role).chat,messages=messages,tools=tools,max_tokens=max_tokens,retries=3,timeout=60,)
凭证通过环境变量或密钥管理服务注入,不要写入配置文件或提示词。不同角色使用不同模型是常见做法:规划与代码生成可用能力更强的模型,摘要与格式化用小模型降成本。
工具描述的质量直接决定调用准确率。每个工具需要:唯一名称、一句话用途、参数模式(含类型与必填性)、失败语义。
{"name": "write_file","description": "在沙箱工作目录内写入文本文件,路径必须位于 workspace 下","parameters": {"path": {"type": "string", "required": true},"content": {"type": "string", "required": true}},"risk": "medium","approval": "auto_with_audit"}
按风险分级设定审批策略:
把”记忆”拆成三层,避免全部历史堆积在上下文里:
关键设计点是每一步都持久化断点。当进程被重启或超时,框架应能从最近一次成功步骤恢复,而不是从头执行。
技能是一个自描述的能力单元,通常包含:触发条件、输入输出约定、执行步骤、成功判定、失败回退策略。技能的目录结构建议与代码版本管理保持一致,便于评审与回滚。
技能设计的两条经验:单个技能只做一件事,职责过大时 Agent 的选择准确率会下降;技能文档里写明何时不该使用它,能显著减少误调用。
当任务包含互不依赖的子目标时,派生子 Agent 并行执行,主 Agent 只负责汇总。子 Agent 的价值不只是并行加速,更重要的是上下文隔离:搜索类任务产生的大量中间内容留在子 Agent 内部,只有结论回到主 Agent,主上下文因此不会被无关细节污染。
# 伪代码:派生与汇总results = parallel_map(subtasks,worker=lambda t: run_agent(goal=t.goal,tools=read_only_tools(t), # 子 Agent 默认只给只读工具max_steps=t.budget,),)summary = call_model("summarizer", merge(results))
给每个子 Agent 设置步数预算与耗时上限,防止个别分支无限扩张。
长时程任务通常通过消息队列或 Webhook 触发,结果回写到通知渠道。网关层应支持:任务提交、进度查询、中断、以及高风险管理动作的审批交互。生产环境建议把”提交任务”和”授权高风险动作”设计为两个独立动作,避免误操作。
每次执行至少记录:任务标识、每步的工具名与入参摘要、耗时、模型 token 消耗、失败原因与重试次数。把日志送入集中式日志服务,关键指标(成功率、平均步数、单任务成本、平均修复次数)配置监控告警。
这一步最容易被跳过,但它是后续所有优化的前提。没有逐步数据,就无法判断是提示词问题、工具描述问题还是模型能力问题。
当某个技能执行失败,框架应记录失败上下文(期望结果、实际输出、错误信息),生成修复建议,在受控范围内尝试下一轮执行。务必设置:同一技能的最大修复轮次(建议 2~3 轮)、修复后的回归验证、以及超过阈值时的人工介入通知。修复动作本身也要经过沙箱与审计,否则自动修复会变成自动引入新缺陷。
分四层验收,逐层收紧:
模型反复调用同一个失败工具:多为工具描述与实际行为不一致,或错误信息未回流到上下文。检查失败输出是否被完整写入下一轮消息。
任务在某一阶段”卡住”不动:确认是否存在无终止条件的循环、以及是否设置了最大步数与无进展检测(连续 N 步无状态变更即中止)。
上下文快速膨胀导致调用失败:开启摘要压缩,并把大体积中间产物写入文件、只把路径放进上下文。
子 Agent 结果互相冲突:在汇总前加入校验与排序规则,明确冲突时的优先级来源。
高风险管理动作被误执行:检查审批策略是否真正生效——部分框架的审批只对交互模式生效,无人值守模式下会静默跳过,这一点必须实测确认。
成本远超预期:按角色拆分模型档位,压缩工具返回结果长度,对可缓存的调用结果做缓存。
安全:默认最小权限,高风险动作显式授权;容器内不注入长期凭证;对外部输入一律视为不可信内容,防止通过文档、网页内容注入指令。
稳定性:所有工具调用必须幂等或可补偿;关键外部调用加超时与退避重试;断点续跑覆盖整个流程而非仅覆盖模型调用。
成本:把”步数”当作一等公民来治理,为每个任务类型设步数与耗时预算;用小模型承担格式转换与摘要类工作。
可维护性:技能与配置进版本库、可评审、可回滚;每次变更附带用例集对比报告;把提示词视为需要测试的代码。
可扩展性:工具层与模型层保持接口稳定,任务触发层通过消息队列解耦,便于后期从单机扩展到容器集群编排。
长时程 Agent 的执行框架本质是一套”把不可靠的智能放进可靠的工程约束里”的系统:沙箱负责边界,权限负责风险,记忆与断点负责连续性,技能与子 Agent 负责结构,日志与用例集负责可判断。
落地路径建议由简到繁:先跑通”沙箱 + 三个只读工具 + 端到端用例”,确认稳定后再逐步引入持久化记忆、子 Agent 并行和自修复回路。选型时以许可条款、隔离机制和可观测性为硬指标,用横向评估表替代社区热度判断,并通过回归用例集把每次改进都变成可度量的收益。