1. 架构分层从一次 LLM 调用到完整 Harness Runtime到底在选什么1.1 先把问题拆开你需要的不是“选框架”而是“选复杂度”很多人一上来就问“AI Agent 架构到底用哪个框架好”我觉得这个问题本身就问偏了。真正要回答的不是“哪个好”而是“你现在需要多复杂”。一次 LLM 调用、一个 ReAct 循环、一套完整 Harness Runtime这三者之间的差距比想象中大得多。我见过不少团队踩同一个坑刚跑通一个带工具调用的 Demo就急着上全套 Agent 运行时结果被上下文管理、记忆持久化、沙箱执行、可观测性这些基础设施拖垮。反过来也有团队在业务已经需要并行 Agent、长时任务、断点恢复时还在手写while True: llm.call()的死循环脚本导致任务一跑长就崩、一并发就乱。先把概念对齐。我这里说的“一次 LLM 调用”指的是单轮请求-响应模型根据 System Prompt 直接产出结果不涉及工具、循环和状态。这是最基础的范式适合分类、抽取、简单问答。“从一次调用到完整 Harness Runtime”中间其实隔了好几层工具调用层模型输出结构化指令由程序解析并执行外部函数循环控制层Agent 在“思考-行动-观察”之间反复迭代直到任务完成状态管理层维护会话上下文、任务进度、中间结果支持暂停和恢复运行时层负责沙箱、并发调度、安全策略、资源限制、可观测性也就是题名里的 Harness Runtime所以“AI Agent 架构怎么选”这个问题的实质是你要在哪一层投入复杂度这决定了后续所有的技术选型。1.2 确定需求的三个关键判断任务类型、交互模式、运行环境我一般会从三个维度判断该落在哪一层比直接看框架榜单靠谱得多。第一个维度是任务类型。如果是短任务比如“从这段合同里抽取违约条款并结构化输出”一次调用加 JSON Mode 就够了压根不需要 Agent 架构。如果是多步骤任务比如“调研一下某领域的竞品写一份对比报告”这就是典型的 ReAct 多轮工具调用场景。如果是长时任务比如“每天监控数据异常异常时自动排查并生成处置建议”这需要完整 Runtime因为涉及定时触发、持久化状态、并发执行和失败重试。第二个维度是交互模式。单轮问答、多轮对话、任务式执行、人机协同这四种模式的架构要求完全不同。任务式执行要求 Agent 能自主决策那么工具权限、操作审计、安全边界就变成核心问题。人机协同要求 Agent 能在不确定时停下来问人那么运行时需要有“挂起-恢复”机制。第三个维度是运行环境。跑在本地脚本里、跑在服务端 API 里、跑在云端工作流里这决定了你要不要做沙箱、怎么做隔离、怎么处理网络权限。这三个维度想清楚之后架构选型基本就收敛了。接下来我按“轻-中-重”三档详细拆解每一档的实现方案和适用边界。2. 轻量方案单次 LLM 调用的工程化增强2.1 结构化输出的关键技巧JSON Mode、函数调用与输出校验先说最轻的一档。你可能只需要一次 LLM 调用但生产环境里“一次调用”远不是“把 Prompt 扔给模型”那么简单。要做对结构化输出核心是三个技巧。JSON Mode 是基础。现在的模型基本都支持约束输出为合法 JSON这能省掉大量“从文本里提取结果”的脏活。但注意JSON Mode 只保证“是合法 JSON”不保证“是你想要的 JSON”。字段名可能漂移、枚举值可能不在你定义的范围内所以一定要在请求里用response_format之类的参数显式声明而不是在 Prompt 里“期望”它输出 JSON。函数调用Function Calling是更稳的方式。对我来说与其让模型自由发挥生成 JSON不如定义好函数签名让模型输出“我要调用这个函数参数是这些”。这种方式本质上是把“结构化输出”变成了“参数填充”模型的准确率会高很多。举个例子定义一个extract_contract_clauses(text: str, clause_types: List[str]) - List[Clause]函数模型会严格按参数约束输出。输出校验这步绝对不能省而且要在架构上设成强制关卡。我见过太多人省了这步导致下游解析崩溃。我的做法是拿到模型输出后先做 JSON Schema 校验再做业务规则校验比如枚举值是否合法、日期格式是否正确。校验失败就自动重试重试时把校验错误信息回传给模型。这个“校验-失败-回传-重试”的闭环是轻量方案里性价比最高的一环。2.2 轻量方案的工具调用落地没有框架也能跑通 ReAct 雏形很多人以为工具调用必须上框架其实不然。最朴素的 ReAct 循环几行代码就能跑通关键是设计好“循环终止条件”和“工具注册机制”。核心数据结构是消息列表。每轮循环把系统提示、历史消息、工具结果依次追加到消息列表里再把整个列表发给模型。模型要么返回最终答案要么返回“要调用某某工具参数是什么”。程序解析出工具调用意图后在本地注册表里查找对应函数执行把结果转成一条tool角色消息继续下一轮循环。循环终止条件要设置三层防线。第一层是模型明确返回最终答案自然终止。第二层是达到最大迭代次数比如 10 轮强制终止并通知用户“任务未完成可能超出模型能力边界了”。第三层是超时保护整个循环设定一个时间上限防止某些工具调用卡死或模型陷入死循环。这三层防线缺一不可否则生产环境里你会被各种边缘情况折磨。工具注册机制上我推荐用装饰器模式把“函数实现”和“函数描述”绑定在一起。一个工具函数配上它的名称、描述、参数 JSON Schema注册进全局字典。模型看到的工具列表就是这份字典的推导结果实际执行时也是从字典里查函数。这样增删工具只改一处不会出现“模型能调用但程序找不到函数”的尴尬情况。2.3 什么情况下该止步于“轻量方案”轻量方案的适用边界我的判断标准有三个任务步骤不超过 3-5 步、状态变化不复杂、不需要长时间后台运行。比如做一个“工单自动分类助手”输入工单文本输出类别、优先级、处理建议这用轻量方案就非常合适。但如果你想做“工单自动处理助手”需要查知识库、调内部系统、依据结果做决策这就超出轻量方案的能力范围了。还有一个容易被忽略的信号当你的工具数量超过 10 个、一轮任务中每个 Agent 平均要调用 3 次以上工具时手写循环开始变得不可维护。不是说你写不了而是错误处理、上下文管理、日志追踪这些横切逻辑会让你疲于奔命。这时候应该考虑上框架或者自己搭一个更完整的运行时骨架。3. 中量方案框架选型与 ReAct 循环的完整落地3.1 主流开源框架的三条技术路线如果你需要更完整的 Agent 能力又不打算从零造轮子主流开源框架基本可以归为三条技术路线。我这里不提具体品牌只讲它们代表的架构思想。第一条是声明式工作流路线。你用配置文件或代码声明“先做 A再做 B如果 C 则跳到 D”每个节点可以是 LLM 调用、工具调用或条件分支。优点是流程确定性强、可观测性好、状态管理简单适合业务流程相对固定的场景比如客服工单处理、数据处理管线。缺点是灵活性受限遇到计划外路径时需要人工补写逻辑。第二条是自主决策路线。Agent 自己决定下一步做什么框架只提供工具、记忆和循环机制。这是 ReAct 范式的工程化实现适合开放性强、步骤不确定的场景比如智能调研、代码生成与执行、复杂问题拆解。优点是非常灵活缺点是流程不可预知需要更多安全护栏和评估手段。第三条是多智能体协作路线。多个 Agent 各司其职有的负责规划、有的负责执行、有的负责审查通过消息传递协作完成任务。适合任务复杂度高、需要角色分工的场景。但我要泼一盆冷水多智能体不是银弹通信协议、任务分配、死锁检测都是新增的复杂度业务没到那个体量的时候单 Agent 加好工具往往比多 Agent 更稳定。3.2 撑起一个 ReAct 循环的最小运行时架构不管用哪条路线一个完整的 ReAct 循环都需要六个基础组件我把它们称为“最小运行时架构”。模型网关统一封装不同模型提供方的调用接口支持超时、重试、限流上下文管理器负责维护消息上下文、截断策略、核心信息注入工具注册表与执行器管理工具元数据执行工具调用并返回结构化结果循环控制器调度“思考-行动-观察”的迭代执行终止策略记忆模块管理短期会话记忆和长期向量记忆事件总线与日志记录每个环节的输入输出方便追踪和评估这里我想重点展开上下文管理器因为它是在实操里头号翻车点。ReAct 循环里每轮工具结果都要拼进消息列表几轮之后 Token 数就上去了。如果不做管理轻则上下文超限重则模型注意力被旧消息稀释表现断崖式下降。我常用的策略是三段式固定不变的系统提示放最前面最近 N 轮对话和工具结果放中间当前正在处理的任务指令放最后。超长历史做摘要压缩摘要有损所以只压缩“已经完成”的轮次当前轮次永远保留完整信息。3.3 框架选型的判断清单不要因为“热”就选我这些年帮人看过不少选型方案也自己经历过反复横跳最后提炼出一张判断清单照着打一遍分基本不会选错。第一项是社区活跃度。看最近三个月有没有持续发版、Issue 响应速度如何、文档是否有人维护。开源框架如果社区死了你就是在给自己埋坑。第二项是协议规范性。重点看它是否遵循标准的工具调用协议、消息格式标准。框架内部的抽象可以自定义但对外接模型、接工具的协议最好符合通用标准否则你将被绑定迁移成本极高。第三项是可观测性。看运行时是否暴露了完整的 trace 信息、每个节点的输入输出是否可导出。Agent 应用与普通后端应用不一样模型输出的不确定性导致 bug 难以复现没有好的可观测性线上问题你将无从下手。第四项是扩展成本。不要看 Demo 跑得多快要看“加一个自定义工具要改几个文件”“换一个模型服务商要动哪些代码”“流式输出支持得怎么样”。这些才是日常开发的真实成本。4. 重量方案完整 Harness Runtime 的设计与实现4.1 Harness Runtime 的核心职责安全、稳定、可控当你的 Agent 要跑长时任务、并发执行、调用外部系统时就需要一个完整的 Harness Runtime。它本质上是一个“专为 Agent 设计的执行环境”核心职责用六个字概括安全、稳定、可控。先讲安全。Agent 执行工具时可能触发外部命令、访问文件系统、调内部 API、甚至写数据库。每一条都是风险点。我的做法是分级纯函数工具走白名单机制文件操作走沙箱目录命令执行走独立容器或子进程网络请求走受控代理。再讲稳定。长时任务意味着进程可能崩溃、网络可能断、模型可能超时所以运行时必须要有断点持久化和自动重试。状态快照每隔一段时间落一次盘重启后从最近的快照恢复。然后是可控。运行时必须暴露完整的控制接口包括暂停、恢复、取消、注入人工消息。当 Agent 在不确定时应该停下问人运行时就要能挂起任务等人回复后继续跑。这个“人机协同”能力是完整 Runtime 区别于普通循环脚本的最大标志。4.2 调度与执行单元任务队列、沙箱与资源限制完整 Runtime 里我建议抛弃“一次任务对应一个进程”的朴素模型改成“任务队列加执行槽”的设计。任务进队列由调度器按优先级和资源空闲度分发给执行单元每个执行单元对应一个独立的 Agent 运行实例。执行单元内部有独立的 Token 配额、时间配额、内存配额。这样设计的好处是多个任务可以并发而不互相干扰单个任务跑飞了不至于拖垮整个系统。沙箱这块是执行单元的基石我用三层隔离来搭。第一层是容器级隔离跑不可信代码时用第二层是进程级隔离跑可信但可能有 bug 的代码时用限制 CPU、内存和运行时长第三层是环境级隔离给 Agent 一个专属的临时工作目录。三层隔离的触发逻辑是看工具的风险等级。只读操作不需要沙箱写文件操作进工作目录执行代码进进程级隔离需要网络操作的则进容器级隔离。资源限制不只在执行侧模型调用侧也要限。我踩过一个大坑Agent 循环里某一步传了太多内容导致模型响应超时程序不对超时做任何处理整个任务卡死既不报错也不退出。后来我在模型网关上加了响应时间监控超时即中断本轮把超时信息作为工具结果回传让模型自己决定是精简输入还是换一种处理方式。4.3 状态持久化与断点恢复快照设计状态持久化是完整 Runtime 与脚本循环之间的一道分水岭。脚本循环的问题在于状态都存在内存里进程一挂就什么都没了。完整 Runtime 则必须把状态外置。我设计的快照分三层。第一层是会话快照保存消息历史、任务描述、上下文状态。第二层是进度快照保存当前执行到哪个环节、中间结果、依赖的工具调用记录。第三层是数据快照保存 Agent 在沙箱里产生的文件变更。三层快照分开存恢复时按需加载。快照频率不是越高越好。我试过每轮循环都落盘结果 IO 开销大得惊人长任务的性能被拖垮了。后来改成“关键节点落盘”策略工具调用前后、生成最终答案前、收到人工指令时这三个节点必须落盘其他中间状态只记内存这样既保证了崩溃恢复的最小损失又不会让性能崩掉。恢复流程也很有讲究。原则上没有银弹我一般分两级先恢复到最近的会话快照让 Agent 重新加载上下文继续跑如果进度快照显示某步工具调用已经执行完但结果没来得及保存就标记该步骤为“可重放”用幂等设计避免重复执行产生副作用。4.4 人机协同与可观测性Runtime 的“驾驶舱”最后一个关键模块是“驾驶舱”。我认为一个成熟 Runtime 必须具备两个驾驶舱能力人机协同接口和全链路可观测面板。人机协同接口解决的是“Agent 不确定时怎么办”的问题。我实现了一个ask_human工具Agent 在决策树里遇到低置信度分支时调用它运行时收到后把任务状态标记为waiting_human暂停继续执行同时把需要人决策的问题和可选方案推送给前端。用户确认后选择结果作为工具返回值继续推进。这里有一个设计细节等待人工响应时任务要支持超时自动降级比如 24 小时无人响应则执行默认策略避免任务无限期挂起。可观测面板则是给开发者和运维人员用的。我强烈建议运行时从第一行代码就埋点而不是事后补。每条链路至少要记录模型调用的输入输出 Token 数、单轮延迟、工具执行耗时和结果摘要、循环轮次、状态转移事件。有了这些数据你才能回答“这个 Agent 为什么这么慢”“它为什么在这一步反复重试”“哪个工具调用最不可靠”。我见过不少团队在 Agent 上线之后两眼一抹黑出了问题只能“重新跑一遍试试”。在 Agent 这种充满不确定性的系统里没有可观测性相当于盲飞。要我说可观测性建设投入的精力至少应该占 Runtime 开发的四成。4.5 演进路线从轻到重的平滑迁移最后聊一个很现实的问题我已经用轻量方案跑通了业务怎么平滑迁移到完整 Runtime而不是推倒重来我的建议是围绕工具层做兼容围绕调用层做抽象。也就是说工具函数本身不要动只把“工具注册、工具调用、结果回传”这层逻辑封装成标准接口。这样轻量方案里的工具代码可以直接复用。迁移过程分三步走。第一步先把工具调用层抽成独立的服务接口让应用层和模型层都通过 HTTP 或内部 RPC 调用它。第二步引入循环控制器把“手写 while 循环”替换成框架或自研轮子原有消息结构保持兼容。第三步你要逐步加上持久化、沙箱和可观测性。这里说一个实操里的细节迁移时旧任务还在线上跑新老系统会有一段时间并行。我建议做一层“适配器”让老代码看起来像新运行时的一个执行单元而不是要求所有任务立刻切换。这样你能先用一小部分流量验证新架构的稳定性再逐步放大流量风险会小得多。5. 典型场景案例拆解不同架构方案的落地对照5.1 案例一客服工单自动分类系统轻量方案某电商公司的客服团队每天收到上千个工单需要自动分类、打标、转派。这个场景我用的是轻量方案加结构化输出。具体做法是定义好分类枚举、优先级枚举、转派部门枚举后把这些枚举和字段描述直接放进函数签名里让模型走 Function Calling 路径输出。接了一层 JSON Schema 校验和失败重试后准确率从最初的 92% 提到了 97% 左右。这个项目从头到尾没有引入任何 Agent 框架没有 ReAct 循环上线后运维也很简单。日志里只需要记录“输入工单、模型原始响应、校验结果、最终输出”四样东西排查问题非常轻松。如果你也遇到类似需求我的建议就是别被“AI Agent”这个词忽悠了能一次调用解决的事情就不要往复杂里做。5.2 案例二智能调研助手中量方案另一个做内部运营的朋友要做“智能调研助手”输入一个主题Agent 自动搜索、阅读、整理、输出调研报告。这就是典型的中量方案场景。我帮他定的是一个 ReAct 循环加少量工具搜索引擎工具、网页正文提取工具、要点归纳工具。循环控制设定最大 15 轮每轮做完一个子任务就更新“调研笔记”最终把笔记汇总成报告。上下文管理用了摘要压缩策略把已完成的搜索结果压缩成要点避免 Token 爆炸。实测下来的坑是搜索引擎返回的噪音信息太多Agent 容易被无关内容带偏。后面我加了一个“信息可信度评分”前置步骤让模型先对搜索结果做一轮相关性过滤再进入正文提取。这个优化之后报告质量提升非常明显。5.3 案例三后台数据分析与自动监控 Agent重量方案第三个案例是“后台数据分析与自动监控 Agent”需要定时触发、数据异常检测、自动排查归因、生成处置建议还要支持人工干预。这个必须上完整 Harness Runtime。架构上采用任务队列加多执行单元设计。监控任务每五分钟触发一批每个异常事件生成一个子任务进入队列由多个执行单元并发处理。每个执行单元里有独立的模型 Token 配额和沙箱工作目录。状态快照在每个异常事件的关键分析节点落盘系统重启后可以从中断处继续排查。人机协同这块是这样用的当 Agent 判断异常可能是重大故障时会调用ask_human工具把已经收集到的证据链、推测原因、可选处置方案推给值班人员等待确认后再继续执行。值班人员在面板上点一下“按方案一处置”Agent 就继续往下做。这个设计极大提升了运维团队对 Agent 的信任度。6. 常见问题与排查技巧实录6.1 工具调用死循环不是模型的问题是控制逻辑的问题Agent 在工具调用里陷入死循环是我被问得最多的问题。现象是 Agent 反复调用同一个工具每次都拿到相似结果然后继续调用直到达到最大轮数。排查思路先别急着怀疑模型。我第一步是打开 trace 日志看每轮模型的思考内容。如果思考内容显示“我要再调用一次确认结果”说明模型陷入了“确认偏误”这时候应该做的是在 Prompts 里加一条规则“如果上一轮工具结果已经足够支持决策不要重复调用”。如果思考内容显示“调用结果不符合预期尝试换一种方式”但工具列表里没有更合适的工具说明工具覆盖度不够需要补工具。实操中最管用的防御是多设一道“重复调用检测”同一工具连续调用超过三次且参数基本一致时循环控制器主动插入一条提醒消息告诉模型“您已经调用过该工具且结果未变化请基于已有信息继续推进”。实测效果立竿见影。6.2 上下文越权与 Token 爆炸三招控制长期运行内存长时任务跑久了最后崩溃在 Token 超限上这是重量方案里最典型的翻车场景。我的经验是三个招配合用。第一招是分层摘要。系统提示和核心任务指令永远完整保留工具执行结果只保留最近两轮的完整内容再往前的统一压缩成一句话摘要。第二招是上下文裁剪计划。每五轮循环检查一次 Token 总量超过阈值就触发一次“历史压缩”压缩过程本身也是一次模型调用因此要把压缩结果标记为“已压缩”避免下次再被压缩。第三招是主动遗忘。与当前任务无关的历史消息直接丢弃只保留摘要。这三招配合下来我最长跑过一个 40 轮的工具调用任务Token 消耗稳定在可控区间。6.3 工具调用副作用与并发安全幂等设计和锁工具调用的副作用问题在并发场景下会放大。比如一个 Agent 在写数据库另一个 Agent 在删除数据两个的决策依据可能互相冲突。我建议在两个层面做防护。工具层面凡是写操作统一要求幂等通过请求 ID 去重。运行时层面每个 Agent 的沙箱和外部资源访问通道做隔离共享资源访问必须走带锁的 API 网关。有一次我排查了半天最后发现是两个并行 Agent 同时在处理同一个业务对象产生覆盖写加一把分布式锁就好了。6.4 常见问题速查表问题现象排查方向推荐解法模型反复调用同一工具检查思考内容与工具覆盖度重复调用检测 提醒消息Token 超限崩溃检查历史消息累积量分层摘要 裁剪计划任务中断后无法恢复检查快照落盘频率与内容关键节点落盘策略并行 Agent 互相干扰检查共享资源访问幂等设计 分布式锁模型输出不稳定检查校验与重试链路校验失败回传模型重试线上问题无法复现检查链路追踪完整性埋点从第一行代码开始6.5 最后分享一个我的排障习惯排查 Agent 线上问题我从来不看应用日志里的 Error 堆栈而是先看 trace 链路里“最后一步成功的工具调用”是什么。Agent 问题的根因几乎总在“某一步我们以为成功的操作实际产出了错误结果”而错误结果被当作正常输入喂给了下一步。顺着链路回放通常很快能定位到问题点。个人体会是Agent 架构选型这件事最怕的不是选错而是不知道自己为什么选。你把需求维度拆清楚把每一档方案的边界搞清楚把运行时该有的骨架搭起来剩下的无非是在实践中持续调优。我做的这三个案例从轻到重都跑通过生产环境过程中踩过的坑远比写出来的多但架构上只要大方向对了小问题都好修。希望这份从实践里沉淀的方案能帮你少走一些我没避开的弯路。