企业官网建设流程全解析

最近团队完成了一次比较有代表性的迁移：把原本跑在一套自建框架上的对话式运维助手，整体搬到了 Claude Managed Agents 上。整个过程从评估、拆解到灰度切换，前后用了大约三周。这次迁移给我的感觉是，它的确把“代理能力”从开源拼装模式带到了“托管即用”的阶段，但在真实业务里，迁移的重头戏并不在“搬”，而在“重新理解任务边界”。

这篇文章不打算讲太多概念，主要围绕这次迁移的前因后果、动手过程中的关键取舍、踩过的坑和最终效果来写。如果读者朋友正准备从自建Agent框架换到托管形态，或者正在对比两种路线，这篇内容可以作为一份实操参考。

1. 为什么敢动这次迁移：从自建框架到托管代理

1.1 之前系统的真实现状

我们之前的运维助手是典型的三件套架构：大模型接口负责语义理解，外部的流程引擎负责调用各类运维工具，中间再用一层胶水代码把两者粘起来。从功能上看，它能做服务器状态查询、日志初步筛查、告警消息的上下文汇总，也能按预设流程执行一些变更操作。这个架构本身没什么大问题，但维护成本越来越集中在“胶水层”上。

每接入一个新的运维系统，就要写一套工具定义、一套参数映射、一套异常处理逻辑。三个月下来，工具数量翻了快一倍，代码里的分支逻辑也越来越复杂。最消耗精力的是“对话状态管理”：用户说一句“看看刚才那台机器现在怎么样了”，系统要先在内存里找到“刚才”指的是哪台机器、哪次操作，再拼接上下文去请求模型。这些状态的存储、过期和清理，全靠自己实现，稍不留神就会在并发场景下出脏数据。

所以这次迁移的核心动机，不是觉得原来的系统“不能用了”，而是想验证一个更省心的问题：把“循环执行”“状态记忆”“工具调用”这些能力交给托管平台之后，原来的业务逻辑能不能更简单。

1.2 Managed Agents 相比“裸平台”解决了什么

用 Claude 的 API 直接做开发，和用 Managed Agents 开发，体验上差别很大。如果只接 API，模型本身不会自己“跑起来”处理一件有多个步骤的事情，所有迭代逻辑都得写在代码里。你需要自己维护循环、自己判断什么时候该调工具、自己决定怎么把多轮结果拼接在一起。

Managed Agents 不一样，它把“执行代理”的通用机制内置了。你提供的是一个任务目标、一组可用工具、一些必要的外部约束，代理就会在这个框架内自行规划步骤、调用工具、查看结果，然后继续下一步。像“循环”“记录”“回退”这一类东西，平台层面已经处理好了。

这就像请了一个外聘专家，你不用手把手教他“先翻文档、再看数据、再给结论”，只需要告诉他任务是什么、手边有哪些工具、哪些事情不能做，他会自己安排工作节奏。对团队来说，省去的是大量与业务无关的调度代码，留下的是更纯粹的业务定义。

2. 迁移前的盘点：哪些能迁、哪些必须重写

2.1 能力边界与工具依赖梳理

迁移不是拍脑袋决定的，动手之前我们花了两天做了一次比较彻底的盘点。盘点对象有三个：原有的对话意图、依赖的工具、外部系统的访问方式。

原有对话意图大约二十来个，覆盖告警查询、日志检索、服务状态确认、配置项信息读取等几大类。逐个过了一遍之后发现，大约七成可以比较顺畅地迁移，因为它们的逻辑核心就是“问一个问题、调一个工具、整理答案”。剩下的三成处理起来会麻烦一些，因为它们依赖多轮状态，比如“对比昨天和今天的流量变化”，需要先明白“昨天”“今天”各自对应的时间窗口，再把两个时间段的数据放一起对比。

工具依赖方面遇到的问题比较典型。之前系统里接的运维工具，不少是直接通过底层命令完成的，比如执行一段脚本去拉取数据，或者直接连到数据库跑查询。托管代理环境并不能直接访问内网的这些通道，所以迁移的第一步，其实是想办法把“能跑的脚本”变成“能调的接口”。

这一步没法偷懒。我们把十多个后端操作统一封装成了标准的HTTP接口，每个接口负责一件很具体的事情，比如“按主机名查最近一小时CPU均值”“按错误码查过去二十四小时日志条数”。封装完之后，代理看到的是一组干净的“工具”，不关心背后是脚本、数据库还是外部平台。

2.2 指令体系与知识库的取舍

原有的提示词体系比较“重”，因为需要应对各种边界情况。当时写了几大段规则，包括意图判断、参数提取、拒答策略、安全话术，每一段都挺长。实际跑下来，提示词越长，模型的响应越保守，很多简单问题反而容易被“绕进去”。

