做了两年多的平台化建设，我越来越觉得，AI 应用开发真正难的不是把一个大模型接口调通，而是怎么把"会调模型"变成"能稳妥交付业务"。XXL-AI 这套平台，本质上就是在回答一个问题：当业务方同时需要 Agent 编排、多家模型供应商、外部工具接入和企业级工程约束时，该怎么设计一个底座。这篇文章会把我在这个项目里的核心设计思路、技术选型和踩坑记录整理出来，偏实战向，适合正在做 AI 平台、Agent 框架，或者打算从零搭一套内部 AI 基础设施的团队参考。
1. 先说说我为什么非要自研这个编排平台
1.1 业务侧的三个真实痛点
项目启动前，我们花了几周时间盘内部已有的 AI 功能，发现三个反复出现的痛点。
第一是重复造轮子。每个业务线都在自己调模型 API、自己写 prompt 管理、自己拼上下文。有的团队用 LangChain，有的自己封装 OpenAI SDK，有的干脆让后端直接抓着 chat completion 接口裸调。表面看功能都能跑，实际上每家都维护了一套互不兼容的"模型调用胶水层"，换一个模型供应商就要改一遍代码。
第二是工具散落。Agent 要落地，离不开外部工具——查订单、查库存、发通知、操作内部系统。但我们当时没有统一的工具接入层，每个 Agent 各自定义自己的 function calling schema，字段命名、鉴权方式、超时策略全都不一样。业务方想复用另一个团队的 Agent 能力，几乎要重新开发一遍。
第三是效果与成本不可控。没有统一的可观测性，模型调一次多少钱、工具调用失败率多少、Agent 在哪一步开始胡说八道，全得靠业务方自己猜。更麻烦的是没有降级和限流机制，上游模型供应商一抖动，下游业务跟着雪崩。
这三个痛点对应的不是"再写一个封装库"，而是需要一个平台层面的抽象：统一的编排能力、统一的工具接入标准、统一的模型供应商适配层、统一的运维观测面。
1.2 为什么没用现成框架直接搭
可能有人会问，LangChain、LlamaIndex、Dify 这些不都能干吗？为什么非要自研？我的判断是这样的：我们需要的不是某个框架的 API，而是平台级的工程约束。
LangChain 这类框架的优势是快速原型开发，但它本质是"代码库"而不是"平台"。团队用它做 PoC 很快，可一旦进入生产，你会立刻撞上几个现实问题：框架升级带来的 breaking change、编排逻辑散落在业务代码里难以治理、链路追踪需要额外接一堆组件、权限和审计能力完全要靠自己补。说白了，框架给了你灵活性，但平台要的确定性、可观测性、可治理性它给不了。
Dify 这类商用平台编排体验好，但我们的场景是平台需要被内部多个业务系统的研发团队二次开发，Agent 的编排策略要能写代码自定义，工具接入要能走企业内网协议，数据要保留在自己的基础设施上。低代码平台适合业务人员搭简单助手，不适合做深度定制的工程底座。
所以结论很干脆：编排引擎自己写，模型协议自己做抽象，工具接入和扩展机制做成开放协议，工程底座（追踪、限流、审计、灰度）完全自建。这样平台的能力边界完全可控，不会被上游框架绑架。当然，这不代表我们要从零实现一个基础模型网关——供应商适配层我们只做轻量封装，把核心精力放在编排和工具生态上。
1.3 平台的目标定位：不是低代码，是工程化底座
XXL-AI 最终定位是"AI 应用的工程化底座"。它不是一个面向业务人员的拖拽平台，而是一个面向研发人员的框架级平台。业务研发可以在上面用代码或者声明式配置来定义 Agent、接入工具、注册技能，同时获得平台提供的模型路由、可观测性、权限能力。
我在设计之初就把这几件事写进了需求优先级：
- 支持多 Agent 的编排，不只是一问一答的聊天机器人
- 支持多家模型供应商，且可以在一个应用内自由切换或降级
- 提供 MCP、SKILL、RAG 三类扩展方式，覆盖"工具能力、做事方法、知识数据"三个维度
- 所有运行过程可观测、可审计、可回滚
这三类扩展方式正好对应了 Agent 应用的三类资产。工具是 Agent 的"手"，技能是 Agent 的"方法论"，知识库是 Agent 的"记忆"。平台要做的，就是把这三类资产都变成可注册、可复用、可治理的对象。
2. 核心架构拆解：编排引擎与多供应商抽象层
2.1 编排引擎的抽象模型
Agent 编排是平台最核心的部分。我在设计编排引擎时没有一上来就上复杂的多代理协商框架，而是先定义了一个足够基础、又足够表达复杂场景的抽象模型。
抽象模型分四层：
- Step：最小执行单元，一个 Step 可以是 LLM 调用、工具调用、代码执行、条件判断、子流程触发
- Node：包含若干 Step 的图节点，每个 Node 有自己的输入输出规范
- Graph：由多个 Node 组成的 DAG，定义了 Agent 的执行流程，支持并行、分支、循环
- Agent：Graph 的运行时实例，包含模型配置、工具列表、技能绑定、上下文管理策略
为什么用 DAG 而不是让模型自由决定下一步？我的经验是：生产环境里，流程确定性比自由度更值钱。让大模型从头到尾自由规划每一个 action，Demo 阶段效果很惊艳，但到了生产就变成"失控代名词"。我们平台上默认的 Agent 执行模式是人机协同：由编排引擎定义主干流程（比如"先查权限 → 再调工具 → 再让模型总结"），模型只在预设的分支点做决策，比如选择调用哪个工具、判断任务是否完成。这样既保留了大模型的智能性，又给业务留下了审计和干预的抓手。
编排引擎的另一个关键设计是状态管理。Agent 执行过程中会产生大量中间状态：上下文窗口内容、工具返回结果、分支选择记录、Token 消耗。我们把这些状态统一持久化到平台的运行日志中，每一个 Step 都可以单独重放。这为后面做追踪和复盘打下了基础，也方便业务方排查 Agent 的"错误决策"到底发生在哪一步。
2.2 多供应商抽象：差异永远比想象的多
多供应商支持听起来很简单，无非是大家都实现 OpenAI 兼容接口。但你真正接的时候就知道了，"兼容"两个字的水分很大。
供应商之间的差异至少分布在五个层面：
- 接口路径与认证方式不同
- 函数调用（tools/function calling）的请求和响应格式有细微差异，有的要 strict schema，有的只要 description
- 流式输出的事件格式不同
- 上下文窗口长度和计费单位不同，直接决定了你给 Agent 设多少 max_tokens
- 限额与限流策略不同，有的按 RPM，有的按 TPM，有的按并发数，触发了之后返回的错误码和重试建议也不一样
所以我在 XXL-AI 里设计了一个ModelProvider 抽象接口，核心就三件事：统一请求参数、统一响应格式、统一错误与重试。平台内部所有编排逻辑只面向这个抽象层开发，不直接依赖任何一家供应商的 SDK。
统一响应的价值，在你做模型降级的时候体会最深。我们在平台上配置了每个"模型身份"的 fallback 列表，比如主用 DeepSeek，超过 10 秒没响应或者返回限流错误，就自动切换到一个备用模型。这套逻辑如果供应商之间响应格式不统一，根本没法写。
还有一个容易被忽视的问题：供应商能力标签。不是所有模型都擅长 function calling，不是所有模型都支持 JSON mode，不同模型对 System Prompt 的遵循度差异也很大。平台在模型注册信息里加了一组能力标签，编排引擎在选模型时会校验"当前 Agent 的配置是否匹配模型的可用能力"，避免上线之后才发现某个模型不支持工具调用这种尴尬。
2.3 供应商切换与降级的实战策略
降级听起来美好，做起来也挺考验细节。我给你一个比较典型的降级策略配置：
- 主供应商错误分成两类：可重试（限流、超时、5xx）和不可重试（鉴权失败、参数错误）
- 可重试错误先按退避策略重试 1 次，仍然失败就切换备用供应商
- 不可重试错误直接抛给编排层，由 Agent 决定是否向用户说明
- 切换动作必须记录审计日志，包括原因、耗时、备用供应商名称
这里有一个我的经验教训：降级不能只换模型，还要考虑工具调用的兼容性。切换供应商后，如果备用模型的 function calling 能力不如主模型，之前设定好的工具调用策略可能需要动态调整（比如减少同时提供给模型的工具数量）。我们后来在供应商配置里加了"工具数量上限"这个属性，就是为了让降级后的 Agent 还能保持基本可用。
另外，多供应商还有一个收益很多人没注意到：它让 Agent 的"模型选型"变成了运行时策略。同一个 Agent，在处理简单问题时路由到小模型，成本低、速度快；遇到复杂推理任务再切换到大模型。平台上线后这套动态路由帮我们省了不少推理成本。把模型当资源池管理，而不是把某个模型写死在代码里，这一点我认为是 AI 平台和普通封装最大的区别之一。
3. MCP 接入实战：从协议理解到工具层落地
3.1 MCP 到底是什么，以及为什么平台会重视它
MCP（Model Context Protocol）简单说，就是给 AI 应用定义的一套"工具外设"标准协议。很多人纠结它到底是软件协议还是硬件协议的概念，其实一个类比就清楚了：如果说 GPT 是主机，那 MCP 工具就像是 USB 设备——协议负责让不同厂商的设备插上就能用。外部工具实现 MCP Server，Agent 平台实现 MCP Client，双方按协议报文沟通，免去每个工具都要定制对接的麻烦。
XXL-AI 把 MCP 作为工具接入的一等公民，原因很简单：MCP 生态正在变成 Agent 世界的"标准外设接口"。今天接一个查询天气的服务，明天接一个操作浏览器的服务，如果每接一个都要写一套 function calling schema 再转换，平台的工具接入成本会线性膨胀。而走 MCP，工具的发现、调用、鉴权都可以标准化。
当然也有不少人质疑 MCP 太"重"，说直接用 OpenAI function calling 就够了。我的看法是：如果你只接两三个工具，确实没必要上 MCP；但平台面对的可能是几十个业务系统、上百个工具，标准化带来的收益远大于协议解析的损耗。这个取舍要看场景。
3.2 平台上 MCP 接入的三种方式
XXL-AI 的 MCP Client 组件支持三种 transport：
- stdio：本地进程间通信，适合在 Agent 运行环境同机部署的能力，启动快但不可远程
- SSE（Server-Sent Events）：适合传统服务端推送场景，兼容性较好，但部分版本存在连接管理问题
- Streamable HTTP：目前比较推荐的方式，更贴近现代 HTTP 语义，鉴权灵活，适合接远程 MCP Server
实践中，我们把工具能力分成了两类：平台内置工具（直接以代码实现，不走 MCP，比如时间查询、ID 生成、基础计算），以及外部业务工具（统一接 MCP）。这样避免"杀鸡用牛刀"，也让平台自身代码保持简洁。
接入 MCP Server 之后，平台会自动完成工具发现：读取 MCP Server 暴露的 tool 列表，把每个 tool 的 JSON Schema 转换成 Agent 可用的 function calling 声明。这里有个容易踩的坑：MCP 的 tool schema 和模型 function calling 的 schema 不是一回事。比如 MCP 允许更复杂的嵌套类型，但很多模型对复杂 JSON Schema 的支持并不好。我们在转换层做了"Schema 扁平化"处理：把不兼容的复杂结构拆分为多个简单参数，实用效果显著提升。
3.3 MCP 工具注册与权限管理
工具接入只是第一步，工具治理才是平台层面的难题。我在 XXL-AI 里做了一个类似"命名空间"的工具管理模型：
- 每个 MCP Server 注册到一个 namespace 下，namespace 对应业务域或工具类型
- 工具全名由 namespace.tool_name 构成，防止多个 MCP Server 暴露同名工具的冲突
- Agent 绑定工具时按 namespace 粒度授权，而不是把全部工具都暴露给模型
为什么这么做？因为工具给模型的选择越多，模型越容易选错。你见过把一个订单查询工具和一个天气工具同时丢给 Agent，结果用户问"今天天气如何"时它去查了订单表的场景吗？我见过。限制工具数量、按域授权，比单纯依赖模型自觉靠谱得多。
权限方面，MCP Server 的鉴权凭证（Token、密钥）统一存在平台密钥管理组件中，运行时不透传给前端。每个 MCP 调用都会记录调用者应用、Agent、用户、工具名、耗时、成功与否。这也是审计追溯的基础。
3.4 Browser Use MCP 和 Playwright MCP 怎么选
在真实的工具落地中，浏览器自动化这类工具特别热门，也特别容易选错。团队里最常问我的就是"浏览器操作的 MCP 应该用 Browser Use 还是 Playwright"。
我提供一个非常务实的判断维度：
- Browser Use MCP：本质是为 AI Agent 设计的浏览器操作系统，更强调"让模型理解网页、规划操作"，它把网页内容提取成适合模型理解的紧凑形式，适合任务型 Agent，比如"打开后台把昨日订单导出"。它不太强求每一步操作可调试。
- Playwright MCP：本质是给浏览器自动化提供的标准操作接口，操作更贴近传统自动化测试的粒度，每一步点击、输入、读取都有明确的工具定义，适合需要确定性、可回归、可写断言的场景。缺点是给模型的信息粒度比较细，长任务需要很多步调用，Token 消耗较大。
如果让我给建议：做通用 Web 自动化 Agent，选 Browser Use；做严格流程控制的网页操作，选基于工具化思路的 Playwright MCP 或者自己封装浏览器控制服务。顺便说一句，MCP Server 不一定只能直接连到别人的服务，也可以把内部原本就写好的自动化能力（比如已有的 Playwright 脚本）包一层 MCP 协议暴露出来，这往往比重新开发的成本低得多。
4. SKILL 技能体系：让 Agent"会做事的方法"成为可复用资产
4.1 SKILL 与 MCP 的本质区别
很多人一开始搞不清 SKILL 和 MCP 的区别，包括最初的我。后来我想明白了一句话：MCP 提供的是"能做什么"（能力/工具），SKILL 提供的是"该怎么做（才做得好）"（方法论/流程）。
举个例子。MCP 可能给你一个search_orders工具，它知道如何查询订单数据；但 SKILL 会告诉你，当用户问"我的订单为什么还没发货"的时候，一个优秀的客服 Agent 应该先查什么、遇到异常状态怎么安抚用户、什么情况下需要转人工。这是业务知识和执行策略，不是简单的工具调用。
把 SKILL 单独提出来做一套体系，是因为我们碰到过几个实际痛点：
- prompt 散落在各个 Agent 的代码里，同样的"客服应答策略"被复制了十几份，改一处漏一处
- Agent 的能力边界不清晰，用户问"你会做什么"，模型回答随心情
- 新人维护 Agent 时不知道系统预设了什么行为约束，导致上线后行为不可控
4.2 SKILL 的分层结构与执行机制
我在 XXL-AI 里把 SKILL 既设计成"prompt 方法论"，也设计成了"可编程的执行单元"。一个完整的 SKILL 包含几个部分：
- 元信息：技能 ID、名称、描述、适用场景标签、作者、版本号
- 触发条件：什么输入下激活该技能，可以是关键词规则、语义匹配，也可以是编排层显式指定
- 指令模板：喂给模型的方法论提示词，包含分步骤引导、约束条件、输出格式要求
- 示例集：少量 few-shot 示例，帮助模型理解技能的期望行为
- 工具绑定：该技能推荐使用的工具列表，执行时会自动装配到 Agent
- 校验器（可选）：对执行结果做程序化校验的函数，比如校验输出格式、检查是否包含必填字段
SKILL 的执行机制支持两种模式：一种是自动激活，Agent 根据用户输入判断要不要启用某个技能；另一种是编排显式绑定，流程图上指定了必须执行某个技能，不走模型决策。后者在合规性要求高的场景特别重要，比如"用户投诉处理流程"，你不能指望模型每次都想起来要按规范来。
4.3 写 SKILL 的避坑指南
我从头写过不少 SKILL，也改过不少团队写的 SKILL。有几点经验值得分享：
第一，不要把 SKILL 写成论文。有些人写技能提示词喜欢把所有情况都事无巨细地列出来，结果上下文窗口被大量方法论描述占满，模型反而抓不住重点。我更推荐的方式是：指令模板只写"必须遵循的核心原则 + 关键决策分支"，其他细节放到示例里让模型自己体会。比如客服技能，指令模板只强调"先查订单状态、再查物流详情、异常时表达歉意并说明原因"，剩下的细节靠三个典型示例来示范。
第二，Skill 要可测试。我见过最难受的情况是技能上线后完全不知道模型是否遵循了。后来我们给每个 SKILL 配了回归用例集：把历史真实对话作为测试输入，跑一遍技能，检查输出是否满足校验器。发布新版本时，先跑用例集再决定是否全量上线。这套机制极大降低了对模型行为的"不可知感"。
第三，版本管理不容小觑。SKILL 在内部是像代码一样管理生命周期的：开发版、测试版、生产版。修改一个技能必须走提审流程，发布后有回滚按钮。有一次我们一个客服技能的新版本里 prompt 措辞做了微调，上线后用户满意度下降了几个点，幸亏能一键回滚，才没有扩大影响。以后再也不敢小看 prompt 的版本管理了。
4.4 平台里 SKILL 的复用与组合
SKILL 是可组合的。平台支持一个 Agent 绑定多个 SKILL，并且定义了技能之间的优先级和冲突消解策略。比如一个名为"问题诊断"的技巧可能包含"故障分类"和"解决方案推荐"两个子技能，执行时先跑前者再跑后者。这种组合逻辑我会优先用编排配置声明，而不是塞进提示词里"叮嘱"模型。模型是概率系统，流程性的事务交给引擎，模型只负责它最擅长的语义理解和表达——这是我设计一切编排功能的基本原则。
另外在技能发现方面，每个 SKILL 的描述信息会被注入到 Agent 的系统提示词中，让模型知道"你具备哪些技能，各自适合什么场景"。但这部分描述要写得足够精炼，我见过有些团队把技能描述写得花团锦簇，结果模型上下文被撑爆，模型选技能也选不准——技能描述最好是一句话能说清适用场景，多一个字都是浪费。
5. RAG 接入与知识编排：平台里的知识模块怎么设计
5.1 平台里 RAG 的定位不只是一个"知识库插件"
RAG（检索增强生成）在 AI 平台里经常被当成一个独立插件来用，但我更愿意把它放在"知识编排"的大框架里看。
在很多团队里，RAG 是用来解决"模型不懂私有知识"的问题的：把文档切片、向量化，用户提问时先检索再让模型基于片段回答。但当我跳出"问答机器人"这个视角后发现，RAG 不应该只服务最终用户，更应该服务 Agent 本身。Agent 在执行任务时，常常需要根据某个内部规范、某个流程文档来决定下一步怎么走。这时候 RAG 的价值就不再是"给回答提供资料"，而是"给决策提供依据"。
所以 XXL-AI 里 RAG 模块化的能力不是绑定在某个聊天界面，而是通过一个知识检索工具暴露给所有 Agent。Agent 在编排的任意 Step 都可以主动调用knowledge_search(query, top_k, filters)来获取知识片段，再根据片段决定接下来的策略。知识检索函数本身被包成了一个标准的工具接入到 MCP 体系里，这比把 RAG 做死在某个应用层要灵活得多。
5.2 从零搭一套 RAG 的模块组合
以一个实际的知识库项目为例，我在 XXL-AI 里搭 RAG 通常分四步：
- 文档接入与解析：支持 PDF、Word、Markdown、HTML。这里最大的坑是 PDF 的表格和版式，直接按文本抽取经常乱码。方案是先对扫描件做 OCR，再用版面分析提取段落结构，复杂表格转成 Markdown 表格后再入库。平台默认带了文档解析流水线，按文档类型配置不同的解析链。
- 切分（Chunk）策略：固定长度切分最省事，但语义连接容易断。我的经验是按标题结构和段落边界做层级切分，再给每个 chunk 打上来源文档和章节路径的元数据。有些知识库场景对准确率要求高，我还会做父子分块：父块上下文完整用于理解，子块精确用于召回。
- 向量化：embedding 模型的选择对中文场景尤其敏感。我们试过多种模型，最后效果差异主要在专业术语和长文档上。建议针对自己的语料做一个基础的检索评测集，否则很难比较 embedding 的好坏。
- 召回与重排：只用向量相似度召回，命中率容易卡在某个水平上不去。我后来加了 BM25 关键词召回做融合，再引入重排序模型对召回结果做精排。上线后命中率从五十几个点提到了八十几个点，代价是多了一次重排调用，延迟大约多一两百毫秒，但准确率收益明显。
5.3 关于命中率、图片存储和其他实际瓶颈
RAG 项目的痛点往往不在"建库"，而在"召回效果"和"长尾问题"。命中率上不去，先不要急着换大模型，大概率是检索链路的问题。
有一个热搜问题问"RAG 知识库能不能存图片"，这其实是两个问题。如果你问的是"把图片作为回答时的引用内容"，完全可以，存图片 URL 或其 Base64 由用户端渲染即可；如果你问的是"用图片内容做语义检索"，那就需要多模态 embedding，或者先用多模态大模型把图片转成文字描述再入库。我们实际项目里更常用的是后者：图片自动生成文本摘要后入库，回答时可以引用原图链接。
RAG 的另一个瓶颈是知识更新。线上文档改了，旧 chunk 如果不及时失效会让检索结果越来越混乱。平台里我做了一个"知识血缘"管理：每个 chunk 都记录来源文件的版本号，文件更新后旧版本 chunk 自动标记过期，不参与检索。这样避免了"问了刚更新的问题，模型还在答旧文档"的尴尬。
最后关于检索结果如何给 Agent，我总结了一个小规律：不要把原始 chunk 全部塞给模型，先让重排模型挑最相关的 3~5 段，再在召回片段里把元数据的上下文标题带上。模型能不能准确回答，很多时候就差一个"这段话出自哪个章节"的信息。
6. 工程化底座：可观测性、权限隔离、灰度发布的落地方式
6.1 全链路追踪：从应用视角覆盖到模型与工具层面
AI 应用的可观测性和传统后端不太一样。传统后端追踪的是接口调用链，而 AI 应用追踪的是决策链：用户输入进入 Agent 后，模型经过了哪些推理分支，调了哪些工具，工具返回了什么，最终怎样生成了回答。这组数据在排障时价值极高。
XXL-AI 的追踪系统统一给每个 Agent 运行产生一个 trace，trace 内包含五类 span：
- 编排执行流：Graph、Node、Step 的执行顺序和耗时
- 模型调用：模型名、供应商、输入输出 Token 数、温度配置、是否命中缓存
- 工具调用：MCP 工具名、入参、出参摘要、错误信息
- 检索调用：知识库名、检索 query、召回文档列表、重排结果
- 人工介入：比如人在回环中的审批/SOP 控制节点是否触发
这些 span 统一输出到日志平台，业务方查一个问题：先看编排走到哪一步，再看模型调了哪个工具，再看工具返回是否正常，排查效率比从前"翻代码打日志"高了很多。
这里说个我印象特别深的案例。有一次一个 Agent 在高峰期大面积回答"暂时无法处理"，业务方以为模型挂了。上线查 trace 才发现，模型调用正常，但工具调用那一环，某个外部 SaaS 接口的凭证过期了，错误被 Agent 理解为"服务不可用"，于是给了用户一个"无能为力"的答案。如果当时没有工具层的 trace，这个问题不知道要排查多久。
6.2 多租户权限隔离与凭证管理
在平台里，不同业务线是不同的租户。租户之间要做到四个隔离：Agent 配置隔离、工具权限隔离、知识库隔离、资源配额隔离。
最敏感的是工具权限。两个业务线不能互相调用对方的 MCP 工具。平台在工具授权模型上，设置了"工具注册者"和"工具使用者"两层：注册者定义工具的可见范围，使用者需要显式申请并被审批后才能看到。这样既避免了工具被滥用，也保留了跨团队复用的路径。
凭证管理是我另一个重点盯的对象。MCP Server 的密钥、供应商 API Key 都不能出现在 Agent 日志和调试信息里，统一放到平台密钥管理模块，支持按租户的密钥绑定。有一次我排查问题，打开某服务的环境变量，发现一个代理商密钥被写死在测试环境里，这个坑幸好发现得早。
6.3 限流、熔断与降级的平台化策略
工程化底座也有防雪崩的要求。平台在三个层级做了保护：
- 网关层：按租户/应用做 RPM 限流，超限直接返回 429
- 供应商层：按模型维度的配额定额，防止单个应用耗尽账号额度
- 编排层：工具调用超时和熔断，连续失败超过阈值就自动摘除该工具
这套熔断逻辑我后来做成了平台缺省能力，核心目的就一句话：任何一个外部依赖的故障，都只应该影响它自己的调用，不应该拖垮整个 Agent。比如某个工具连续失败，Agent 可以选择跳过该工具并告知用户部分能力暂不可用，而不是整体报错。
6.4 灰度与回滚：让 Agent 变更不再靠祈祷
AI 应用有一个特点，代码虽然没变，但模型输出会变（上游模型可能悄悄更新了），prompt 变了效果也不完全可预测。所以我把灰度发布当成了平台的刚需功能。
具体做法：一个 Agent 应用可以配置多个版本，流量按百分比切给新版本，版本与版本之间的差异可能是编排逻辑、SKILL 版本、模型参数或者工具绑定。灰度期间自动对比新老版本的业务指标（比如用户满意度打分、工具调用成功率、平均耗时），如果新版本指标明显劣化，自动回滚。这套机制上线后，团队里再没有人说过"这个 Agent 改完怎么情况变差了"这种话——因为不用猜了，直接看灰度对比数据就能定位。
7. 上线至今的踩坑记录与改进清单
7.1 模型不按 schema 调用工具怎么办
这是所有 Agent 平台都会遇到的问题。大模型宣称支持 function calling，但实际调用时就是会忍不住自己发明参数、少传必填项、甚至把参数类型搞错。我们最开始把所有希望寄托在模型自身能力上，后来发现必须加两层防御：
第一层，平台在调用工具前做一次参数校验与修复。能自动补的（比如把"今天"转成具体日期）就补，不能补的就返回模型要求重新生成。这层逻辑千万别偷懒，不然你会经常看到工具报错来自模型传错参。
第二层，在 SKILL 或者应用提示词里约束"你不确定参数时先 explain 或 ask"。我们内部叫"不确定性协议"。宁可让 Agent 多问用户一句，也不要猜一个错误的参数导致业务操作失败。这个教训来自一次订单查询事故——模型把用户的"最近三个月"猜成具体日期，结果查错范围，用户投诉了。
7.2 编排流程设计中的"过度 Agent 化"
还有一次印象深刻的教训是编排流程一开始设计得太"聪明"。为了让 Agent 显得智能，我们把很多决策都交给了模型——包括要不要调工具、要不要问用户、要不要并行执行。结果 Agent 的行为变得很难预测，尤其在用户反复修改意图的对话里，模型的规划经常和上下文信息自相矛盾，开始频频返工。
后来我把编排策略调整成"尽量确定，只在必要处智能"：能画出来的流程就用流程图写死，只有真正需要语义理解的分支才让模型决策。效果立竿见影，Agent 的稳定性和可用性提升了一大截。如果你在做 Agent 平台，一定要记住，一个流程跑得稳、用户能预期它的行为的 Agent，远比一个看起来"聪明但动不动失控"的 Agent 有价值。
7.3 现在沉淀下来的改进清单
项目走到今天，我们沉淀了一套自己的迭代节奏，总结下来大概是这样：
- 新增任何能力，先以"平台能力"的方式接入，不允许业务方绕开平台直接改模型调用参数
- 每次 Agent 行为变更，必须配套回归用例集，用例集不过不能发布
- 每个新接的 MCP 工具，都要有超时、限流、熔断配置才能上生产
- 对外部知识库的数据更新要有版本标记、审计日志，避免旧知识误导
这套清单是我在实际交付中验出来的，不一定适合所有团队，但如果你在做类似的事情，可以直接拿去做基线。
最后分享一个比较个人的感受：AI 应用平台的护城河不是模型，也不是某个炫酷的 Agent Demo，而是把模型能力、工具调用、知识数据和企业工程约束统一治理起来的那层底座。模型会快速更新，工具生态会持续膨胀，但平台层的抽象和治理机制一旦沉淀下来，就能持续为上层应用提供稳定可靠的基础。这也是我坚持把 XXL-AI 做成"工程底座"而不是"聊天机器人框架"的最大原因。
