企业官网建设流程全解析

1. 从一次裸调用说起：为什么单次 LLM 调用撑不起一个 Agent

很多人第一次接触 Agent 开发，都是从一段几十行的脚本开始的：拼一个 prompt，调一次大模型接口，拿到返回文本，解析一下，结束。这个模式在"问答"场景下确实够用，但只要任务稍微复杂一点——比如需要查资料、需要多步推理、需要调用外部工具、需要根据中间结果调整策略——这套写法立刻就会崩掉。

我见过太多项目卡在这个阶段：demo 跑得挺漂亮，一上真实任务就各种翻车。翻车的表现通常有这么几类：模型在第二轮对话里"忘记"了第一轮的工具返回结果；同一个工具被反复调用五六次，每次都返回一样的东西；模型输出了格式不对的 JSON，解析器直接抛异常，整个流程中断；任务跑到一半 token 超了上下文窗口，前面的关键信息被截断。这些问题看起来零散，本质上都指向同一件事：你缺的不是一个更好的 prompt，而是一层运行时（Runtime）。

所谓 Harness Runtime，你可以把它理解成 Agent 的"操作系统"。裸调用相当于你直接拿汇编去操作硬件，而 Runtime 是那层帮你管理内存、调度任务、处理中断的系统软件。它要解决的核心问题包括：状态怎么存、工具怎么注册和调用、循环怎么控制、错误怎么恢复、上下文怎么压缩、多轮之间怎么保持一致性。这篇文章就围绕这条演进路径展开——从最朴素的单次调用，一步步推导出一个可用的 Harness Runtime 应该长什么样，每一层为什么这么设计，以及实际落地时会踩哪些坑。

需要先说明的是，本文讨论的是通用 Agent 架构的设计思路，不绑定任何特定厂商的模型或框架。你用的是哪家的大模型接口、哪个编程语言，都不影响这些架构层面的判断。文中涉及的具体参数和代码示例，都是基于常见工程实践给出的参考值，实际项目中需要根据你的任务特点做调整。

2. 裸调用阶段的能力边界与典型失效模式

2.1 单次调用的本质：一个无状态的纯函数

先把最基础的事情说清楚。一次 LLM 调用，从工程视角看就是一个纯函数：输入是一段文本（prompt），输出是另一段文本（completion）。它没有记忆，没有状态，不会主动做任何事。你给它什么，它基于训练时学到的模式给你生成什么。这个认知非常重要，因为后面所有的架构设计，本质上都是在给这个"无状态纯函数"套上各种外挂，让它看起来像是有状态、能行动的智能体。

很多人对 Agent 的误解就来自这里：以为模型"记得"之前的对话。实际上不是模型记得，是你每次调用时把历史对话重新塞进了 prompt 里。所谓"记忆"，是工程层面拼出来的假象。理解这一点，你就能明白为什么上下文管理是 Agent 架构里最核心的难题之一——因为模型的"记忆"完全依赖于你每次喂给它的文本，喂多了超窗口，喂少了丢信息。

2.2 三种典型失效：格式崩溃、循环失控、上下文溢出

在真实项目里，裸调用最先暴露的问题通常是输出格式不稳定。你要求模型返回 JSON，它大部分时候返回得挺好，但偶尔会加一句"好的，以下是结果："，或者把 JSON 包在 markdown 代码块里，或者某个字段该是数字却返回了字符串。解析器一崩，整个流程就断了。这个问题在单轮场景下还能靠重试糊弄过去，但在多步任务里，一次解析失败可能意味着前面几步的工作全部白费。

第二个问题是循环失控。当你想让模型自己决定"下一步做什么"时，它很容易陷入死循环：调用搜索工具，没找到想要的，再调一次，还是没找到，再调一次……直到把 token 烧光。裸调用没有任何机制阻止这种行为，因为模型本身没有"我已经试过了"这个概念，它每次看到的都是你拼给它的上下文，如果上下文里没有明确记录"这个工具已经调用过 N 次且失败了"，它就会一直试。

第三个问题是上下文溢出。多步任务跑下来，工具返回的结果、模型的思考、历史对话越堆越多，很快就撞上模型的上下文窗口上限。这时候你有两个选择：要么截断（丢掉早期信息，模型可能因此"失忆"），要么报错（任务中断）。裸调用阶段通常只能粗暴截断，效果自然好不到哪去。

2.3 一个具体的失败场景复盘

举个我实际遇到过的例子。任务是让 Agent 分析一份销售数据并生成报告。流程设计是：先调用数据读取工具拿到原始数据，再调用统计工具算几个指标，最后让模型基于统计结果写报告。裸调用版本跑起来是这样的：第一轮模型决定调用数据读取工具，返回了一大坨 CSV 文本；第二轮模型看到 CSV，决定调用统计工具，但它把 CSV 里的列名记错了，传了个不存在的字段名；统计工具报错返回；第三轮模型看到报错，又调了一次统计工具，还是同样的错误字段名；如此循环了七八次，token 耗尽，任务失败。

