AI Agent架构选型与Harness Runtime技术实现方案

去年帮一个团队做内部自动化时我一开始天真地以为只要把大模型 API 接进来把工具函数写清楚再给模型一条“你可以调用这些函数”的指令一个 AI Agent 就能跑起来。结果上线第一天模型就对着“发送邮件”工具反复调用了 17 次每次都因为参数里少了收件人而报错但它就是不学乖也不问我。那天凌晨我在日志里看到一串串重复的 tool_call 记录才真正意识到一个问题从一次 LLM 调用到一个可靠的 AI Agent中间差的不是代码量而是整个运行时架构的设计。这个标题里的信息量其实很大——“AI Agent 架构怎么选”是一个决策问题“从一次 LLM 调用到完整 Harness Runtime”是一条演进路径“技术实现方案”才是这篇文章真正要交付的东西。我下面会完全按我自己从零搭一套 Harness Runtime 的完整经历来讲包括为什么一开始只在“调用模型”后面不得不引入 Agent 循环再进一步把工具、权限、超时、追踪全部收进一个运行时里。这篇文章适合正在做 LLM 应用、准备从“单次调用”切换到“自主循环”的团队也适合那些已经被 Agent 循环搞到失控、想知道到底缺了什么的人。1. 想清楚再动手Agent 本质与选型第一原则1.1 一次 LLM 调用的能力边界先把“一次 LLM 调用”这件事说透。它本质上是一个无状态的文本转化过程你输入一段 prompt模型根据训练得到的参数分布输出一段补全文本。它很适合做摘要、翻译、情感分类、结构化信息抽取这类“输入确定、输出可预期”的任务。比如给一段客户评价让它输出“正面/负面/中性”再加一句理由这种场景下根本不需要 Agent一次调用就够了。但一旦任务里出现“根据 A 的结果决定是否执行 B执行后还要校验 C失败了得换方案 D”这样的逻辑单次调用就彻底不够了。因为模型在单次生成时看不到执行后的真实世界状态。它生成的是一段“它认为应该执行的计划”而不是“基于真实反馈修正后的行动”。模型以为自己调用了数据库但它其实只是写了“调用数据库”这几个字模型以为邮件发送成功了但其实没有任何代码真正执行过发送动作。这个问题的本质是大模型只在语言空间内推理而 Agent 必须把语言空间里的决定映射到物理世界里的行动再把行动的结果反馈回语言空间。中间缺的这层“执行 反馈”机制就是 Agent 架构要解决的核心问题。1.2 Agent 的最小定义模型在循环中我给 Agent 下的一个极简定义是模型在一个可控的循环里重复“观察 → 决策 → 行动 → 再观察”的过程直到目标达成或触发终止条件。和普通 LLM 调用相比它多了一个关键的反馈回路。用生活化的比喻来说普通 LLM 调用相当于你让实习生写一段汇报他写完交给你就完事Agent 则相当于你给实习生配了电脑、账本、电话跟他说“去把这件事调查清楚遇到问题自己想办法实在不行再回来问我”然后他每做一步都会把结果带回到自己的思考里决定下一步怎么做。这个循环本身并不复杂复杂的是把它做“稳”。比如循环要跑多少轮模型同一个工具调用失败三次要不要停下来工具执行超时了算不算观察结果模型把工具返回的原始 JSON 读不懂怎么办这些都是在循环骨架之外的运行时问题也是这篇文章后半部分重点展开的内容。1.3 选型第一原则复杂度守恒定律很多人一上来就选最复杂的多 Agent 架构问原因回答往往是“因为这是 Agent”。但我在实际项目里得到一个非常强的经验复杂度不会消失只会转移。你用 Agent 循环换掉了手工写死的 if-else 流程就一定会在“控制循环次数、错误修正、上下文管理、安全边界”这些地方把复杂度找回来。所以选架构的第一原则不是“哪个听起来更先进”而是“哪个复杂度的位置你扛得住”。我给团队的选型建议基本上遵循这样一个表格方案形态适用场景优点主要成本单次 LLM 调用摘要、抽取、单轮分类实现最简单、成本低无法处理多步骤真实操作Prompt 编排工作流步骤固定、流程明确结果可控、易调试流程变化时要改代码单 Agent Harness工具多、目标开放、需要自主决策灵活度高、能自我修正需要运行时治理、追踪多 Agent 编排并行任务、领域隔离、技能分化并发高、职责清晰上下文隔离复杂、通信成本高以我实际经验至少 70% 的“Agent 需求”用“Prompt 编排 少量工具调用”就能解决根本不需要一个真正的自主循环。只有当你发现工具数量超过十个、模型需要在多个真实操作之间做选择和判断、并且失败后需要自主换路线时才值得把 Harness Runtime 这套东西建起来。下文的所有内容都是假设你已经决定了“我需要一个真正的 Agent 循环”之后怎么把它搭稳。2. 核心细节解析工具抽象与上下文管理2.1 让模型学会调用工具从一次函数调用说起要让模型从“只输出文字”变成“能发起行动”第一步是给模型定义工具。主流大模型 API 基本都支持类似 Function Calling 的机制你提供一组 JSON Schema 格式的工具定义模型在判断“需要调用工具时”返回一个结构化的调用请求而不是自然语言。这个机制是整个 Agent 循环的入口做得好不好直接影响后面八成的问题。一个工具定义通常包含三块名称、描述、参数结构。很多人把重点放在参数结构上却忽略描述的重要性。我的经验是描述里必须写清楚“这个工具是干什么的、什么时候用、什么时候千万不要用”。比如一个“读取文件”工具描述里光写“读取文件内容”是不够的要写成“读取服务器上指定路径的文本文件并返回内容。适用于用户询问文件内容、需要从文件中提取信息时。不适用于用户要求修改文件修改请使用另一个工具”。模型对工具的选择依据就是这个描述描述越模糊模型越容易乱调、误调。参数结构最好用严格的 JSON Schema把每一个参数的类型、枚举、必填约束都写清楚。还需要注意一点模型在生成参数时经常会“编造”不存在的值。比如它需要查一个订单号但用户根本没给模型会自己生成一个“ORD-123456”塞进去。这个问题不是靠约束能完全解决的后面会在运行时做参数校验和缺失参数反馈。2.2 上下文管理模型的记忆是有限且昂贵的Agent 循环里最容易被忽视的是上下文。每一轮循环你都要把“系统提示词 历史对话 工具观察结果”拼在一起发给模型而模型能处理的 token 是有限的成本也和 token 数量直接挂钩。很多 Agent 一开始跑得好好的到第 5 轮循环就开始胡言乱语原因就是上下文里塞进了太多工具返回的原始内容把模型的核心指令冲淡了。我在实际项目里常用的做法是分三层管理上下文核心系统提示词固定不变包含角色设定、工具使用规则、终止条件、输出格式要求。这层要精简不要超过 1000 字。任务上下文包含用户目标、当前计划、已完成步骤。每轮更新由代码维护而不是让模型自己总结。执行观察历史每次工具调用的结果按时间顺序追加。这层最需要控制长度对超长返回结果要先做截断或摘要再放回消息里。有一个很实用的技巧工具返回结果如果超过一定长度不要直接拼进上下文先在代码层用一个摘要模型对结果做压缩只把“关键结论 数据概要”塞回去。比如数据库查询返回了 200 行记录模型其实只需要知道“共 200 条其中状态为待处理的 35 条最早一条是三天前”。这既省 token又避免模型在细节里迷失。2.3 抽象一层 Tool Interface注册表与白名单直接写一个函数send_email(receiver, content)然后在 prompt 里告诉模型“你可以调用这个函数”看似可行但一旦工具数量增多问题就来了模型生成的工具调用和代码里的函数怎么映射函数内部执行失败怎么反馈某个工具只允许特定场景调用权限怎么控制这些都是模型层管不了的必须有一层代码来统一处理。所以我在搭建 Harness 时第一件事就是做工具注册表。每个工具不再是一个裸函数而是注册成带有元数据的一个“条目”包含工具名称、描述、参数 Schema、执行函数、权限标签、超时时间、可重试次数这些字段。模型调用工具时运行时通过名称找到对应条目执行代码逻辑然后把结果统一封装成一个标准化结构回传给模型。这个抽象最大的好处是解耦。模型只和“工具名 参数”打交道代码只和“注册表 执行函数”打交道。将来新增工具不需要改 Agent 循环的代码只需要注册新条目要下线工具也不需要动模型配置把注册表里条目禁用即可。安全边界也因此有了着力点——白名单、权限校验、审计日志都可以在这一层集中实现。3. 完整 Harness Runtime 的搭建过程3.1 Harness 是什么Agent 的操作环境如果 Agent 是大脑那 Harness Runtime 就是给大脑配备的整套“身体 感官 安全装甲”。它不是一个具体的算法也不是某个模型框架而是围绕 Agent 循环搭建的一整套运行时环境负责工具注册、执行调度、权限校验、资源隔离、生命周期管理、日志追踪和异常处理。目的只有一个把大模型这个不可控的组件装进一个可控的盒子里。我最早踩的坑就是只实现了“模型循环 两个工具函数”没有任何运行时管理。第一版跑起来很惊艳模型会自己查天气、查日历、写便签像个“有手有脚”的智能体。但一旦进入真实业务模型开始调用了不止两个工具、工具之间还有依赖关系时问题就像潮水一样涌过来工具超时、模型在循环里出不来、权限无边界地调删除接口、日志里根本看不出它哪一步做错了。第二版我花了大量时间补的全是这些“不性感”的运行时能力但恰恰是这些能力让 Agent 真正可以上线。3.2 核心模块拆分五个组件一个也不能少一个可用的 Harness Runtime 至少包含以下五个模块缺一个都会在某个时刻出大问题模块职责关键配置工具注册中心登记所有可用工具、参数 Schema、权限标签工具名、描述、Schema、执行函数调度器驱动“观察 → 决策 → 行动 → 再观察”循环max_steps、终止条件、循环节流工具执行器真实调用工具代码封装结果或错误超时时间、重试策略、异常捕获策略门禁权限校验、参数校验、行为审计白名单、黑名单、敏感操作确认追踪日志记录每一步的输入输出、耗时、成本结构化日志、事件流、trace ID我用一个类比的顺序来理解它们的关系调度器是主编决定稿子Agent 循环怎么推进工具注册中心是资料库告诉主编有什么素材可以用工具执行器是排版车间真正把素材变成文章策略门禁是审校想发出去的内容必须过审追踪日志是发稿后的存档出了问题能倒查是哪一位的锅。3.3 从最小循环开始一个可以跑的 Agent 骨架先给大家看一个最精简的 Agent 循环骨架我用伪代码写重点展示循环的结构而不是具体某个模型的 SDK 细节def agent_loop(user_goal): messages [system_prompt(user_goal)] step 0 max_steps 8 while step max_steps: response llm.chat(messages, toolsregister.get_tools_schema()) if response.is_tool_call: for call in response.tool_calls: # 策略门禁权限与参数校验 if not policy.check(call.tool_name, call.params): observation policy.reject_message(call.tool_name) else: observation executor.run(call.tool_name, call.params, timeout30) messages.append({ role: tool, tool_call_id: call.id, content: format_observation(observation) }) else: # 没有工具调用说明模型认为任务已完成 return response.text step 1 return final_answer(messages)这个骨架看起来简单但里面每一行在实际工程里都有讲究。max_steps8不是随手填的是根据任务特征评估的只有一两个工具依赖的简单任务3 到 5 步足够了涉及多工具编排、可能有失败重试的任务8 到 15 步合理超过 20 步的任务我一般会先怀疑是不是任务拆分出了问题。步数设得太小任务完不成设得太大成本和失控风险都会指数级上升。policy.check也是一个关键设计。工具调用不是模型说调就能调至少要做一层参数校验必填参数是否缺失、类型是否正确、枚举值是否合法。校验不过把错误信息返回给模型让它修正比直接在代码层面报异常要优雅得多。我后面会单独讲这一点。3.4 工具调用失败时的反馈路径一个关键实坑刚开始做工具调用时我最常犯的错误是工具抛了异常我就让 catch 直接返回“Error: xxx”给模型。结果模型经常不懂这个错误是什么意思也不会修正调用方式反而开始胡编。后来我才理解返回给模型的内容不是给人看的错误堆栈而是给模型看的“可行动的修正信号”。我的标准做法是工具执行器的 catch 会把异常包装成结构化的 observation包含三块信息def safe_execute(tool_func, params, timeout30): try: result tool_func(**params) return {status: success, result: result} except MissingParamError as e: return {status: error, error_type: missing_param, missing_fields: e.missing_fields, tool_name: e.tool_name, hint: 请根据用户已提供的信息补充这些参数如果用户确实没有提供请主动向用户提问} except TimeoutError: return {status: error, error_type: timeout, tool_name: e.tool_name, hint: 工具执行超时请确认必要参数后重试一次或换用其他方式} except Exception as e: return {status: error, error_type: unknown, message: f工具执行遇到未预料的错误{str(e)[:200]}, hint: 建议停止使用该工具调整方案后再试}模型的修正能力本质上是上下文能力。你给它的错误信息越“结构化”、越包含下一步动作建议它就越容易从错误中恢复。反之如果抛一段 Python 栈给它模型只会更懵。这个细节是我在实践中踩了很多次坑才明白的。3.5 执行沙箱与权限隔离控制 Agent 的行动边界Agent 一旦真实调用代码就等同于一个能操作服务器的“数字员工”。它的权限边界必须从一开始就缩到最小。我在生产环境对所有工具做了三层隔离第一层是接口层白名单。工具注册表里登记的工具必须经过评审每一个工具都有 owner 和权限标签。第二层是进程级隔离工具代码运行在受限制的子进程中与主服务分离设置独立的 timeout 和内存限制。第三层是环境隔离涉及文件操作的工具把执行环境挂载到临时目录用完即焚涉及网络操作的工具通过代理或防火墙白名单只允许访问指定域名。我见过不少团队把工具函数直接跑在 Agent 服务的主进程里连超时都不设。一旦模型的参数里出现一个野路径文件工具可能把整个系统目录扫一遍。这不是危言耸听模型在工具描述模糊的情况下完全可能做出超出预期的操作。所以任何 Agent 的 Runtime只要没有沙箱和权限控制我就认为它只能停留在 demo 阶段。在本地做验证的过渡期至少也要用子进程管理器把工具与主服务隔离并禁止工具直接访问真实业务数据库。3.6 可观测性没有 trace 的 Agent 等于盲飞Agent 循环的调试难度远高于普通接口。普通接口出错你只要看一次请求日志就能定位。Agent 出错时问题可能出在模型的决策上、工具的参数上、上下文的组织上甚至循环步数耗尽导致的截断上。没有一套完整的追踪系统你连“它到底在哪一步错的”都说不清。我的做法是为每一个用户请求生成一个 trace ID贯穿整个 Agent 循环。每一次 LLM 调用、每一次工具执行、每一次策略拦截都打点记录输入输出 token 数、耗时、模型返回的 text 或 tool_call、工具执行结果、是否符合预期等。日志层面全部结构化输出方便后续做统计分析。实际排查问题的时候我最常做的操作就是翻 trace看第几步开始模型的行为偏离了预期、工具返回了什么、模型是怎么理解那个结果的。曾经有一个“模型反复调用同一个失败工具”的线上问题我就是靠 trace 统计发现它在连续 6 步里的行为模式完全一致才定位到是工具描述里“何时不用”的信息缺失。没有这层追踪这个定位过程可能要多花好几天。4. 架构的分层决策三种落地路径怎么选4.1 阶段一LLM 调用 函数库 手工编排如果你的场景是“几个固定工具、流程基本确定”我不推荐你直接上 Agent 循环。比如一个工单分类助手先通过检索找到相似工单再用模型给新工单分类最后写入数据库。这个流程每一步都是确定的代码里用 if-else 或者状态机绑一下就行根本不需要模型自己决定要不要调工具。这种方案最大的优势是可控和便宜。模型只负责“分类”“抽取”这些语言任务真正的流程控制权都在代码手里任何一步出错都能快速定位。很多人觉得这是“不够 Agent”但我的观点是能用工程规则的就不用模型自由发挥能用一次调用的就不要让模型循环。把模型用在它最擅长的地方把逻辑确定性留给代码是最被低估的好架构。4.2 阶段二单 Agent Harness Runtime当工具数量超过十个用户请求又高度开放时模型必须在多个工具之间做选择、编排和失败重试这时候才需要真正的 Agent 循环和 Harness Runtime。我建议从单 Agent 开始把所有工具都注册到一个运行时里让模型在一个循环内自由规划和行动。单 Agent 阶段最容易遇到的问题是“工具太多导致选择困难”。我实测下来工具数量超过 20 个时模型在循环里选错工具的概率会明显上升。解决办法是给工具做分组比如“搜索类”“写入类”“审批类”并在系统提示词里加一句“先判断用户请求属于哪个域少量候选工具内再做选择”。更进阶的做法是在主循环前加一个轻量的意图分类节点把问题路由到特定的工具子集再把子集作为工具的 schema 传给模型。这是目前单 Agent 方案里性价比最高的优化手段。4.3 阶段三多 Agent 与编排层的取舍多 Agent 架构听起来酷但实际落地时通信成本、上下文隔离和协调复杂度都很高。我的判断标准是除非遇到下面三种情况之一否则不要上多 Agent。第一种工具域之间物理隔离比如业务数据在完全不同的系统里一个 Agent 的上下文装不下所有工具第二种任务可以自然并行拆解比如一段时间内要同时检索多个数据源、做多路分析再汇总第三种不同技能需要不同的工具集和不同的系统提示词硬塞进一个 Agent 会导致互相干扰。多 Agent 的编排方式我实际用过两种。一种是“主管-下属”模式主管 Agent 负责任务拆解把子任务分发给专精的下属 Agent再收集结果做汇总。另一种是“流水线”模式上游 Agent 的处理结果作为下游 Agent 的输入适合流程链条长且方向明确的场景。这两种模式的共同问题是子 Agent 之间共享什么、隔离什么必须非常清楚。我的建议是子 Agent 之间不要共享上下文只通过结构化消息传递结果各 Agent 的上下文保持独立。协作消息里要包含任务、约束、截止时间、返回格式否则子 Agent 之间很容易产生理解偏差。4.4 从轻到重的升级路径参考阶段工具数量循环控制需要投入的工程重点单次调用0-3无prompt 设计、输出解析编排工作流0-5代码控制状态流转、异常分支单 Agent Harness5-30模型循环工具抽象、运行时治理多 Agent 编排分组 20分层循环任务拆解、上下文隔离我的核心建议是“不跳级”。每上一个阶段都先确认当前阶段的痛点真的来自架构瓶颈而不是工具描述不清、上下文组织不合理或异常处理不到位。因为前三个问题修起来便宜得多而动一次架构贵得多。5. 常见问题与排查技巧实录5.1 Agent 在同一工具上反复失败死循环这是我在生产环境遇到最多的一个问题特征非常明显同一轮任务里模型连续多次调用同一个工具参数几乎不变每次都是相同的错误但它就是不换方案。排查时我先看 trace 里的same_tool_call_repeat_count统计同一个 tool_call id 出现的次数。如果大于 3基本可以断定模型的修正能力没有生效。根因通常有两个。一个是工具返回的错误信息太模糊模型看不懂怎么修正另一个是工具描述没有写清楚“什么时候不要用”模型觉得自己“必须用这个工具才能完成任务”。修复方法也很直接把错误反馈结构化在 hint 里明确给出修正方向同时在工具描述里补上“不适用于什么场景”。我还有一个比较硬的兜底策略在 Runtime 层统计同一工具连续失败次数达到 3 次时不再把错误返回给模型循环而是直接中断循环让位给人工干预或备选流程。这个兜底能避免大量 token 浪费。5.2 模型乱调工具或参数幻觉模型把“查询天气”调成“查询股票”或者给“发送提醒邮件”编造一个用户并不存在的邮箱地址这类问题都属于工具正确性失控。排查先看 trace 里模型在调用前的思考文本通常它会说明“为什么选择这个工具”。如果发现思考逻辑是合理的只是工具选错了那大概率是工具描述之间的边界不清晰模型难分辨如果模型自己都说不出理由那就是工具数量太多、选择空间太大导致随机性上升。修复路径有几个层次。第一层是做工具分组让模型在小范围候选里选第二层是给工具描述统一加“使用场景”和“不可使用场景”两个字段把边界描述清楚第三层是参数校验对模型生成的关键参数做合法性检查比如邮箱格式、日期格式、ID 是否存在于数据库。前两层减少错误发生的概率第三层保证错误发生时被拦截而不是继续传播。5.3 上下文爆掉导致行为前后矛盾Agent 循环跑得越久上下文里的历史越臃肿模型越容易被“新信息淹没旧指令”。典型症状是任务执行到后半程模型忘记最初的用户目标开始根据最近的工具结果自行发挥。排查时我会看 trace 里每轮传入的 token 数如果后几轮的 token 数比第一轮翻了五倍以上就要警惕上下文污染。解决办法是严格控制观察历史的长度。工具返回的长文本一律先截断优先保留结论和统计量每轮循环结束由代码重构一次消息历史把不重要或重复的观察折叠成一行摘要。还有一个我常用的小技巧系统提示词里加一条“始终记住用户最初的目标是{目标摘要}”在当前轮回复里强制回显用户目标这个简单的约束能显著降低模型跑偏的概率。5.4 工具执行结果被模型错误解读工具返回的内容是对的但模型理解错了。这类问题在 trace 里很隐蔽因为它不报错只是最终答案跑偏。比如工具返回“库存 0 件”模型却在最终总结里说“该商品有货”这种错误常常是模型在总结时凭语言惯性补完了信息。我的做法是两层校验。第一层在工具执行器里对涉及关键状态的结果做一次规则化摘要并把“结论先行”放在返回内容的最前面比如“结论缺货。明细……”。第二层在最终输出前加一个独立的校验调用用一个小模型或同样的模型对最终答案进行一次“与观察结果一致性检查”把矛盾的点挑出来。这等于找了一个“第二读者”来校稿虽然多花一点钱但对关键场景非常值得。5.5 成本失控与限流兜底Agent 循环的成本天然比单次调用高因为每一轮都是一次完整模型调用。如果不对成本做约束“模型多尝试几次”的成本可能会超过业务收益。我在 Runtime 里做了三个成本控制点一是单任务总 token 预算预算用尽直接终止循环并通知管理员二是工具调用失败的快速熔断连续失败达到阈值不再重试三是响应缓存对固定 prompt 前缀的模型请求做精确匹配或语义近似缓存能减少重复计算。实测下来这三个控制点能把单任务平均成本压到不设控制时的三分之一左右。最后说一个我自己的体会。很多人问 Agent 架构的关键是什么我现在的答案已经不再是“模型选哪个”“要不要上多 Agent”而是“你愿意花多少精力把模型以外的运行时做扎实”。我记得搭建第二版 Harness 时绝大部分时间都花在工具注册、超时管理、错误反馈、追踪日志这些看起来毫不惊艳的模块上。但正是这些模块让 Agent 从“偶尔惊艳的 demo”变成了“可以交给非技术用户使用的工具”。如果你现在正打算上 Agent我的建议是先把 3.3 节那个最小循环跑通然后立刻开始补“错误反馈结构”“步骤上限”“追踪日志”这三件事。这三件事不用花你太多时间但它们会在你上线后替你挡住无数个凌晨三点的告警。