AI Agent架构演进：从单次LLM调用到Harness Runtime的完整路径

最近身边不少团队都在同一个问题上打转：AI Agent架构到底怎么选？有人用一次LLM调用就把Demo跑通了，觉得再上复杂框架纯属折腾；也有人一上来就直奔完整的Harness Runtime，结果被状态同步、异常恢复、日志回放这些事拖得筋疲力尽。这个问题难就难在，它没有放之四海而皆准的答案，只存在一条从“单次调用”逐步走向“完整运行时”的演进路径，而你要先搞清楚自己当前站在路径的哪一格。

这篇文章我会把这条路径完整拆开讲清楚：一次LLM调用在什么场景下就是最优解，引入工具调用和Agent循环之后会新增哪些复杂度，最后重点落到Harness Runtime——它到底在运行什么、核心组件怎么拆、有哪些最容易被忽略的细节，以及如何从“一个会调LLM的脚本”平滑迁移到能上线的Runtime。适合正在做Agent技术选型、手头已经有调用脚本、或者正卡在“能跑但不敢上线”阶段的开发者看。

1. 先别急着选架构：Agent复杂度从一次调用到一套运行时

1.1 一个反直觉的事实：一次LLM调用往往是正确答案

很多人觉得Agent听起来高级，任务就一定要拆成多步。其实不是这么回事。相当一部分真实需求，比如工单分类、邮件信息抽取、合同关键项比对、商品描述润色，用一次LLM调用配上结构清晰的Prompt，效果已经完全够好，而且延迟低、成本低、出了问题好定位。

原因在于：这类任务的输入输出边界非常清楚，模型拿到一段完整信息，经过一次推理就能给出确定性的结果，中间根本不需要额外的“计划”“执行”“反馈”环节。如果这时候硬加一个Agent循环，你会给自己引入一大堆跟业务无关的问题：中间状态存在哪、任务什么时候算结束、工具调用失败要不要重试。这些复杂度并不会提高结果质量，反而会让系统变得更脆弱。

所以我的建议是，先用最朴素的方式把业务价值跑通，再根据真实出现的缺陷决定要不要升级。判断原则就一句话：如果任务能在一次推理里完成，就别让模型多绕弯路。所谓“Agent能力”，从来不是架构越重越好，而是刚好够用。

1.2 工具调用带来的转折：模型从“回答”变成“行动”

当任务开始需要实时数据、精确计算，或者要联动内部系统时，就自然走到第二步：给模型接工具。这一步的质变在于，模型输出的不再只是自然语言，而是一个结构化的“工具调用意图”。系统拿到这个意图后负责执行真实函数，再把执行结果放回上下文，让模型据此继续推理。

最朴素的实现并不复杂：给每个工具写一段JSON Schema，描述工具名称、用途、参数结构。请求时把Schema列表和用户问题一起发给模型，模型如果需要使用工具，就会返回类似“调用某函数并传入这些参数”的结构。你用解析逻辑取出函数名和参数，执行完把结果追加进对话，再发给模型。

这个阶段要留意一个很现实的问题：模型偶尔会“幻觉”出工具根本不需要的参数。比如一个查询天气的工具只接受城市名，模型却顺手传了一个日期，校验直接不通过。正确的做法不是抛异常，而是把“参数校验失败”的提示作为结果回填给模型，让它自己纠正。这也是后面Harness里“错误即上下文”理念的雏形。

不过，工具调用最常见的形式仍然是一轮或两轮的短链路，模型在同一轮请求里通常不具备把多个工具动作编排成完整任务的能力。等你的需求变成“先查航班，再订酒店，最后发通知”这类多步骤执行，就得引入一个真正的Agent循环。

1.3 最复杂的那一端：Harness Runtime到底解决了什么

当任务从“回答一个问题”变成“自主完成一套动作”，你就需要走到第三级方案，行业里常叫它Harness Runtime。很多人第一次听到这个词容易懵，其实它就是把Agent决策循环“产品化”的一组运行时组件，解决的问题非常具体。