迁移到 Managed Agents 之后，提示词体系的组织方式完全变了。原来的“一次性把规则全部塞给模型”不再是主流做法，更合理的拆法是：平台级指令负责整体纪律，工具各自的描述负责具体能力，每轮任务的目标写得越清楚，结果就越可控。

我们保留了一个固定前缀的全局指令，内容主要是角色定位、通用纪律和输出要求。其余大量细节被“下沉”到了工具描述里，比如某个接口的参数边界、某个数据的单位换算，都写在对应工具的描述中。

知识库这一块我们做了减法。原来为了应对“冷门术语解释”，硬塞了不少内部文档片段，效果并不理想，因为检索到的内容经常和当前问题不相关，反而干扰了模型判断。这次迁移时我们只保留了两种知识：一是高频缩写对照表，二是常见报错码的含义说明。其他内容一律从指令里删掉，需要的时候靠外部工具实时取数，而不是靠记忆硬答。

2.3 数据格式与外部约定

还有一个容易忽略的工作，是约定外部系统返回的数据格式。原来的胶水代码可以在调用工具后做各种后处理，比如把CSV转成JSON、把时间戳统一成东八区、把字段名做个映射。现在工具返回什么，代理基本就直接“看到”什么，所以必须在源头把格式处理好。

我们把所有工具的返回统一成了两层结构：外层带状态码和简要说明，内层才是真正的数据。数据字段一律使用小写下划线命名。时间字段一律使用ISO 8601格式并带时区偏移。

这套“外部约定”在迁移后显得格外重要。Managed Agents 的规划能力很强，但它的判断基础仍然是工具返回的内容，如果返回的格式混乱、字段含义不清，后续的规划质量就会直线下降。我们曾经遇到过代理因为工具返回了一个不明确的字段值，连续调了好几次同一接口，白白浪费了时间和额度，后来才发现是返回格式里“状态”字段没有说清楚枚举含义。

3. 迁移实操：四个阶段的完整过程

3.1 第一轮：把原有意图拆解成 Agent 能懂的任务

迁移的第一步，是把原来的二十多个对话意图重新“翻译”成代理视角下的任务定义。这个“翻译”不是简单换个说法，而是要做任务拆分。

举例来说，原来的对话里有一个意图叫“查询业务异常”，用户可能说“看看今天有没有异常”“这个报错是什么原因”“帮我查一下支付失败的情况”。在自建框架里，这个意图的背后是一堆正则加关键词匹配，再加上一个查询函数。到了 Managed Agents 环境里，我们需要把它定义成一个更灵活的任务：“根据用户的描述，识别他关心的对象和时间范围，调用日志检索工具，并结合错误码知识库给出解释。”

这么定义之后，代理不再需要“命中某个意图”才能工作，它只要持续理解用户的话，然后决定用哪个工具去满足当前需求。这是迁移过程中思维方式变化最大的一点：从“意图识别+固定流程”转向“目标理解+动态规划”。

我把所有原意图拆成了三个层级：第一层是直接可执行的单一任务，比如“查某台机器的负载情况”；第二层是需要调用多个工具但顺序固定的任务，比如“查日志→筛关键字→给时间分布”；第三层是需要判断和取舍的复杂任务，比如“帮我分析一下为什么最近告警变多”。前两类迁移起来最轻松，第三类需要仔细设计指令和工具描述。

这次拆分过程中我们坚持了一个原则：一个任务定义里，最多包含一个核心目标。不要把“查流量、查错误、给建议”塞进同一个任务里，否则代理容易顾此失彼。宁可拆成两三个任务连续执行，也不要贪多。

3.2 第二轮：工具定义与说明的重写

工具定义在 Managed Agents 里几乎是决定成败的关键环节。我在实际操作中体会到，模型对工具的理解，完全取决于你在工具描述里写了什么。写得太简单，代理就不知道怎么用；写得太冗长，代理又会抓不住重点。

我们的工具描述采用的是固定模板，每条包含五部分：功能概述、适用场景、参数说明（含类型、是否必填、取值范围、默认值）、返回值示例、注意事项。这个模板看起来没什么稀奇，但坚持每条工具都按模板写，效果提升很明显。

参数说明是最容易出问题的地方。原来有一台机器的“名称”字段，既可能是业务名，也可能是主机名，在旧系统里靠代码做映射，现在必须讲清楚。我们在参数说明里专门加了一句“如果用户只提供了业务名，先调用查询接口获取对应的主机名，再执行本操作”。这种“工具之间的衔接提示”，远比在全局指令里写“要注意关联查询”有效。

