从零搭建长时程 Agent 执行框架实战教程

作者:沙与沫2026.11.18 11:20浏览量:0

简介:本教程面向希望让大模型从"一问一答"升级为"持续干活"的开发者、独立开发者与运维人员,系统讲解长时程 Agent 执行框架(harness)的选型、搭建、配置、验证与排查方法,覆盖沙箱隔离、工具权限、记忆持久化、技能版本化、子 Agent 编排与自修复闭环,帮助读者跑通一个可稳定运行数十分钟到数小时的自动化任务流程。

一、教程目标:你将完成什么

本教程要交付的不是一段”能聊天的脚本”,而是一个可持续执行任务的最小可用执行框架。

完成本教程后,你应当能够做到:

  1. 说清楚”对话式模型调用”与”长时程执行框架”的本质差异,并据此判断自己的需求是否需要框架;
  2. 搭建一个带隔离工作区、工具注册表、记忆存储和日志追踪的执行骨架;
  3. 把一个多阶段任务(如”调研—写代码—自测—产出报告”)稳定跑完,并在中途失败后自动重试或修复;
  4. 建立一套可复用的验收用例,用来判断改动是变好还是变差。

适合读者:已有基础编程能力、调用过模型 API、写过多步骤脚本或流水线的开发者;负责内部自动化平台选型的运维人员;需要评估长时程自动化投入产出的技术负责人。

二、适用场景

长时程框架的价值只在”任务本身需要多个步骤、多种工具、并且中间结果会互相影响”时才成立。典型场景包括:

  • 代码类任务:读取仓库、定位问题、修改多个文件、运行测试、根据失败输出反复迭代;
  • 调研与产出类任务:抓取与整理资料、交叉验证、生成结构化文档或多媒体素材;
  • 运维巡检类任务:定时检查指标、比对基线、按预案执行动作、汇总巡检报告;
  • 数据处理类任务:多源数据接入、清洗、校验、落库并输出对账结果。

反过来,如果任务一次调用模型就能回答,引入框架只会增加延迟、成本和故障面。

三、前置准备

环境层面:一台可运行的开发机或云主机;支持容器运行时的环境(用于隔离执行);可用的版本控制仓库用于保存技能定义与配置。

能力层面:一个可访问的模型服务接口(自建推理服务或云上托管的模型服务均可);如需处理图像、语音类产出,还需确认对应模态的服务可用。

权限层面:仅申请任务真正需要的最小权限。原则是只读优先、写操作显式授权、删除类操作默认禁用。

知识层面:理解 Agent、工具调用(tool calling)、函数描述、上下文窗口、沙箱、幂等这几个概念即可,不必提前掌握具体框架。

依赖层面:对象存储(用于存放中间产物与归档)、消息队列(用于解耦长任务与触发方)、日志服务与监控告警、容器平台——这些都可以在自建或云上完成,例如百度智能云等云平台均提供上述通用类目能力,选择时以接口标准化程度、配额与成本为主要依据。

四、先理解:为什么需要”执行框架”而不是提示词

一次模型调用是一次”无状态计算”:输入上下文,输出文本,然后一切结束。而长时程任务有三个特征会让单次调用失效。

一是状态跨步延续。任务执行到第 40 步时,第 1 步的结论不能丢失,否则会重复劳动甚至自相矛盾。二是动作产生外部影响。写文件、调接口、跑命令都会改变世界状态,而文本输出不会——框架必须把”想做的事”翻译成”被允许执行的动作”。三是失败是常态而不是异常。长时间运行中必然遇到超时、工具报错、上下文溢出,框架的职责是让失败后能继续,而不是整体重来。

因此一个长时程执行框架的最小构件是六件事:沙箱(安全地执行动作)、工具(可调用的能力集合)、记忆(跨步状态)、技能(可复用的能力单元)、子 Agent(任务并行与上下文隔离)、消息网关(与人和其他系统交互)。后续所有搭建步骤都是围绕这六件事展开。

五、选型维度:如何判断一个开源框架是否值得投入

开源生态中存在多个成熟的长时程 Agent 框架,功能重叠度较高。建议用下面的维度做横向评估,而不是只看社区热度。

维度 需要确认的问题 高风险信号
任务跨度 是否支持数十步以上的任务与断点续跑 只能在单次会话内循环
隔离机制 是否默认在容器中执行工具调用 直接在宿主环境运行命令
记忆设计 是否区分短期上下文与长期持久化存储 只把全部历史塞进上下文
技能扩展 技能是否为独立文件、可版本化、可回滚 技能硬编码在提示词里
编排能力 是否支持子 Agent 派生与结果汇总 单一线性循环
可观测性 是否输出每一步的输入、输出、耗时与 token 消耗 只有一条最终日志
许可协议 是否采用宽松型开源许可,是否允许商用 许可条款含商用限制
失败恢复 技能失败时是否有修复或降级路径 失败即终止