首先是循环控制。Agent必须能自主决定多轮执行，直到目标达成或者触发终止条件。其次是状态存储。多步任务中间会产生大量局部结果，比如查到的航班号、筛好的酒店清单，这些必须被安全保存下来，任务中断后还能恢复。第三是工具生命周期。一个工具调用从注册、校验、执行到超时处理、失败重试，需要有统一管理，而不是散落在业务代码里。第四是可观测事件。每一步的思考、决策、工具返回都应该有记录，否则上线后出了问题连复盘都无从下手。最后是策略注入。最大步数、危险操作审批、用户确认这类规则，要能灵活配置。

做个类比：一次LLM调用就像一个快餐窗口，你报需求、它给结果；加了工具调用之后，像你指挥一个临时外包工，能干几件具体的事；而完整的Harness Runtime，相当于把临时工签成正式员工，给他配工牌、派工单、操作SOP，出事还能回溯。

这里要特别强调一句：层级高不代表更好。把简单单轮任务塞进完整Runtime，等于在小区门口小卖部旁边建大型仓储系统，浪费且难维护。复杂度层级一定要匹配任务的不可预测性。

2. 选型前必须想明白的四个决策点

2.1 状态放哪里：无状态优先，别急着引入存储

架构选型里最容易被忽略的点就是状态。对一次LLM调用来说，状态几乎可以忽略，因为输入进、输出出，不需要记录中间值。但一旦进入多轮Agent循环，状态就成了头等大事：模型上一轮做的决策、工具返回的结果、已经完成的部分目标，都要能被下一轮读到。

我的经验是默认无状态，只有当任务确实需要跨步骤读取中间结果时，才引入状态存储。更准确的说法是，写第一版代码时就建议把状态存储抽象成一个state_store接口，哪怕内部先用内存字典实现。因为后续大概率会遇到这些情况：服务重启、任务挂起、多人协作，都需要把状态从内存搬到外部存储。接口提前留好，替换成本会低很多。

2.2 工具怎么定义和调用：协议比工具本身更重要

工具接入没有想象中那么简单，真正花时间的是定义一套稳定的调用协议。一个工具协议至少需要四样东西：名称、用途描述、输入参数JSON Schema、执行函数。复杂场景还要加超时时间、权限标记、是否需要用户确认等字段。

用途描述和参数Schema是模型选择工具的依据，描述写得越具体，模型越不容易选错。拿一个“查订单”工具举例，如果描述只写“根据订单号查询订单”，模型很难判断什么时候该用；如果改成“当用户询问订单状态、物流信息、支付结果时，根据订单号查询订单详情，订单号必填”，效果会明显不一样。

调用边界也要注意。工具函数内部一定会访问外部系统，比如HTTP接口、数据库，所以必须统一做超时控制、限流和异常捕获。异常信息不要吞掉，也不用直接向上抛，应该序列化成一段简短文本回填给模型。模型看到错误信息后，通常会自行调整参数或换策略，这本身就是一种天然的容错机制。

还有一个容易被忽略的边界是权限。工具能调通，不代表它应该向所有用户开放。比如“更新订单状态”这类写操作工具，要加一个permission标记，在Runtime里统一做鉴权；敏感操作直接进入人工确认流程，绝不自动执行。

2.3 上下文窗口不是越大越好：积累得越多，污染风险越高

多轮Agent最绕不开的痛点是上下文长度。很多人以为把窗口调大就能解决问题，实际恰恰相反。在Agent任务里，真正吃掉Token的是不断累积的历史消息和工具返回结果，而不是System Prompt。

所以每次请求前都要做一次上下文组装：System Prompt固定携带核心规则；对话历史保留最近N轮，更早的滑动丢弃；工具返回结果如果特别长，先摘出关键字段再回填，而不是原样塞回去；如果有必须长期记住的关键信息，比如用户的偏好、任务的最终目标，建议单独维护一个“常驻记忆区”，每次组装时拼进System Prompt。