返回值示例也很重要。尤其对于代码类、脚本类的运维工具，返回内容往往比较粗糙。我们在返回值示例里写清楚了哪些字段值得关注，哪些字段可以忽略。这相当于帮代理画了“重点”，它可以快速从一堆原始输出里定位关键信息，而不是纠结于无关字段。

3.3 第三轮：在托管环境里调整运行参数

工具定义好之后，接下来就是参数调优阶段。Managed Agents 平台通常提供一组运行参数，控制着模型选择、温度、上下文窗口等。很多人在这一阶段容易犯一个错误：照搬之前 API 调用时的参数习惯。

我们以前在自建框架里用的是偏高的温度，希望让回答风格更灵活。但是在托管代理里，温度这个参数需要大幅降低。原因很简单：任务执行阶段需要的是稳定、可靠，而不是创意。如果温度过高，代理可能会在“该调工具”的时候“猜”一个答案，这代价很大。经过几轮测试，我们最终把温度停在了一个较低值附近，既保证了一定的表达多样性，又不会因为随机性导致任务路径偏离。

上下文窗口的设置也经历了一些调整。一开始我们希望把对话历史尽量保留长一些，结果发现几轮之后代理容易变得“犹豫”，因为旧信息和新信息混在一起，干扰了当前任务的判断。后来我们做了主动“收敛”：每个任务开启时，只保留最近两轮对话和当前任务的明确描述，更早的内容如果相关，通过工具去查询，而不是靠上下文硬记。这种做法显著减少了信息过载。

模型选择这一层倒没什么好纠结的，我们直接用平台当前主推的代理模型。如果后续有更合适的版本，再评估切换即可。这里想提醒的是：不要频繁切换模型版本，因为工具的“手感”是在某个版本上调出来的，换一个版本往往意味着工具描述又要微调。

3.4 第四轮：灰度切换与双跑验证

迁移的最后阶段是灰度上线。我们没有采取“一刀切”的方式，而是先挑了一个内部测试群，跑了大概一周。这一周里，新旧两套系统并行运行，内部群用户完全不知道背后已经换了引擎。

这一周的“双跑”价值非常大。我们准备了一个对比清单：相同的问题分别问旧系统和新系统，记录回答质量、任务完成率、响应耗时和异常次数。刚开始对比时，差距很明显。新系统在“多轮追问”场景下表现更好，但在“精确参数提取”方面反而不如旧系统稳，经常出现用户说“查一下最近一小时的数据”，代理却把时间窗口理解偏了。

针对这个问题，我们没有改全局指令，而是在日志检索工具的参数说明里增加了示例：“如果用户只说‘最近一小时’，则起始时间为当前时间减一小时，结束时间为当前时间”。这种“参数级修正”的成本很低，但效果立竿见影。灰度期间大约调整了七八处类似的细节，新系统的表现才逐渐稳定下来。

灰度一周后，我们开始逐步放量：先放一个外部用户群，踩完一轮问题后再放全量。全量切换后大约又观察了两天，确认没有明显回退，旧系统才正式下线。

4. 运行表现与指标：迁移前后的对比观察

4.1 关键指标的实测变化

迁完之后，我们对几项关键指标做了对比。这个对比不一定很“科学严谨”，但作为实际使用体验，具有一定的参考意义。

先看响应耗时。旧系统由于需要在胶水层里做状态拼接和意图判断，平均响应时间比较长。新系统在多数简单查询场景下响应更快，因为少了很多中间层跳转。但在一些复杂任务里，新系统的耗时反而更长，因为它会在内部做多步规划，每一步都有模型交互。整体看，体感响应速度基本持平，复杂任务略有变慢，但换来的是更高的任务完成率。

再看任务完成率。我们把“用户问题是否获得了满意解答”作为标准，灰度结束后统计了一下，大约提升了十来个点。提升最明显的是“模糊提问”场景，比如用户说“看看这几台机器有没有异常”，旧系统需要先识别“这几台”指哪几台，经常卡住；新系统会通过追问或查询动态确定范围，表现自然更好。

工具调用次数也值得关注。刚开始迁移时，新系统常常比旧系统多调用很多次工具，因为代理在“探索”。后来经过工具描述优化，调用次数逐渐回落，最终稳定在比旧系统略低的水平。这也从侧面说明，工具描述质量对执行效率的影响有多大。

4.2 “托管”省出来的开发和运维成本

成本这块，除了模型调用的直接费用，更要看人力成本。

原来维护自建框架，每次新增工具都要写胶水代码、写状态管理逻辑、跑测试，加班是常事。迁移后，新增一个工具只需要写好接口、定义好描述，代理即可直接使用。团队里一位以前主要写调用链路的同事，现在更多精力花在接口设计和文档撰写上，这种感觉其实是“从搬砖变成了设计”。