这个案例里，三个失效模式全占了：工具参数格式不对（格式问题）、重复调用同一个失败的工具（循环失控）、CSV 数据把上下文撑爆导致后面的报错信息被截断（上下文溢出）。要修好它，光改 prompt 是没用的，必须引入运行时层面的机制。这就引出了下一层的设计。

3. 第一层运行时：工具调用循环与状态机的引入

3.1 把"模型决定"变成"状态机驱动"

裸调用的核心问题是把控制权完全交给了模型。模型说下一步干啥就干啥，工程侧没有任何约束。第一层运行时的思路是：把控制流从模型手里拿回来一部分，用状态机来约束。具体做法是定义一个明确的状态集合，比如"待规划""执行工具""观察结果""生成回复""结束"，然后规定状态之间的合法转移。模型在每个状态下只负责它该负责的那部分决策，而不是全权决定整个流程。

这样做的好处是显而易见的。首先，循环失控被天然限制了——你可以在状态机里规定"同一个工具连续失败超过 3 次就强制进入错误处理状态"，这个规则由代码强制执行，模型说了不算。其次，格式问题可以在状态边界上做校验——工具调用的参数在进入执行状态前先过一遍 schema 校验，不合法就直接打回，不让它污染后续流程。最后，整个流程变得可观测、可调试，你能清楚地知道当前卡在哪个状态，而不是面对一坨黑盒输出干瞪眼。

3.2 工具注册表：让模型知道"有什么能用"

状态机解决了控制流，接下来要解决的是工具管理。裸调用阶段，工具信息通常是硬编码在 prompt 里的，加一个工具就要改一次 prompt，维护起来很痛苦。第一层运行时应该引入一个工具注册表：每个工具用结构化的方式描述——名字、功能说明、参数 schema、返回值格式。模型在需要时，运行时把注册表里相关工具的描述动态拼进 prompt。

这里有个实操细节值得展开。工具描述写得好不好，直接决定模型会不会正确使用它。我见过太多工具描述写得像 API 文档，什么"参数 a 为字符串，参数 b 为整数"，模型看了根本不知道什么时候该用。好的工具描述应该回答三个问题：这个工具解决什么问题、什么情况下该用它、调用时要注意什么。比如一个搜索工具，与其写"执行网络搜索"，不如写"当需要获取实时信息或你不确定的事实性内容时使用；输入应该是具体的关键词而非完整句子；返回结果是摘要列表，可能需要进一步筛选"。后者能让模型的调用准确率提升一大截。

3.3 观察结果的回填与截断策略

工具执行完，结果要回填给模型。这一步看似简单，实则暗藏玄机。工具返回的内容可能非常长（比如读了一个大文件），直接塞进上下文会迅速撑爆窗口。所以第一层运行时必须有一个结果截断与摘要策略。常见的做法是：设定一个单次工具返回的字符上限，超过就截断，并在截断处明确标注"内容已截断，完整结果共 X 字符"。更聪明的做法是让模型自己决定要不要看完整内容——先给它一个摘要或前 N 行，如果它判断需要更多，再让它显式请求。

注意：截断策略一定要在上下文里留下明确标记，否则模型会以为它看到的就是全部，基于不完整信息做决策。我踩过这个坑，模型因为没看到被截断的部分，反复调用同一个工具想"拿到完整数据"，结果每次都拿到同样的截断结果，白白烧了一堆 token。

3.4 这一层的局限：状态机是死的，任务是活的

第一层运行时能解决不少问题，但它有个根本局限：状态机是预先定义好的，而真实任务的流程往往是动态的。你很难在写代码时就穷举出所有可能的状态转移。比如一个研究型任务，模型可能需要先搜索、再阅读、再搜索、再对比、再总结，中间还可能因为发现新线索而回头重新搜索。这种灵活的流程，用固定状态机去套会非常别扭，要么状态爆炸，要么约束太死导致模型没法发挥。

这就引出了下一层：当任务流程本身需要动态生成时，我们需要一个更灵活的运行时，它不再依赖预定义状态机，而是让模型在每一轮自主决定下一步，但运行时提供足够的护栏防止它跑偏。

4. 第二层运行时：ReAct 循环与动态规划的实现细节

4.1 ReAct 模式的本质：思考与行动的交替

ReAct（Reasoning + Acting）是当前 Agent 架构里最主流的范式，核心思想是让模型在每一轮里先"想"再"做"：输出一段思考（我现在的目标是什么、我掌握了什么信息、下一步该干什么），然后输出一个行动（调用某个工具，或者给出最终答案）。运行时执行这个行动，把结果作为观察回填，进入下一轮。如此循环，直到模型输出最终答案或触发终止条件。