截断是有风险的。一旦早期约束被挤出上下文，模型行为就可能漂移。我见过不少案例，Agent前几轮还很听话，后面突然频繁调用某个工具，查日志发现是最早那条“只在必要时调用”的指令被挤出了窗口。这类关键约束必须放进不可裁剪的System Prompt区域，不能指望它们一直留在对话历史里。

2.4 可观测性：跑起来之前先想好怎么“回头看”

Agent和普通接口最大的区别是难以复现。普通接口输入输出可枚举，出Bug调用一次就能重放；Agent的每次运行都依赖前面若干轮的模型决策和工具返回，中间状态一旦没记录，后续排查就全靠猜。

从第一天起就该在代码里埋结构化日志，至少包含：请求ID、LLM的完整输入和输出、当前轮次、模型生成了哪个工具调用、工具返回结果或错误信息。不要偷懒不记LLM输入，因为很多诡异问题正是由上下文被截断或污染导致的。

我常被问的一种情况是：Agent做了一次错误操作，没人说得清为什么。回放轨迹日志后往往发现，问题源头在十几轮之前某条工具返回被截断，模型少看了一个关键字段。没有轨迹日志，这种问题几乎无法定位。所以可观测性不是上线前的加分项，而是Agent系统的基础设施。

3. Harness Runtime到底在运行什么：核心组件逐个拆开

3.1 五个核心组件一起协作，才叫Runtime

把Harness Runtime拆开看，核心可以收敛成五个组件。第一个是LLM Client，负责统一封装模型访问，包括重试、超时、Token统计、模型版本切换。第二个是Tool Registry，也就是工具注册中心，保存从工具名到执行函数、校验规则、权限标记的映射。第三个是State Manager，负责状态的装载、保存和恢复，对外只暴露“读取当前上下文”和“写入最新状态”两个方法。第四个是Agent Loop，这个循环是整个Runtime的心脏，负责调用模型、解析意图、执行工具、判断终止，循环往复。第五个是Event Bus，负责把每一步事件推给日志系统、监控系统、人工审批入口等订阅方。

用一句话连接它们：Agent Loop从State Manager里拿上下文，通过LLM Client拿到模型决策，再从Tool Registry里找到对应工具执行，执行结果交回State Manager保存，整个过程每一步都向Event Bus广播。

你可以这么理解：Agent Loop是大脑，State Manager是记忆体，Tool Registry是手脚，Event Bus是对外广播站。五者缺一个，你都只能在最简陋的循环里打转。

3.2 一次任务在Runtime里是怎么流转的

看一遍完整生命周期，比读十段概念都管用。用户提交一个任务之后，Runtime按照下面的顺序执行：

1. 创建任务上下文，把系统级提示、用户输入、历史记忆一并装入State Manager。
2. Agent Loop调用LLM Client，传入组装好的消息列表。
3. 解析模型返回结果，判断是“直接输出最终答案”还是“需要调用工具”。
4. 如果是最终答案，校验是否满足任务目标，满足则结束循环，不满足则回到第2步。
5. 如果是工具调用，从Tool Registry中取出执行函数，做参数校验和权限检查。
6. 执行工具，捕获异常，把执行结果或错误信息转换成观察结果。
7. State Manager保存新状态，Event Bus发出一条工具执行事件。
8. 回到第2步，直到触发终止条件或达到最大步数。

用伪代码表达核心循环会更直观：