托管环境自带的状态管理和执行循环，也帮我们省掉了很多潜在的坑。以前我们要自己处理会话超时、回调重试、状态清理，现在这些由平台兜底。出了异常，至少不会再出现“旧会话状态把新用户的问题带偏”这种隐蔽问题。

还有一点是调试体验。我们在旧系统里排查问题，经常要翻日志去猜模型当时为什么那么理解。现在托管平台提供了执行轨迹和调用的可视化信息，能直观看到代理每一步做了什么判断、为什么调用某个工具。虽然不是所有细节都展示，但和以前相比，定位问题的时间明显缩短了。

5. 常见问题与排查技巧实录

5.1 高频故障与排查速查表

迁移和上线过程中，我们积累了一些常见问题的排查经验，整理成了一份速查表。这里列几个最有代表性的，供准备做类似迁移的朋友参考。

5.2 几个非常实用的排查思路

排查问题不能只靠“看报错”，更要理解代理的决策链路。

第一个思路是“逐段质问法”。每次发现结果不对，就沿着代理的执行轨迹一步步追问：它为什么调这个工具？这个工具返回了什么？它基于什么得出结论？很快就能找到问题主要出在“工具返回环节”还是“信息理解环节”。我们遇到的很多问题，追到源头都是工具返回内容不够清晰，而不是模型变笨了。

第二个思路是“最小复现法”。一次复杂任务出错时，不要直接在原始场景里反复试，那样成本高、变量多。把问题剥离成一个最小场景，只保留一个工具、一轮对话、一个目标。这样复现得很快，定位也准确。有一回我们排查“代理不调查询工具直接回答”的问题，做了一次最小复现后发现，是全局指令里有一段“你可以根据经验给出初步判断”的表述，给了代理偷懒的借口。

第三个思路跟记忆有关。Managed Agents 虽然在状态管理上比自建框架省心，但并不是完全无状态。遇到一些奇怪的行为时，可以考虑重置一段会话再测试。我们在灰度期间遇到过一次代理表现异常，排查了半天，最后发现是之前某次测试留下了一段异常的历史信息影响了判断。类似情况下，直接“重启会话”往往比在现有会话里反复修补更高效。

6. 迁移后的经验与心得

6.1 文档与 Prompt 同等重要

这次迁移给我最深的体会是，托管代理时代，“文档质量”直接决定了系统的智商。

以前写接口文档，主要给人看，写得不那么严谨也能靠同事之间沟通补漏。现在不行了，接口文档是给模型看的，描述是否清晰、示例是否充足，直接影响代理在真实使用时的表现。我们在迁移后期几乎把每个接口描述都迭代过至少一轮，每轮都有实实在在的效果提升。

我也建议大家不要偷懒，直接复用旧的接口文档。旧文档通常是给后端联调用的，充满术语和内部简称。模型对术语的消化能力有限，遇到它不熟悉的表达，宁可多绕弯也不会来问你。把描述调整成“自然语言优先，术语辅助解释”的写法，会顺畅很多。

6.2 我个人的几点体会

最后分享几个比较个人化的体会，也是踩过几次坑之后才慢慢明白的。

第一，迁移到 Managed Agents 不等于“把提示词改一改就完事”。它更接近一次系统重构，需要重新审视任务边界、工具定义和数据格式。如果抱着“搬代码”的心态做迁移，大概率会绕远路。

第二，“少即是多”在指令设计上非常适用。我们最初的全局指令写得很全，结果代理经常被无关规则干扰。后来把指令精简到只保留核心纪律，把细节下放到工具描述，整体表现反而更好了。这里的规律是：越靠近具体操作的信息，越应该放在操作对应的描述里，而不是堆在全局层面。

第三，不要让代理“背”知识。凡是能通过工具实时获取的信息，都不要试图通过指令或记忆来固化。我在实际操作中遇到过好几次这类问题，比如要求代理记住某个配置项的默认值，结果模型记错了，给出的判断就跟着错了。正确做法是定义一个查询工具，每次需要时实时取用。

第四，灰度验证阶段别图快。我们用了大约两周的时间去观察和打磨，才敢把全量流量切过去。如果为了省时间缩短灰度周期，到线上再暴露问题，处理的成本反而更高。

这次迁移完成后的这段时间，我们陆续在上面扩展了新的自动化场景，而且新增速度明显比以前快。和那些仍在自建框架里“打补丁”的老路相比，把代理的执行机制交给托管平台，然后专注做好业务定义和工具梳理，确实是一条更省心、也更容易扩展的路线。