关于许可协议要额外提醒:社区热度高不代表可用于你的场景。在正式引入前,务必以仓库自带的许可文件原文为准,确认商用、闭源分发、专利与再许可条款,这一步无法通过阅读宣传性描述替代。

六、实施步骤

步骤 1:定义任务边界与成功判据

先写清楚”什么算完成”。这一步决定了后面所有编排逻辑的终点。

示例判据:”任务成功” = 目标仓库中目标测试全部通过 且 变更行数不超过设定阈值 且 未修改受保护目录。

为什么先做:没有可判定的成功条件,Agent 会陷入无限重试或过早收敛。判据要可被程序检查,不能是”看起来合理”这类主观描述。

步骤 2:搭建隔离沙箱与工作目录

为每个任务创建独立的工作目录并绑定到容器实例,宿主机只挂载必要的读写路径。

  1. task_workspace/
  2. ├── input/ # 只读挂载,任务输入
  3. ├── output/ # 任务产出,可归档到对象存储
  4. ├── scratch/ # 临时文件,任务结束即销毁
  5. └── meta/ # 任务元数据与断点状态

要点:容器内不注入长期凭证;网络出口按域名白名单限制;CPU 与内存设上限,避免单次任务拖垮宿主;任务结束后销毁容器,仅归档 output/ 与 meta/。

步骤 3:接入模型服务与凭证管理

框架需要一个模型适配层,把不同供应商的接口差异收敛成统一调用。建议在框架外维护一个独立的适配模块,暴露统一的方法签名。

  1. # 伪代码:统一模型适配层
  2. def call_model(role, messages, tools=None, max_tokens=None):
  3. """role: planner / coder / reviewer / summarizer
  4. 统一超时、重试、限流与计费记录"""
  5. return retry_with_backoff(
  6. provider_client(role).chat,
  7. messages=messages,
  8. tools=tools,
  9. max_tokens=max_tokens,
  10. retries=3,
  11. timeout=60,
  12. )

凭证通过环境变量或密钥管理服务注入,不要写入配置文件或提示词。不同角色使用不同模型是常见做法:规划与代码生成可用能力更强的模型,摘要与格式化用小模型降成本。

步骤 4:注册工具并实现权限最小化

工具描述的质量直接决定调用准确率。每个工具需要:唯一名称、一句话用途、参数模式(含类型与必填性)、失败语义。

  1. {
  2. "name": "write_file",
  3. "description": "在沙箱工作目录内写入文本文件,路径必须位于 workspace 下",
  4. "parameters": {
  5. "path": {"type": "string", "required": true},
  6. "content": {"type": "string", "required": true}
  7. },
  8. "risk": "medium",
  9. "approval": "auto_with_audit"
  10. }

按风险分级设定审批策略:

  • 低风险(读文件、检索、格式化):自动执行;
  • 中风险(写文件、安装依赖):自动执行但记录完整审计;
  • 高风险(删除、发布、外部计费操作):必须人工确认后执行,且在生产环境建议直接禁用。

步骤 5:设计记忆与状态持久化

把”记忆”拆成三层,避免全部历史堆积在上下文里:

  1. 工作记忆:当前任务的历史消息,超过窗口时做摘要压缩;
  2. 结构化状态:以键值形式保存任务进度、已完成子任务、未决问题,支持断点续跑;
  3. 长期知识:跨任务的经验沉淀,如”某类报错的固定处理方式”,可按相似度检索后注入。

关键设计点是每一步都持久化断点。当进程被重启或超时,框架应能从最近一次成功步骤恢复,而不是从头执行。

步骤 6:把重复逻辑固化为”技能”

技能是一个自描述的能力单元,通常包含:触发条件、输入输出约定、执行步骤、成功判定、失败回退策略。技能的目录结构建议与代码版本管理保持一致,便于评审与回滚。

技能设计的两条经验:单个技能只做一件事,职责过大时 Agent 的选择准确率会下降;技能文档里写明何时不该使用它,能显著减少误调用。

agent-">步骤 7:用子 Agent 拆分任务与隔离上下文