class HarnessRuntime: def __init__(self, llm_client, tool_registry, state_manager, max_steps=10): self.llm_client = llm_client self.tool_registry = tool_registry self.state_manager = state_manager self.max_steps = max_steps def run(self, task_id, task): ctx = self.state_manager.create(task_id, task) while not self._should_stop(ctx): messages = ctx.build_messages() response = self.llm_client.chat(messages) intent = self.llm_client.parse_intent(response) if intent.is_final_answer(): ctx.mark_finished(intent.answer) break tool = self.tool_registry.get(intent.tool_name) if tool is None: ctx.add_observation(f"Error: unknown tool {intent.tool_name}") self.state_manager.save(ctx) continue try: result = tool.handler(**intent.args) except Exception as e: result = f"Error: {e}" ctx.add_observation(f"{tool.name} returned: {result}") self.state_manager.save(ctx) return ctx.result() def _should_stop(self, ctx): return ctx.is_finished() or ctx.step_count() >= self.max_steps

这段代码是高度简化版，但抓住了Runtime的关键动作：每一轮都从状态管理器重建消息，执行工具后立即保存状态。生产级实现会在这些主线上叠加并发控制、审批、重试，但骨架不会变。

State Manager真正要做的，不是往内存里塞一个Python对象，而是把Context序列化成JSON，落到Redis或数据库。恢复的时候按task_id把数据取出来，重新构建Context。这样进程重启不会丢任务，也才能支撑真正的异步长任务。

3.3 三个最容易写错的关键细节

第一个细节是终止条件。只设置max_steps远远不够，因为Agent可能在到达步数上限前就陷入无意义循环。我建议至少同时支持三种终止信号：任务目标已满足、模型主动给出最终答案、外部策略判定应该结束。比如让Agent“整理一份会议纪要给所有参会人发邮件”，它可能第一步查完参会人列表后反复重新查询，而不是去调用发邮件工具，就是因为缺少“发送成功即视为目标达成”的策略。没有明确的终止条件，Agent会变成“永远在努力”的永动机。

第二个细节是工具执行的并发控制。模型有时会在一次响应里请求执行多个工具，别急着并行，尤其是这些工具可能修改共享状态的时候。初期统一串行执行，慢一点没关系，换来的是状态一致性和可回放性。等你能接受并行，也要先确认不同工具之间没有写冲突，再把它们分成组并发。

第三个细节是默认“错误即上下文”。工具调用失败不要直接中断整个任务，把错误信息当作一次观察回填给模型。模型有机会自行纠正，要么换参数，要么换工具。当然要有兜底：同一个工具连续失败达到阈值，就升级为人工处理或直接结束任务。

4. 从一次LLM调用平滑演进到Runtime的落地路径

4.1 别推倒重来：四步渐进改造，每一步都有可运行产物

很多人问“我到底要不要直接上Runtime”，我的建议通常很明确：不要一步到位，按四步渐进改造，每一步都先跑通，再进入下一步。

第一步，把模型调用封装成统一接口。不管后端用哪个模型服务，业务侧只面向一个client对象。这一步能让你后续随时切换模型或统一统计调用量。可运行产物是：一个接受消息列表并返回模型响应的小模块。

第二步，增加工具调用与响应回填。定义好工具Schema和执行函数，模型返回工具调用意图后，由同一个client接口触发执行，再把结果拼回消息列表。可运行产物是：一次会话里模型能调用真实工具并基于结果回答用户。

第三步，在业务层引入外部循环。把“发请求—解析意图—执行工具—回填结果”包成一个while循环，并加上最大轮次上限。可运行产物是：模型能自主完成至少三个步骤的任务，中间不需要人介入。

第四步，把循环收敛进Runtime类，同时补充状态抽象、事件日志、策略配置。可运行产物是：一套能被多个任务共享的Harness运行时。走到这一步，再回头审视哪些组件需要真正工业化。

4.2 一份可供参考的最小Harness骨架

为了让渐进路径更具体，我整理了一份最小可运行的设计骨架。它没有依赖任何具体框架，接口与工具都可替换。