这个模式比状态机灵活得多，因为"下一步干什么"完全由模型根据当前上下文动态决定，不需要预先枚举。但它也带来了新的工程挑战：既然控制权又交回给模型了，怎么防止它跑偏？答案是运行时提供护栏，而不是替模型做决定。护栏包括：最大轮数限制、单轮 token 限制、工具调用频率限制、重复调用检测、格式校验等。模型在护栏内自由发挥，一旦触碰护栏，运行时介入。

4.2 思考链的显式化：为什么要把"想"写出来

ReAct 要求模型显式输出思考过程，这不是为了好看，而是有实际工程价值的。首先，显式思考让模型的决策更可解释，出问题时你能看到它"当时是怎么想的"，便于调试。其次，显式思考本身能提升模型的表现——这在大模型研究里已经被反复验证，让模型把推理步骤写出来，比直接给答案的准确率更高。最后，思考内容可以作为上下文的一部分，帮助模型在后续轮次里保持目标一致性。

实操中，思考部分的格式需要约束。我通常要求模型用固定的标记包裹思考内容，比如用特定的分隔符，这样运行时可以方便地把思考和行动拆开。如果不做约束，模型有时候会把思考和行动混在一起，解析起来很麻烦。

4.3 行动解析：从自由文本到结构化调用

模型输出的行动部分，需要被解析成结构化的工具调用。这里最容易出问题的就是格式。我的经验是：不要指望模型每次都输出完美格式，运行时要做好容错。具体做法包括：用正则或解析器提取工具名和参数，如果解析失败，不要直接崩溃，而是把解析错误作为观察回填给模型，让它重新输出。通常模型看到"你的输出格式不对，请按 X 格式重新输出"之后，第二次就能对了。

另一个技巧是给模型提供 few-shot 示例。在系统提示里放一两个正确的工具调用示例，模型的格式准确率会明显提升。示例要覆盖常见的边界情况，比如参数为空、参数是复杂嵌套结构等。

4.4 终止条件的判定：什么时候该停

ReAct 循环必须有明确的终止条件，否则就是无限循环。终止条件通常有三类：模型主动输出最终答案、达到最大轮数、触发错误阈值。第一类是最理想的，但需要模型能正确判断"任务完成了"。实践中模型有时候会过早认为任务完成（其实还没做完），有时候又会没完没了地做下去（其实已经可以给答案了）。所以运行时要能识别这两种情况并干预。

我的做法是在系统提示里明确告诉模型终止规则：什么情况下应该输出最终答案，什么情况下应该继续。同时运行时设置一个软上限（比如 15 轮）和一个硬上限（比如 25 轮），软上限到了就提醒模型"你还有 N 轮机会，请考虑是否该给出答案"，硬上限到了就强制终止并返回当前最好的结果。

4.5 上下文膨胀的应对：滑动窗口与摘要压缩

ReAct 循环跑起来，上下文会快速膨胀。每一轮的思考、行动、观察都要进上下文，十几轮下来轻松几万 token。应对策略主要有两种：滑动窗口和摘要压缩。滑动窗口是只保留最近 N 轮的完整内容，更早的轮次只保留摘要或直接丢弃。摘要压缩是定期让模型把之前的对话总结成一段简短摘要，用摘要替换原始内容。

两种策略各有取舍。滑动窗口实现简单，但可能丢掉早期的重要信息；摘要压缩保留信息更全，但摘要本身要消耗一次模型调用，而且摘要可能失真。实践中我通常组合使用：最近几轮保留完整，更早的轮次做摘要，同时把关键的工具返回结果单独存起来，需要时再取。

5. 第三层运行时：记忆、规划与多 Agent 协作

5.1 短期记忆与长期记忆的分层设计

到了这一层，Agent 要处理的任务周期变长了，单靠上下文窗口已经不够。需要引入分层记忆：短期记忆就是当前上下文窗口里的内容，长期记忆则是存在外部存储里的、可以按需检索的信息。长期记忆通常用向量数据库实现，把历史对话、工具结果、任务中间产物都向量化存起来，需要时用相似度检索召回。

这里有个容易忽略的点：什么该进长期记忆，什么不该。如果什么都往里存，检索时噪音会很大，召回的内容质量差。我的经验是只存三类东西：任务的关键结论、可复用的工具调用结果、用户明确表达的偏好或约束。过程性的思考、失败的尝试、临时的中间数据，都不值得长期保存。

5.2 任务分解：把大目标拆成可执行的子任务

复杂任务需要规划。规划的实现方式有两种：一种是让模型在开始时就生成一个完整的任务列表，然后逐个执行；另一种是让模型边做边规划，每完成一步再决定下一步。前者适合流程相对确定的任务，后者适合探索性强的任务。实践中我倾向于混合：先让模型生成一个粗粒度的计划（3 到 5 个大步骤），执行过程中再对每个大步骤做细粒度的动态规划。