当任务包含互不依赖的子目标时,派生子 Agent 并行执行,主 Agent 只负责汇总。子 Agent 的价值不只是并行加速,更重要的是上下文隔离:搜索类任务产生的大量中间内容留在子 Agent 内部,只有结论回到主 Agent,主上下文因此不会被无关细节污染。

  1. # 伪代码:派生与汇总
  2. results = parallel_map(
  3. subtasks,
  4. worker=lambda t: run_agent(
  5. goal=t.goal,
  6. tools=read_only_tools(t), # 子 Agent 默认只给只读工具
  7. max_steps=t.budget,
  8. ),
  9. )
  10. summary = call_model("summarizer", merge(results))

给每个子 Agent 设置步数预算与耗时上限,防止个别分支无限扩张。

步骤 8:接入消息网关与人工审批

长时程任务通常通过消息队列或 Webhook 触发,结果回写到通知渠道。网关层应支持:任务提交、进度查询、中断、以及高风险管理动作的审批交互。生产环境建议把”提交任务”和”授权高风险动作”设计为两个独立动作,避免误操作。

步骤 9:建立可观测性

每次执行至少记录:任务标识、每步的工具名与入参摘要、耗时、模型 token 消耗、失败原因与重试次数。把日志送入集中式日志服务,关键指标(成功率、平均步数、单任务成本、平均修复次数)配置监控告警。

这一步最容易被跳过,但它是后续所有优化的前提。没有逐步数据,就无法判断是提示词问题、工具描述问题还是模型能力问题。

步骤 10:闭合自修复回路

当某个技能执行失败,框架应记录失败上下文(期望结果、实际输出、错误信息),生成修复建议,在受控范围内尝试下一轮执行。务必设置:同一技能的最大修复轮次(建议 2~3 轮)、修复后的回归验证、以及超过阈值时的人工介入通知。修复动作本身也要经过沙箱与审计,否则自动修复会变成自动引入新缺陷。

七、结果验证

分四层验收,逐层收紧:

  1. 连通性验证:沙箱能启动、模型接口可调用、每个工具能独立跑通一次最小调用;
  2. 单步验证:对关键技能准备输入样本,确认输出符合约定格式;
  3. 端到端验证:准备 5~10 个典型任务用例,覆盖正常路径与至少两个失败路径(工具报错、上下文超限),确认能完成或按预期终止;
  4. 回归验证:任何提示词、工具描述、模型版本变更后,重跑同一用例集,对比成功率、平均步数与成本三项指标的变化。

八、常见问题与排查

模型反复调用同一个失败工具:多为工具描述与实际行为不一致,或错误信息未回流到上下文。检查失败输出是否被完整写入下一轮消息。

任务在某一阶段”卡住”不动:确认是否存在无终止条件的循环、以及是否设置了最大步数与无进展检测(连续 N 步无状态变更即中止)。

上下文快速膨胀导致调用失败:开启摘要压缩,并把大体积中间产物写入文件、只把路径放进上下文。

子 Agent 结果互相冲突:在汇总前加入校验与排序规则,明确冲突时的优先级来源。

高风险管理动作被误执行:检查审批策略是否真正生效——部分框架的审批只对交互模式生效,无人值守模式下会静默跳过,这一点必须实测确认。

成本远超预期:按角色拆分模型档位,压缩工具返回结果长度,对可缓存的调用结果做缓存。

九、优化建议

安全:默认最小权限,高风险动作显式授权;容器内不注入长期凭证;对外部输入一律视为不可信内容,防止通过文档、网页内容注入指令。

稳定性:所有工具调用必须幂等或可补偿;关键外部调用加超时与退避重试;断点续跑覆盖整个流程而非仅覆盖模型调用。

成本:把”步数”当作一等公民来治理,为每个任务类型设步数与耗时预算;用小模型承担格式转换与摘要类工作。

可维护性:技能与配置进版本库、可评审、可回滚;每次变更附带用例集对比报告;把提示词视为需要测试的代码。

可扩展性:工具层与模型层保持接口稳定,任务触发层通过消息队列解耦,便于后期从单机扩展到容器集群编排。

十、总结

长时程 Agent 的执行框架本质是一套”把不可靠的智能放进可靠的工程约束里”的系统:沙箱负责边界,权限负责风险,记忆与断点负责连续性,技能与子 Agent 负责结构,日志与用例集负责可判断。

落地路径建议由简到繁:先跑通”沙箱 + 三个只读工具 + 端到端用例”,确认稳定后再逐步引入持久化记忆、子 Agent 并行和自修复回路。选型时以许可条款、隔离机制和可观测性为硬指标,用横向评估表替代社区热度判断,并通过回归用例集把每次改进都变成可度量的收益。