from dataclasses import dataclass, field from typing import Callable, Dict, List @dataclass class Tool: name: str description: str schema: dict handler: Callable timeout: float = 10.0 @dataclass class StepRecord: step: int intent: dict observation: str @dataclass class Context: task: str messages: List[dict] records: List[StepRecord] = field(default_factory=list) def add_observation(self, text: str): self.messages.append({"role": "user", "content": text}) def snapshot(self) -> dict: return { "task": self.task, "messages": self.messages, "records": self.records, } class MinimalHarness: def __init__(self, llm_client, tools: List[Tool], max_steps=8): self.llm_client = llm_client self.tools = {t.name: t for t in tools} self.max_steps = max_steps def run(self, task, user_input): ctx = Context(task=task, messages=[{"role": "user", "content": user_input}]) for step in range(self.max_steps): resp = self.llm_client.chat(ctx.messages) intent = self.llm_client.parse_intent(resp) if intent.get("type") == "final": return intent["answer"] tool = self.tools.get(intent.get("tool")) if not tool: ctx.add_observation(f"Error: unknown tool {intent.get('tool')}") continue try: result = tool.handler(**intent.get("args", {})) except Exception as e: result = f"Error: {e}" ctx.add_observation(f"{tool.name} returned: {result}") ctx.records.append(StepRecord(step, intent, str(result))) raise RuntimeError("max steps exceeded")

这个骨架的核心价值在于接口清晰。想换后端模型，只换llm_client实现；想加新能力，往tools列表注册一个Tool对象；要做状态持久化，把Context的序列化和存储补上就行，循环逻辑基本不用动。

4.3 用一张选型清单找到你的落点

不确定自己该停在哪层？可以按顺序做几道判断题：

1. 任务能不能在一次模型推理里完成？如果能，停在单次LLM调用。
2. 是否需要实时数据、精确计算、访问内部系统？需要，则引入工具调用。
3. 用户会不会提出多步骤、带中间结果的任务？会，则加入Agent循环。
4. 任务是否可能被中断，需要在恢复后继续执行？需要，则必须引入状态持久化。
5. 是否要求每一步决策都留痕，支持审计和回放？要求，完整的Harness Runtime才真正值得。

这套清单还有一个隐藏好处：它能帮你跟业务方对齐预期。当你说“这一步不需要状态存储”时，对方能理解你在控制复杂度；当你说“这里必须上Runtime”时，你也已经想清楚要付出什么成本。我见过不少团队直接在第四步做全套，最后大量能力根本用不上，白增维护成本。反倒是那些从第一层开始、一层层加上去的项目，因为每步都验证过需求，整体结构干净得多。

5. Agent跑起来之后：常见故障与排查笔记

5.1 高频故障速查表

上线之后，Agent的各种问题会集中爆发。下面这张表是我实际调试中反复遇到的几类问题，整理成速查形式：

5.2 我的排查顺序与个人习惯

Agent排障如果没有章法，会很煎熬。我习惯固定一套顺序：先看轨迹日志，再看工具返回结果，最后才看模型输出。轨迹日志能告诉你Agent当时打算做什么，工具返回结果能告诉你现实情况是什么，两者对照之后再看模型文本，往往一眼就能定位问题。

还有几个小习惯值得分享。一是单测工具函数，不要只测Agent整体。工具函数本身逻辑复杂，整体跑失败时先怀疑工具，而不是先怀疑模型。二是遇到诡异行为先怀疑上下文被截断或污染，这类问题最隐蔽。三是把关键SOP写进System Prompt，放在不可裁剪的位置，不要放在容易被滑出窗口的历史消息里，这样能极大减少行为漂移。

我自己的体会是，Agent架构选型最忌讳一步到位。我第一次把一个简单任务直接塞进完整Runtime，结果花在状态同步和日志系统上的时间比Agent逻辑本身还多。后来换了一种方式，先把一次LLM调用的路径彻底打通，再逐步加工具、加循环、加状态，反而很快。大部分场景其实停在“工具调用+轻量循环”这一层就足够了，真正需要完整Harness Runtime的场景，通常都具备三个特征：任务步骤超过三步、中间结果需要跨会话保留、错误必须能回溯。用这三个特征去卡需求，架构选型自然会清晰起来。