计划不是一成不变的。执行过程中发现新信息，计划应该能调整。所以运行时需要支持"重新规划"：当某个子任务失败或发现计划不合理时，把当前状态和问题反馈给模型，让它修订计划。这个机制很重要，否则 Agent 会死板地执行一个已经过时的计划。

5.3 多 Agent 协作：什么时候需要，什么时候是过度设计

多 Agent 是这两年的热门话题，但我要泼盆冷水：大多数任务不需要多 Agent。多 Agent 带来的复杂度是实打实的——通信开销、状态同步、冲突解决、调试困难，每一样都能让项目周期翻倍。只有当任务确实可以清晰拆分成多个独立子领域，且每个子领域需要不同的工具集或不同的提示策略时，多 Agent 才划算。

如果确实要用，常见的协作模式有几种：主管-工人模式（一个协调 Agent 分配任务给多个执行 Agent）、流水线模式（多个 Agent 按顺序处理，前一个的输出是后一个的输入）、辩论模式（多个 Agent 对同一问题给出方案，互相批判后收敛）。选哪种取决于任务结构，没有万能方案。

5.4 状态持久化：让 Agent 能"断点续跑"

长任务可能跑几个小时甚至几天，中间可能因为各种原因中断。如果每次中断都要从头再来，成本太高。所以运行时需要支持状态持久化：把 Agent 的当前状态（已完成哪些步骤、当前上下文、记忆内容）定期存到外部存储，中断后能从最近的检查点恢复。这个机制在工程上不难，但很容易被忽略，等到真出问题时才后悔没做。

6. 落地 Harness Runtime 时的工程取舍与踩坑记录

6.1 同步还是异步：调用模型的阻塞问题

模型调用是网络请求，天然是阻塞的。如果 Agent 要串行执行多个步骤，每个步骤都等模型返回，整体延迟会很高。解决方案是异步化：把模型调用、工具执行都做成异步任务，能并行的并行。但异步会带来状态管理的复杂度，多个异步任务同时修改 Agent 状态时需要考虑并发安全。我的建议是：先做同步版本跑通，确认逻辑正确后再逐步异步化，不要一上来就追求高性能，那样调试成本太高。

6.2 错误处理的分级：哪些错误该重试，哪些该放弃

Agent 运行中会遇到各种错误：网络超时、模型返回格式错误、工具执行失败、上下文超限。这些错误不能一视同仁。网络超时通常重试就能解决；格式错误重试一两次也可能好；但工具执行失败如果是参数问题，重试多少次都一样，应该把错误反馈给模型让它改参数；上下文超限则必须触发压缩或截断。分级处理错误，是运行时成熟度的标志。

6.3 成本控制：token 是要花钱的

Agent 跑起来 token 消耗很快，尤其是 ReAct 循环，每一轮都要把完整上下文发给模型。控制成本的手段包括：精简系统提示、及时压缩上下文、缓存重复的模型调用结果、对简单任务用小模型、对复杂任务才用大模型。我见过一个项目，因为没做任何成本控制，一个任务跑下来烧掉的钱比人工做还贵，这就本末倒置了。

6.4 可观测性：没有日志的 Agent 就是黑盒

Agent 出问题时，如果没有详细的日志，你根本不知道它卡在哪、为什么做了某个决策。所以从第一天起就要把可观测性做进去：每一轮的输入输出、工具调用参数和结果、状态转移、耗时、token 消耗，全部记录下来。这些日志不仅能用于调试，还能用于后续的优化——分析哪些工具调用最频繁、哪些步骤最耗时、哪些错误最常出现。

6.5 一个渐进式的落地路线建议

最后给一个务实的落地路线。不要一上来就追求完整的 Harness Runtime，那样很容易陷入过度设计。我的建议是分阶段：第一阶段，把单次调用封装成一个带格式校验和重试的函数，解决最基本的稳定性问题；第二阶段，引入工具注册表和简单的 ReAct 循环，加上轮数限制和重复调用检测；第三阶段，加入记忆管理和状态持久化，支持长任务；第四阶段，根据实际需要引入规划和多 Agent。每个阶段都跑通了、验证了价值，再进入下一阶段。这样既能快速看到效果，又不会在早期就背上沉重的架构包袱。

我在实际项目里最大的体会是：Agent 架构的复杂度应该由任务的实际需求驱动，而不是由技术的新鲜感驱动。很多看起来"高级"的机制，如果你的任务根本用不上，加进去只会增加维护负担。反过来，如果任务确实复杂，那些看似繁琐的护栏、记忆、持久化机制，一个都不能少。判断标准很简单：跑一个真实任务，看它在哪一步崩，然后针对性地补那一层的机制。这比照着任何架构图照搬都管用。