最近在搭AI应用你一定绕不开这几个词Agent编排、MCP、RAG还有现在越来越多人提到的SKILL。我把自己内部一个项目从“散装大模型API调用”迁移到XXL-AI这类平台型底座之后最大的感受是真正卡住落地的不是模型能力而是怎么把模型、工具、知识库和业务流程串成一个能上线、能运维的东西。这篇就以XXL-AI为例拆一拆AI应用开发平台如何处理Agent编排、多供应商切换以及MCPSKILLRAG三种扩展方式到底怎么协同。适合正在做技术选型、准备自研底座或者想把单点Demo变成产品的团队参考。我用过裸调SDK、也自己拼过工作流后来才慢慢理解平台的价值不在于多花哨的界面而在于把“工程化”这件事提前替你想好了。下面这些内容没有按官方文档式的顺序讲更多是我在实际配置和排障中的体会。1. 内容整体设计与思路拆解1.1 为什么需要一个“工程化底座”很多团队一开始做AI功能都是直接调模型接口。写几个prompt示例封装一个chat函数再配上流式输出看起来很简单。但一旦要上线问题全来了不同供应商的请求格式不一致有的支持function calling有的支持tool calling但参数结构不一样有的限量流有的返回错误码还不标准用户问的问题经常需要拆成多步每一步都要调不同工具模型回答要不带幻觉还需要把企业内部知识库接进来。这些问题零散处理会非常痛苦。XXL-AI这类平台的思路是提供一个“工程化底座”把模型接入、流程编排、工具调用、知识库、可观测性统一收口。你不需要关心每家供应商的SDK细节只需要配置一个别名平台自动帮你路由到对应的供应商你不需要自己写循环和回退逻辑在编排层拖几个节点就行你也不需要每次去拼各种prompt和工具描述SKILL机制可以把这些打包成可复用单元。用生活化的话说这就像你装修房子不会自己烧水泥、拉电线而是用成熟的“水电改造方案”。AI应用开发平台给的就是这套方案插座接口统一了线路规划好了出了问题也知道去哪查电表。1.2 MCP、SKILL、RAG三个扩展词的分工这三个词放在一起容易懵但实际分工很清晰MCPModel Context Protocol模型上下文协议管的是“连接外部工具和数据源”。它定义了一套标准化的通信方式让大模型应用能调用文件系统、数据库、内部API、浏览器等。类比USB-C接口只要设备支持这个协议插上就能用。SKILL管的是“怎么把一件事做好”。它是一个可复用的技能包里面包含触发条件、系统提示词、步骤说明、少样本示例、常用工具调用序列甚至还包括一些禁区。类比岗位SOP或者“老员工带新人的操作手册”。RAGRetrieval-Augmented Generation检索增强生成管的是“从知识库里找到依据”。它把文档切片、向量化、存储在模型回答前把和问题最相关的内容检索出来作为上下文一起送进模型。类比开卷考试时先翻资料再作答。三者协同关系经常是这样的用户提问后Agent判断意图命中某个SKILLSKILL里的步骤需要查订单于是通过MCP调用订单系统如果还涉及退货政策再从RAG知识库检索相关条款最后把所有结果汇总给模型生成。三者不是互相替代而是不同层次的问题。1.3 “多供应商”不是备胎而是基础设施多供应商这个词听起来像是“多一个保险丝”实际作用远不止。首先是用量治理单一供应商在高峰期容易限流尤其是长文本场景如果没有备用通道业务就断了。其次是成本不同模型价格差异很大简单任务用便宜的小模型复杂推理用旗舰模型按任务类型做路由能省下大量成本。再就是合规与稳定某些场景需要把数据留在特定区域供应商如果出现可用性问题可以灰度切换。XXL-AI的做法是在模型层做统一抽象所有供应商统一成一套接口模型别名alias指向具体供应商和模型版本。应用层只认别名不直接写死供应商。这样切换供应商时不需要改业务代码只需要调整别名映射或故障转移策略。这里有个容易踩的坑不是所有模型参数都通用。比如有的模型支持temperature但不支持frequency_penalty有的支持tool calling但tool schema格式有差异。平台需要在统一接口层做参数归一化和兼容性转换否则fallback到另一家时会出现400错误而不是真正“无缝切换”。2. Agent 编排与多供应商切换的核心机制2.1 Agent 编排到底在编什么Agent编排的难点不是“画几条线连起来”而是状态管理和容错。一个复杂任务通常会被拆成多个节点意图识别节点、信息抽取节点、工具调用节点、知识检索节点、条件分支节点、回复生成节点有时还带人工审核节点。每个节点都要处理上下文传递。用户在对话中说了“这个订单怎么还没发货”这里的“这个”到底指哪个订单可能是前一轮提到的订单号。所以编排必须能把对话状态、实体信息、中间结果放进一个全局上下文窗口后续节点才能正确引用。一个有价值的编排设计是Planner-Executor-Critic模式。Planner负责把用户目标拆成子任务Executor逐步执行工具调用Critic检查结果是否满足目标如果不满足就重新规划。这套模式在XXL-AI里可以做成一个“多Agent编排示例”主Agent负责任务分解两个子Agent分别负责工具执行和质量校验主Agent最后汇总。但不要为了编排而编排。节点层级太深一方面增加推理延迟和token消耗另一方面也更容易出错。我的经验是能用单模型工具调用解决的不要硬拆成多Agent如果拆每个子Agent的职责边界一定要清晰最好有独立的输出校验标准。2.2 多供应商抽象层的设计与容错多供应商接入需要考虑四个维度协议适配、参数归一化、错误码映射、故障转移。协议适配很好理解OpenAI格式、Anthropic格式、国内一些厂商的格式并不完全一致。平台一般会把它们统一转成内部标准格式业务层拿到的是统一的Message和ToolCall结构。参数归一化要小心。有些供应商支持max_tokens有些叫max_completion_tokens有些支持logprobs有些不支持。平台需要维护一个能力矩阵应用层请求某个能力时如果当前模型不支持要么自动忽略要么启用降级策略。错误码映射是很多人忽略的点。供应商A返回429表示限流供应商B返回429可能表示余额不足还有些供应商会把参数错误也包装成400。如果fallback逻辑只按HTTP状态码判断很可能在参数错误时也切到备用模型结果备用模型同样报错。正确做法是解析供应商返回的错误body识别出真正的错误类型再决定是否转移。故障转移不是简单的“报错就换”还要考虑幂等性和状态同步。假如主模型已经产生了中间工具调用切换到备用模型时这些工具结果要不要继续保留如果保留备用模型能否正确理解我建议在设计时把工具调用结果作为纯文本上下文传给备用模型避免因为工具schema兼容问题导致二次失败。2.3 一个完整的编排示例客服Agent用一个实际例子说明。假设要做一个客服Agent需求是用户查询订单状态时Agent调用订单查询工具用户问退货规则时从知识库检索用户情绪激烈时转人工最后所有回复都要有礼貌、简洁。在XXL-AI里这个Agent的编排可以拆成四个节点意图识别节点用一个小模型比如3.5级别判断用户意图输出query_order、return_policy、human_handoff、general_chat四类。工具/知识节点按意图路由到MCP工具或RAG检索。条件分支节点根据是否有订单号、检索结果置信度等条件决定是否追问或直接回复。回复生成节点把工具结果、知识片段、对话历史交给主模型生成最终回复。这个编排的优势是意图识别用便宜模型回复生成用更强的模型整体成本可控错误可以追溯到具体节点而不是整个Agent一坨黑盒。用JSON配置大致长这样{ agent: customer_service_v1, nodes: [ { id: intent_classify, type: llm, model_alias: classifier-fast, prompt: 判断用户意图输出以下四类之一..., output_schema: intent }, { id: route, type: switch, condition: { intent query_order: order_tool, intent return_policy: rag_search, intent human_handoff: handoff_node, default: general_reply } }, { id: order_tool, type: mcp_call, tool: query_order, params: { order_id: ${context.order_id} } }, { id: rag_search, type: rag, kb: return_policy_kb, query: ${user_input}, top_k: 5 } ] }实际运行时那个${context.order_id}需要注意用户不会直接给订单号可能需要信息抽取节点先从对话里提取。这就是前面说的状态管理很多编排跑不通都是因为中间变量没接上。3. 实操把 MCP、SKILL、RAG 跑进同一个平台3.1 MCP 接入从 Server 注册到工具白名单MCP接入的第一步是注册一个MCP Server。MCP Server可以是一个本地进程通过网络或标准输入输出与平台通信。常见传输方式有stdio、SSE、Streamable HTTP。在XXL-AI里配置一个本地MCP Server大概是这样的mcp_servers: order_api: transport: stdio command: node args: - ./servers/order-mcp-server/index.js env: API_BASE: https://api.internal.example.com API_KEY: ${env:ORDER_API_KEY} allow_tools: - query_order - cancel_order - update_order_remark这里有两个容易被忽略的细节。第一个是allow_tools白名单。如果不加白名单Agent能看到这个Server暴露的所有工具可能会尝试调用一些高风险接口。加白名单既是安全手段也是减少工具数量、降低模型误选概率的方法。工具数量过多Agent的tool calling准确率会明显下降所以宁可少给。第二个是密钥注入方式。不要把密钥直接写在配置文件里用${env:ORDER_API_KEY}这种环境变量引用避免代码库泄露。MCP Server本身也要做鉴权尤其当你的MCP Server暴露到公网时至少要校验来源IP和API Key。注册完成后要验证工具能不能被正确调用。平台一般有调试控制台可以列出工具列表再手动发起一次调用。我第一次接入时就看到工具名多了order_api__query_order这样带Server前缀的结构这在Agent编排里引用工具名时要特别注意命名空间不同调用就会失败。3.2 写好一个真正有用的 SKILLSKILL不是一个“高级prompt”那么简单。它要能被Agent命中、能指导Agent一步步执行、还能被质量评估。我见过很多SKILL只写“你是一个专业的客服”这种基本没用。一个可用的SKILL至少包含四部分触发条件什么情况下Agent应该使用这个技能。比如“用户询问订单状态且上下文中有订单号”。输入要求需要哪些字段缺少时怎么追问。执行步骤先做什么再做什么调用哪些MCP工具按什么顺序。输出规范回复格式、长度、语气以及绝对不要做的事。举一个简化例子处理“订单催发货”的SKILL。## 订单催发货处理 - 触发条件用户对发货时间不满或询问“为什么还没发货”。 - 输入要求order_id从对话中提取缺失则先询问。 - 执行步骤 1. 调用 query_order 查询订单状态 2. 如果 status shipped回复物流单号并致歉 3. 如果 status pending查询预计发货时间 4. 如果超过承诺时间转人工处理。 - 注意事项 - 不要直接承诺赔偿 - 不要提及内部仓储流程 - 回复控制在50字内。在实际使用中我发现SKILL里的“反向约束”比“正向描述”更重要。比如“不要承诺赔偿”因为模型一旦自由发挥很容易说出给用户造成预期的话。把这类约束写进SKILL能在很大程度上提升结果稳定性。SKILL还应该有版本号。一个技能经过多次迭代它的适用范围和行为都会变化。可以给SKILL分配类似SKILL-247这种编码标识版本和迭代批次方便在Agent编排中引用精确版本也方便灰度验证。尤其当平台同时存在多个技能版本时编码管理能避免线上Agent引用到旧技能。3.3 RAG 知识库的工程化步骤和参数选择RAG经常被误解成“把文档塞进向量库就完事”。实际上知识库质量决定RAG效果而质量主要来自前面的解析和切分阶段。首先是文档解析。PDF、Word、网页、图片处理方式都不同。有人问“RAG知识库能存储图片吗”答案是能但不能只存一张图让模型“看”多数纯文本模型看不懂图片内容。工程上的做法是先用OCR把图片里的文字抽出来再走后面流程。如果这张图本身就是用户要检索的目标比如产品logo图那要单独为它建图片向量库用多模态模型生成描述或向量。然后是文本切分。切分太粗检索结果冗余切分太细语义被截断。一般按段落切分同时保留标题上下文。一个常用配置是chunk_size500字符overlap50字符。但这不是万能参数技术文档和对话记录的最佳值差很多。标准做法是取一批真实问题做召回评测调整参数到命中率比较稳定为止。向量化也需要选embedding模型。中英文混合场景要选多语言模型比如基于bge系列或text-embedding-3-large如果是代码和普通文本混合可能需要专门的代码embedding模型。向量维度越高不一定越好还影响存储和检索速度。存储和检索层可以选择向量数据库也可以直接用PG的向量插件。TopK通常取5~10但不能只靠相似度分数决定“是否可用”最好加一个score阈值低于阈值的检索结果不要硬塞给模型否则会引入噪声。一个完整RAG配置示例rag_config: kb_name: return_policy_kb loader: pdf: true docx: true image_ocr: true chunk: size: 500 overlap: 50 strategy: markdown_header embedding: model: bge-m3 dimension: 1024 retrieval: top_k: 8 score_threshold: 0.65 rerank: true rerank_model: bge-reranker-large index: incremental_update: true versioned: true这里的关键是rerank。第一轮向量检索的TopK可以放宽到20再用rerank模型精排取前5。这个组合比单纯加大TopK更精准因为向量召回负责“莫要漏”rerank负责“精中选精”。RAG真正的瓶颈往往不在向量检索而在“能不能检索到与问题语义一致的片段”。比如用户问“退货要多久到账”文档里写的是“退款将在3-5个工作日内原路返回”两者问法不同但语义相关。如果检索不到问题可能出在切分把答案拆断了或者embedding模型对“到账”和“退款”的语义关联不够强。排查顺序是先看召回片段再看切分方式最后换embedding模型不要一上来就怀疑向量数据库。4. 常见问题与排查技巧实录4.1 高频问题速查表下面这个表是我在配置XXL-AI过程中遇到最多的问题列成速查表方便你直接用现象可能原因排查与解决Agent循环执行不停止缺少最大迭代限制条件分支判断反复不收敛设置max_iterations为5~8检查条件分支是否覆盖所有路径对中间结果做去重工具调用一直超时MCP Server启动慢外部API响应慢调大timeout_ms确认MCP Server日志给外部API增加缓存主模型报错后fallback到备用模型但备用模型也失败错误码映射不细参数兼容问题被当作故障转移条件看错误body里的具体code对参数不兼容做降级而不是切换模型RAG检索不到答案切分策略不当embedding模型不合适score阈值过高先用调试模式看TopK召回片段降低阈值换切分或embedding模型MCP Server显示离线命令路径错误环境变量缺失stdio进程启动失败手动在命令行执行启动命令确认node/python路径查看平台运行日志上下文超限多轮对话历史太长中间结果太大对早期消息做摘要只保留最近N轮和关键上下文工具结果截断排查时有一个总原则先看日志再看配置最后再看代码。平台日志里通常记录了每个节点的输入输出和token消耗很多时候问题一眼就能定位。4.2 我在项目中踩过的几个坑第一个坑是给Agent的工具权限太宽。我一开始把所有MCP工具都开放给Agent结果它在一个简单问答中连续调用了三个工具其中两个完全没必要既浪费token也增加延迟。后来我把工具白名单缩到五个准确率反而提升了。工具不是越多越好每个工具都要有清晰的描述和参数说明否则模型会乱猜。第二个坑是SKILL只写了正向指令忘了负向约束。我的一个“售后安抚”技能没写“不要主动提供赔偿方案”结果模型在安抚用户时自作主张说“我们将为您补偿20元优惠券”。这不是模型“坏”而是技能边界不明确。加上约束并做几轮测试才稳定下来。第三个坑是RAG的增量更新。我最初用离线脚本全量重建知识库每次都要十几分钟而且会暂时查询不到数据。后来改成增量更新新文档先切分、向量化、写入新版本构建成功后切换索引旧版本保留。这样线上查询基本无感。知识库不能只关注“建”还要关注“更新”和“失效”文档被删除后向量库里如果还残留就会一直带出错误信息所以要保留删除记录和索引清理策略。第四个坑是关于故障转移的。我们配置了两个供应商主模型是A备用模型是B。一次线上故障中A供应商返回的错误其实是“请求中包含不支持的参数”我们判断成“限流”就切换到了B结果B同样不支持那个参数双双失败用户看到的是服务不可用。从那以后我们把错误码解析做细了并且区分了“可重试的错误”和“不可重试的错误”。5. 一些想对准备上手的人说的话我个人实际使用下来最值钱的反而不是某一家模型或某个酷炫技能而是稳定的工程底座。MCP、SKILL、RAG这三个词拆开都不算陌生但真正把它们放进同一个平台形成一套可运维、可观测、可灰度的工作流才是XXL-AI这类平台存在的意义。如果准备开始做我的建议是先跑通一个最小闭环。不要急着把所有供应商都接上也不要一次性设计十几个编排节点。先选一个主模型、一个MCP工具、一个知识库搭一个能回答特定问题的Agent再逐步增加复杂度和容错。等你发现单点模型确实不够用了再加替补供应商等你发现某个流程反复需要手工干预再把它拆成SKILL。从简单到复杂每一步都有验证这样才不会把自己淹没在“平台配置”里。最后再分享一个小技巧在编排节点的关键位置加“人工审计”节点。尤其是涉及客户承诺、工单创建、费用计算等敏感操作时让Agent先产出草稿人工确认后再执行。AI应用平台不是把“人”去掉而是把重复工作省掉让人专注在最需要判断的地方。这样既稳又不容易翻车。
最近在搭AI应用你一定绕不开这几个词Agent编排、MCP、RAG还有现在越来越多人提到的SKILL。我把自己内部一个项目从“散装大模型API调用”迁移到XXL-AI这类平台型底座之后最大的感受是真正卡住落地的不是模型能力而是怎么把模型、工具、知识库和业务流程串成一个能上线、能运维的东西。这篇就以XXL-AI为例拆一拆AI应用开发平台如何处理Agent编排、多供应商切换以及MCPSKILLRAG三种扩展方式到底怎么协同。适合正在做技术选型、准备自研底座或者想把单点Demo变成产品的团队参考。我用过裸调SDK、也自己拼过工作流后来才慢慢理解平台的价值不在于多花哨的界面而在于把“工程化”这件事提前替你想好了。下面这些内容没有按官方文档式的顺序讲更多是我在实际配置和排障中的体会。1. 内容整体设计与思路拆解1.1 为什么需要一个“工程化底座”很多团队一开始做AI功能都是直接调模型接口。写几个prompt示例封装一个chat函数再配上流式输出看起来很简单。但一旦要上线问题全来了不同供应商的请求格式不一致有的支持function calling有的支持tool calling但参数结构不一样有的限量流有的返回错误码还不标准用户问的问题经常需要拆成多步每一步都要调不同工具模型回答要不带幻觉还需要把企业内部知识库接进来。这些问题零散处理会非常痛苦。XXL-AI这类平台的思路是提供一个“工程化底座”把模型接入、流程编排、工具调用、知识库、可观测性统一收口。你不需要关心每家供应商的SDK细节只需要配置一个别名平台自动帮你路由到对应的供应商你不需要自己写循环和回退逻辑在编排层拖几个节点就行你也不需要每次去拼各种prompt和工具描述SKILL机制可以把这些打包成可复用单元。用生活化的话说这就像你装修房子不会自己烧水泥、拉电线而是用成熟的“水电改造方案”。AI应用开发平台给的就是这套方案插座接口统一了线路规划好了出了问题也知道去哪查电表。1.2 MCP、SKILL、RAG三个扩展词的分工这三个词放在一起容易懵但实际分工很清晰MCPModel Context Protocol模型上下文协议管的是“连接外部工具和数据源”。它定义了一套标准化的通信方式让大模型应用能调用文件系统、数据库、内部API、浏览器等。类比USB-C接口只要设备支持这个协议插上就能用。SKILL管的是“怎么把一件事做好”。它是一个可复用的技能包里面包含触发条件、系统提示词、步骤说明、少样本示例、常用工具调用序列甚至还包括一些禁区。类比岗位SOP或者“老员工带新人的操作手册”。RAGRetrieval-Augmented Generation检索增强生成管的是“从知识库里找到依据”。它把文档切片、向量化、存储在模型回答前把和问题最相关的内容检索出来作为上下文一起送进模型。类比开卷考试时先翻资料再作答。三者协同关系经常是这样的用户提问后Agent判断意图命中某个SKILLSKILL里的步骤需要查订单于是通过MCP调用订单系统如果还涉及退货政策再从RAG知识库检索相关条款最后把所有结果汇总给模型生成。三者不是互相替代而是不同层次的问题。1.3 “多供应商”不是备胎而是基础设施多供应商这个词听起来像是“多一个保险丝”实际作用远不止。首先是用量治理单一供应商在高峰期容易限流尤其是长文本场景如果没有备用通道业务就断了。其次是成本不同模型价格差异很大简单任务用便宜的小模型复杂推理用旗舰模型按任务类型做路由能省下大量成本。再就是合规与稳定某些场景需要把数据留在特定区域供应商如果出现可用性问题可以灰度切换。XXL-AI的做法是在模型层做统一抽象所有供应商统一成一套接口模型别名alias指向具体供应商和模型版本。应用层只认别名不直接写死供应商。这样切换供应商时不需要改业务代码只需要调整别名映射或故障转移策略。这里有个容易踩的坑不是所有模型参数都通用。比如有的模型支持temperature但不支持frequency_penalty有的支持tool calling但tool schema格式有差异。平台需要在统一接口层做参数归一化和兼容性转换否则fallback到另一家时会出现400错误而不是真正“无缝切换”。2. Agent 编排与多供应商切换的核心机制2.1 Agent 编排到底在编什么Agent编排的难点不是“画几条线连起来”而是状态管理和容错。一个复杂任务通常会被拆成多个节点意图识别节点、信息抽取节点、工具调用节点、知识检索节点、条件分支节点、回复生成节点有时还带人工审核节点。每个节点都要处理上下文传递。用户在对话中说了“这个订单怎么还没发货”这里的“这个”到底指哪个订单可能是前一轮提到的订单号。所以编排必须能把对话状态、实体信息、中间结果放进一个全局上下文窗口后续节点才能正确引用。一个有价值的编排设计是Planner-Executor-Critic模式。Planner负责把用户目标拆成子任务Executor逐步执行工具调用Critic检查结果是否满足目标如果不满足就重新规划。这套模式在XXL-AI里可以做成一个“多Agent编排示例”主Agent负责任务分解两个子Agent分别负责工具执行和质量校验主Agent最后汇总。但不要为了编排而编排。节点层级太深一方面增加推理延迟和token消耗另一方面也更容易出错。我的经验是能用单模型工具调用解决的不要硬拆成多Agent如果拆每个子Agent的职责边界一定要清晰最好有独立的输出校验标准。2.2 多供应商抽象层的设计与容错多供应商接入需要考虑四个维度协议适配、参数归一化、错误码映射、故障转移。协议适配很好理解OpenAI格式、Anthropic格式、国内一些厂商的格式并不完全一致。平台一般会把它们统一转成内部标准格式业务层拿到的是统一的Message和ToolCall结构。参数归一化要小心。有些供应商支持max_tokens有些叫max_completion_tokens有些支持logprobs有些不支持。平台需要维护一个能力矩阵应用层请求某个能力时如果当前模型不支持要么自动忽略要么启用降级策略。错误码映射是很多人忽略的点。供应商A返回429表示限流供应商B返回429可能表示余额不足还有些供应商会把参数错误也包装成400。如果fallback逻辑只按HTTP状态码判断很可能在参数错误时也切到备用模型结果备用模型同样报错。正确做法是解析供应商返回的错误body识别出真正的错误类型再决定是否转移。故障转移不是简单的“报错就换”还要考虑幂等性和状态同步。假如主模型已经产生了中间工具调用切换到备用模型时这些工具结果要不要继续保留如果保留备用模型能否正确理解我建议在设计时把工具调用结果作为纯文本上下文传给备用模型避免因为工具schema兼容问题导致二次失败。2.3 一个完整的编排示例客服Agent用一个实际例子说明。假设要做一个客服Agent需求是用户查询订单状态时Agent调用订单查询工具用户问退货规则时从知识库检索用户情绪激烈时转人工最后所有回复都要有礼貌、简洁。在XXL-AI里这个Agent的编排可以拆成四个节点意图识别节点用一个小模型比如3.5级别判断用户意图输出query_order、return_policy、human_handoff、general_chat四类。工具/知识节点按意图路由到MCP工具或RAG检索。条件分支节点根据是否有订单号、检索结果置信度等条件决定是否追问或直接回复。回复生成节点把工具结果、知识片段、对话历史交给主模型生成最终回复。这个编排的优势是意图识别用便宜模型回复生成用更强的模型整体成本可控错误可以追溯到具体节点而不是整个Agent一坨黑盒。用JSON配置大致长这样{ agent: customer_service_v1, nodes: [ { id: intent_classify, type: llm, model_alias: classifier-fast, prompt: 判断用户意图输出以下四类之一..., output_schema: intent }, { id: route, type: switch, condition: { intent query_order: order_tool, intent return_policy: rag_search, intent human_handoff: handoff_node, default: general_reply } }, { id: order_tool, type: mcp_call, tool: query_order, params: { order_id: ${context.order_id} } }, { id: rag_search, type: rag, kb: return_policy_kb, query: ${user_input}, top_k: 5 } ] }实际运行时那个${context.order_id}需要注意用户不会直接给订单号可能需要信息抽取节点先从对话里提取。这就是前面说的状态管理很多编排跑不通都是因为中间变量没接上。3. 实操把 MCP、SKILL、RAG 跑进同一个平台3.1 MCP 接入从 Server 注册到工具白名单MCP接入的第一步是注册一个MCP Server。MCP Server可以是一个本地进程通过网络或标准输入输出与平台通信。常见传输方式有stdio、SSE、Streamable HTTP。在XXL-AI里配置一个本地MCP Server大概是这样的mcp_servers: order_api: transport: stdio command: node args: - ./servers/order-mcp-server/index.js env: API_BASE: https://api.internal.example.com API_KEY: ${env:ORDER_API_KEY} allow_tools: - query_order - cancel_order - update_order_remark这里有两个容易被忽略的细节。第一个是allow_tools白名单。如果不加白名单Agent能看到这个Server暴露的所有工具可能会尝试调用一些高风险接口。加白名单既是安全手段也是减少工具数量、降低模型误选概率的方法。工具数量过多Agent的tool calling准确率会明显下降所以宁可少给。第二个是密钥注入方式。不要把密钥直接写在配置文件里用${env:ORDER_API_KEY}这种环境变量引用避免代码库泄露。MCP Server本身也要做鉴权尤其当你的MCP Server暴露到公网时至少要校验来源IP和API Key。注册完成后要验证工具能不能被正确调用。平台一般有调试控制台可以列出工具列表再手动发起一次调用。我第一次接入时就看到工具名多了order_api__query_order这样带Server前缀的结构这在Agent编排里引用工具名时要特别注意命名空间不同调用就会失败。3.2 写好一个真正有用的 SKILLSKILL不是一个“高级prompt”那么简单。它要能被Agent命中、能指导Agent一步步执行、还能被质量评估。我见过很多SKILL只写“你是一个专业的客服”这种基本没用。一个可用的SKILL至少包含四部分触发条件什么情况下Agent应该使用这个技能。比如“用户询问订单状态且上下文中有订单号”。输入要求需要哪些字段缺少时怎么追问。执行步骤先做什么再做什么调用哪些MCP工具按什么顺序。输出规范回复格式、长度、语气以及绝对不要做的事。举一个简化例子处理“订单催发货”的SKILL。## 订单催发货处理 - 触发条件用户对发货时间不满或询问“为什么还没发货”。 - 输入要求order_id从对话中提取缺失则先询问。 - 执行步骤 1. 调用 query_order 查询订单状态 2. 如果 status shipped回复物流单号并致歉 3. 如果 status pending查询预计发货时间 4. 如果超过承诺时间转人工处理。 - 注意事项 - 不要直接承诺赔偿 - 不要提及内部仓储流程 - 回复控制在50字内。在实际使用中我发现SKILL里的“反向约束”比“正向描述”更重要。比如“不要承诺赔偿”因为模型一旦自由发挥很容易说出给用户造成预期的话。把这类约束写进SKILL能在很大程度上提升结果稳定性。SKILL还应该有版本号。一个技能经过多次迭代它的适用范围和行为都会变化。可以给SKILL分配类似SKILL-247这种编码标识版本和迭代批次方便在Agent编排中引用精确版本也方便灰度验证。尤其当平台同时存在多个技能版本时编码管理能避免线上Agent引用到旧技能。3.3 RAG 知识库的工程化步骤和参数选择RAG经常被误解成“把文档塞进向量库就完事”。实际上知识库质量决定RAG效果而质量主要来自前面的解析和切分阶段。首先是文档解析。PDF、Word、网页、图片处理方式都不同。有人问“RAG知识库能存储图片吗”答案是能但不能只存一张图让模型“看”多数纯文本模型看不懂图片内容。工程上的做法是先用OCR把图片里的文字抽出来再走后面流程。如果这张图本身就是用户要检索的目标比如产品logo图那要单独为它建图片向量库用多模态模型生成描述或向量。然后是文本切分。切分太粗检索结果冗余切分太细语义被截断。一般按段落切分同时保留标题上下文。一个常用配置是chunk_size500字符overlap50字符。但这不是万能参数技术文档和对话记录的最佳值差很多。标准做法是取一批真实问题做召回评测调整参数到命中率比较稳定为止。向量化也需要选embedding模型。中英文混合场景要选多语言模型比如基于bge系列或text-embedding-3-large如果是代码和普通文本混合可能需要专门的代码embedding模型。向量维度越高不一定越好还影响存储和检索速度。存储和检索层可以选择向量数据库也可以直接用PG的向量插件。TopK通常取5~10但不能只靠相似度分数决定“是否可用”最好加一个score阈值低于阈值的检索结果不要硬塞给模型否则会引入噪声。一个完整RAG配置示例rag_config: kb_name: return_policy_kb loader: pdf: true docx: true image_ocr: true chunk: size: 500 overlap: 50 strategy: markdown_header embedding: model: bge-m3 dimension: 1024 retrieval: top_k: 8 score_threshold: 0.65 rerank: true rerank_model: bge-reranker-large index: incremental_update: true versioned: true这里的关键是rerank。第一轮向量检索的TopK可以放宽到20再用rerank模型精排取前5。这个组合比单纯加大TopK更精准因为向量召回负责“莫要漏”rerank负责“精中选精”。RAG真正的瓶颈往往不在向量检索而在“能不能检索到与问题语义一致的片段”。比如用户问“退货要多久到账”文档里写的是“退款将在3-5个工作日内原路返回”两者问法不同但语义相关。如果检索不到问题可能出在切分把答案拆断了或者embedding模型对“到账”和“退款”的语义关联不够强。排查顺序是先看召回片段再看切分方式最后换embedding模型不要一上来就怀疑向量数据库。4. 常见问题与排查技巧实录4.1 高频问题速查表下面这个表是我在配置XXL-AI过程中遇到最多的问题列成速查表方便你直接用现象可能原因排查与解决Agent循环执行不停止缺少最大迭代限制条件分支判断反复不收敛设置max_iterations为5~8检查条件分支是否覆盖所有路径对中间结果做去重工具调用一直超时MCP Server启动慢外部API响应慢调大timeout_ms确认MCP Server日志给外部API增加缓存主模型报错后fallback到备用模型但备用模型也失败错误码映射不细参数兼容问题被当作故障转移条件看错误body里的具体code对参数不兼容做降级而不是切换模型RAG检索不到答案切分策略不当embedding模型不合适score阈值过高先用调试模式看TopK召回片段降低阈值换切分或embedding模型MCP Server显示离线命令路径错误环境变量缺失stdio进程启动失败手动在命令行执行启动命令确认node/python路径查看平台运行日志上下文超限多轮对话历史太长中间结果太大对早期消息做摘要只保留最近N轮和关键上下文工具结果截断排查时有一个总原则先看日志再看配置最后再看代码。平台日志里通常记录了每个节点的输入输出和token消耗很多时候问题一眼就能定位。4.2 我在项目中踩过的几个坑第一个坑是给Agent的工具权限太宽。我一开始把所有MCP工具都开放给Agent结果它在一个简单问答中连续调用了三个工具其中两个完全没必要既浪费token也增加延迟。后来我把工具白名单缩到五个准确率反而提升了。工具不是越多越好每个工具都要有清晰的描述和参数说明否则模型会乱猜。第二个坑是SKILL只写了正向指令忘了负向约束。我的一个“售后安抚”技能没写“不要主动提供赔偿方案”结果模型在安抚用户时自作主张说“我们将为您补偿20元优惠券”。这不是模型“坏”而是技能边界不明确。加上约束并做几轮测试才稳定下来。第三个坑是RAG的增量更新。我最初用离线脚本全量重建知识库每次都要十几分钟而且会暂时查询不到数据。后来改成增量更新新文档先切分、向量化、写入新版本构建成功后切换索引旧版本保留。这样线上查询基本无感。知识库不能只关注“建”还要关注“更新”和“失效”文档被删除后向量库里如果还残留就会一直带出错误信息所以要保留删除记录和索引清理策略。第四个坑是关于故障转移的。我们配置了两个供应商主模型是A备用模型是B。一次线上故障中A供应商返回的错误其实是“请求中包含不支持的参数”我们判断成“限流”就切换到了B结果B同样不支持那个参数双双失败用户看到的是服务不可用。从那以后我们把错误码解析做细了并且区分了“可重试的错误”和“不可重试的错误”。5. 一些想对准备上手的人说的话我个人实际使用下来最值钱的反而不是某一家模型或某个酷炫技能而是稳定的工程底座。MCP、SKILL、RAG这三个词拆开都不算陌生但真正把它们放进同一个平台形成一套可运维、可观测、可灰度的工作流才是XXL-AI这类平台存在的意义。如果准备开始做我的建议是先跑通一个最小闭环。不要急着把所有供应商都接上也不要一次性设计十几个编排节点。先选一个主模型、一个MCP工具、一个知识库搭一个能回答特定问题的Agent再逐步增加复杂度和容错。等你发现单点模型确实不够用了再加替补供应商等你发现某个流程反复需要手工干预再把它拆成SKILL。从简单到复杂每一步都有验证这样才不会把自己淹没在“平台配置”里。最后再分享一个小技巧在编排节点的关键位置加“人工审计”节点。尤其是涉及客户承诺、工单创建、费用计算等敏感操作时让Agent先产出草稿人工确认后再执行。AI应用平台不是把“人”去掉而是把重复工作省掉让人专注在最需要判断的地方。这样既稳又不容易翻车。
