AI 应用开发这件事，最让人头疼的从来不是模型本身，而是模型之外那一大堆东西：工具怎么接、知识怎么喂、多个模型供应商怎么切换、Agent 跑起来之后怎么调试和观测。我见过太多团队，Demo 阶段用几十行胶水代码就能跑通，一旦要上生产，代码就烂成一团——工具调用散落在各个文件里，RAG 的检索逻辑和业务逻辑缠在一起，换个模型供应商要改十几个地方。XXL-AI 这个项目，本质上就是冲着这些工程化痛点去的：它把 Agent 编排、多供应商接入、MCP + SKILL + RAG 三种扩展能力，以及一整套工程化底座揉进了一个平台里。这篇文章我会从实际落地的角度，把它的核心设计思路、每个模块解决什么问题、以及我在类似系统里踩过的坑，掰开揉碎讲清楚。不管你是刚接触 Agent 开发的新手，还是正在为现有系统做架构升级的老手，都能从中找到可以直接抄作业的部分。
1. 为什么 Agent 开发需要一个"平台"而不是一堆脚本
1.1 从胶水代码到工程化底座的必然演进
刚开始做 Agent 应用的时候，几乎所有人的路径都一样：写一个 Python 脚本，调一下模型 API，把几个工具函数塞进 prompt 里，跑通了就完事。这个阶段没什么问题，因为你要验证的只是"模型能不能理解我的意图"。但当你开始接第二个工具、第三个数据源，当你需要让 Agent 记住上下文、需要它根据用户输入动态选择工具、需要在出错时重试、需要观测每一步的耗时和 token 消耗时，脚本模式就彻底崩了。
我自己的经验是，一个 Agent 应用从 Demo 到生产，代码量会膨胀 10 到 20 倍，而其中真正跟"智能"相关的部分可能只占 10%。剩下的 90% 全是工程问题：状态管理、错误处理、并发控制、日志追踪、配置管理、权限隔离。XXL-AI 这类平台的价值，就是把这 90% 的重复劳动沉淀成基础设施，让你只需要关注那 10% 的业务逻辑。
具体来说，一个 Agent 开发平台至少要解决四类问题。第一类是编排问题：Agent 的执行流程不是线性的，它可能要先规划、再调用工具、再根据结果决定下一步，甚至要多个 Agent 协作。第二类是扩展问题：Agent 的能力边界取决于它能调用什么，工具（MCP）、技能（SKILL）、知识（RAG）就是三种不同维度的扩展。第三类是供应商问题：不同模型各有优劣，成本、速度、能力都不一样，你需要能灵活切换甚至混用。第四类是工程问题：可观测性、可调试性、可部署性，这些决定了你的系统能不能稳定跑在生产环境。
1.2 编排、扩展、供应商、底座：四个维度的拆解
把这四个维度拆开看，每个维度都有它自己的技术选型和设计取舍。
编排维度的核心是"执行图"。最简单的编排是 ReAct 模式——思考、行动、观察循环。但真实场景往往更复杂：你可能需要先做意图识别，再路由到不同的子 Agent，子 Agent 内部又可能有并行任务。XXL-AI 的 Agent 编排能力，本质上是在提供一个可视化的、可配置的执行流程定义方式，让你不用把流程逻辑硬编码在代码里。
扩展维度是 Agent 能力的来源。MCP 解决的是"工具接入标准化"的问题，它定义了一套协议，让任何符合规范的工具都能被 Agent 调用，不用为每个工具写适配代码。SKILL 解决的是"能力封装"的问题，它把一组相关的操作、提示词、知识打包成一个可复用的技能单元。RAG 解决的是"知识注入"的问题，让 Agent 能基于私有知识库回答问题，而不是只依赖模型自身的参数化知识。
供应商维度是成本和质量的控制阀。不同任务对模型的要求不一样，简单分类任务用便宜的小模型就够，复杂推理才需要上大模型。多供应商支持意味着你可以在同一个平台里配置多个模型端点，按任务类型、按成本预算、按可用性动态选择。
工程底座是前面三个维度的支撑。没有好的底座，编排再灵活、扩展再丰富、供应商再多，系统也跑不稳。底座包括配置管理、日志追踪、监控告警、版本控制、灰度发布这些"不性感但致命"的东西。
1.3 一个真实场景：当客服 Agent 需要同时处理工具调用和知识检索
举个具体例子。假设你在做一个电商客服 Agent，用户问"我上周买的那双鞋能退吗，退款要多久到账"。
这个问题需要 Agent 做几件事：首先识别用户身份，这需要调用用户服务接口（工具调用）；然后查询订单状态，这需要访问订单数据库（工具调用）；接着判断退货政策，这需要检索平台的退货规则文档（RAG）；最后综合信息生成回答，并且语气要符合客服规范（SKILL 里定义的提示词模板）。
如果用脚本模式，你可能会写一个巨大的函数，里面串行调用这些逻辑。但问题是：用户服务接口可能超时，订单查询可能返回空，退货政策文档可能更新了版本，客服话术可能要根据用户情绪调整。每一个分支都需要处理，代码很快就失控了。
用平台模式，你可以把用户服务和订单查询注册成 MCP 工具，把退货政策做成 RAG 知识库，把客服话术封装成 SKILL，然后在编排层定义一个流程：先并行调用两个工具，再根据结果决定是否检索知识库，最后用 SKILL 模板生成回答。整个流程可视化、可调试、可复用。这就是平台化的价值。
2. Agent 编排：从 ReAct 循环到可视化执行图
2.1 ReAct 模式的局限性与编排的进阶需求
ReAct（Reasoning + Acting）是 Agent 最经典的执行模式，它的逻辑很简单：模型先输出思考过程，然后决定调用哪个工具，拿到工具结果后再思考，循环直到得出最终答案。这个模式在简单场景下很好用，但一旦任务变复杂，它的局限性就暴露了。
第一个问题是不可控。ReAct 的循环次数是不确定的，模型可能陷入死循环，也可能过早停止。你没法在流程层面设置"最多调用三次工具"这样的硬约束。第二个问题是不可观测。整个执行过程是一个黑盒，你只能看到最终的输入输出，中间每一步的决策依据很难追踪。第三个问题是不可复用。每次执行都是从头开始，之前成功的执行路径没法沉淀成模板。
XXL-AI 的编排能力，我理解它是在 ReAct 的基础上做了结构化。它允许你把 Agent 的执行流程定义成一张有向图，节点是执行单元（比如"调用工具""检索知识""生成回答"），边是流转条件。这样你就能在流程层面控制执行路径，而不是完全交给模型自由发挥。
2.2 编排节点的类型与流转逻辑设计
一个成熟的 Agent 编排系统，通常需要支持几类节点。
LLM 节点是最基础的，它调用模型生成内容。这个节点需要配置模型选择、提示词模板、输入变量映射、输出解析规则。提示词模板支持变量插值，比如把上游节点的输出作为下游节点的输入。
工具节点负责调用外部能力。在 XXL-AI 里，工具调用应该走 MCP 协议，这样工具的定义和调用是解耦的。工具节点需要配置工具名称、参数映射、超时时间、重试策略。
知识检索节点负责 RAG 查询。它需要配置知识库选择、检索策略（向量检索、关键词检索、混合检索）、返回条数、相似度阈值。
条件节点负责流程分支。它根据上游节点的输出做判断，决定走哪条路径。比如"如果订单状态是已发货，走退货流程；如果是未发货，走取消流程"。
并行节点负责并发执行。当多个子任务之间没有依赖关系时，并行执行能显著降低总耗时。比如同时查询用户信息和订单信息。
循环节点负责迭代。当需要对列表中的每个元素执行相同操作时，循环节点能避免重复定义。
这些节点通过边连接起来，边上的条件决定了流转方向。整个图就是一个可执行的流程定义。相比硬编码的 if-else，这种方式的优势在于：流程是数据，不是代码，可以动态修改、可以版本管理、可以可视化调试。
2.3 多 Agent 协作：什么时候需要，怎么设计
单 Agent 能解决的问题是有限的。当任务需要不同领域的专业知识时，多 Agent 协作就变得必要了。比如一个"市场分析"任务，可能需要一个负责数据收集的 Agent、一个负责数据分析的 Agent、一个负责报告撰写的 Agent。
多 Agent 协作的设计有两种主流模式。一种是主从模式：一个主 Agent 负责规划和调度，子 Agent 负责执行具体任务。主 Agent 决定什么时候调用哪个子 Agent，子 Agent 完成后把结果返回给主 Agent。这种模式的控制流是集中的，容易调试。
另一种是对等模式：多个 Agent 之间通过消息传递协作，没有中心调度者。这种模式更灵活，但也更难控制，容易出现消息风暴或者死锁。
在实际落地中，我倾向于主从模式，因为它的可观测性更好。XXL-AI 的编排能力如果支持子流程或者子 Agent 的嵌套，那实现主从模式就很自然：主流程里定义一个"调用子 Agent"的节点，子 Agent 本身也是一个编排图。
提示：多 Agent 协作最容易踩的坑是"职责边界不清"。如果两个 Agent 都能处理同一类任务，模型在调度时就会犹豫，导致执行路径不稳定。设计时一定要让每个 Agent 的职责单一且明确。
2.4 编排的调试与观测：怎么知道 Agent 为什么这样决策
编排系统好不好用，调试能力是关键。一个 Agent 执行失败，可能的原因太多了：提示词写得不好、工具返回了意外结果、知识检索没召回相关内容、模型本身能力不够。如果没有详细的执行日志，你根本无从下手。
我在实际项目里总结的调试要点是：每一步的输入输出都要记录，包括模型的原始响应、工具的调用参数和返回、检索的查询和结果、每个节点的耗时和 token 消耗。这些信息汇总起来，才能还原出 Agent 的完整决策链路。
XXL-AI 作为平台，应该提供执行轨迹的可视化。理想情况下，你能看到一张执行图，每个节点上标注了实际执行的状态、耗时、输入输出摘要。点击某个节点，能看到详细的日志。这样排查问题时，你就能快速定位到是哪个环节出了偏差。
另外，回放能力也很重要。把一次失败的执行记录下来，修改提示词或工具配置后，用相同的输入重新执行，对比两次的差异。这种"改-测-对比"的循环，是优化 Agent 的主要工作方式。
3. MCP + SKILL + RAG：三种扩展能力的定位与配合
3.1 MCP：工具接入的标准化协议
MCP（Model Context Protocol）是这两年 Agent 领域最重要的标准化进展之一。它的核心价值是解耦：工具的定义和工具的调用分离，工具提供方和工具使用方分离。
在没有 MCP 之前，每接一个工具，你都要写适配代码：定义工具的 schema、实现调用逻辑、处理错误和超时。工具多了之后，这些适配代码就成了维护负担。MCP 定义了一套标准协议，工具提供方按照协议暴露自己的能力，Agent 平台按照协议发现和调用工具。这样，接一个新工具可能只需要配置一个地址，不用写代码。
MCP 的工作模式通常是客户端-服务端架构。MCP Server 暴露工具列表和调用接口，MCP Client（也就是 Agent 平台）连接 Server，获取工具列表，然后在需要时调用。传输层可以用标准输入输出，也可以用 HTTP 或者 WebSocket。
在实际使用中，MCP 的几个关键点需要注意。工具描述的质量直接决定模型能否正确选择工具。描述要清晰说明工具的功能、适用场景、参数含义。参数 schema 要严格，类型、必填项、取值范围都要定义清楚，否则模型可能传入非法参数。错误处理要规范，工具执行失败时返回的错误信息要能被模型理解，这样模型才能决定是重试还是换一个工具。
XXL-AI 把 MCP 作为工具扩展的核心机制，意味着它的工具生态是开放的。任何符合 MCP 规范的工具都能接入，不用为每个工具单独开发适配层。这对平台的可扩展性来说是决定性的。
3.2 SKILL：把一组能力封装成可复用的技能单元
如果说 MCP 解决的是"单个工具怎么接"的问题，那 SKILL 解决的是"一组相关能力怎么打包"的问题。
一个 SKILL 通常包含几部分：提示词模板，定义这个技能的执行指令；工具依赖，声明这个技能需要哪些 MCP 工具；知识依赖，声明这个技能需要哪些 RAG 知识库；执行逻辑，定义技能内部的执行流程；输入输出 schema，定义技能的调用接口。
举个例子，"合同审查"这个 SKILL 可能包含：一段审查合同的提示词模板、对文档解析工具的依赖、对法律法规知识库的依赖、一个"提取关键条款-比对法规-生成审查意见"的执行流程。用户调用这个 SKILL 时，只需要传入合同文本，SKILL 内部会自动完成所有步骤。
SKILL 的价值在于复用和组合。一个设计良好的 SKILL，可以在多个 Agent 里复用。多个 SKILL 可以组合成更复杂的能力。这就像软件开发里的函数和模块，是能力封装的基本单元。
设计 SKILL 时，我建议遵循几个原则。单一职责：一个 SKILL 只做一件事，做深做透。接口清晰：输入输出要明确定义，内部实现可以变化，但接口要保持稳定。依赖显式：SKILL 依赖哪些工具和知识库，要显式声明，不能隐式依赖。可测试：每个 SKILL 都应该能独立测试，给定输入能得到预期输出。
3.3 RAG：知识注入的工程化实现
RAG（Retrieval-Augmented Generation）是让 Agent 基于私有知识回答问题的核心技术。它的基本流程是：把知识文档切分成片段，向量化后存入向量数据库；用户提问时，把问题向量化，检索最相关的片段，把片段作为上下文喂给模型生成回答。
这个流程听起来简单，但工程化落地时坑非常多。我按环节拆解一下。
文档处理环节：文档格式五花八门，PDF、Word、HTML、Markdown 都有。解析质量直接影响后续效果。PDF 里的表格、图片、公式，解析不好就会丢失信息。我的经验是，文档解析要尽量保留结构信息，比如标题层级、表格结构、列表关系，这些信息在切分时能帮助保持语义完整性。
切分环节：切分粒度是个权衡。切得太碎，单个片段信息不完整，检索到了也没用；切得太粗，一个片段里混了多个主题，检索精度下降。常见的做法是按语义切分，比如按段落、按章节，同时设置最大长度限制。重叠切分（相邻片段有部分重叠）能缓解边界信息丢失的问题。
向量化环节：嵌入模型的选择很关键。不同模型在不同语言、不同领域上的表现差异很大。中文场景下，要选对中文支持好的嵌入模型。另外，向量维度、归一化方式、距离度量方式都要和检索时保持一致。
检索环节：纯向量检索的问题是，它对关键词匹配不敏感。用户问"XXL-AI 的 MCP 怎么配置"，如果知识库里有一篇标题就是"XXL-AI MCP 配置指南"的文档，但向量相似度不高，就可能检索不到。混合检索（向量 + 关键词）能缓解这个问题。另外，重排序（Rerank）也是提升精度的有效手段：先粗召回一批，再用重排序模型精排。
生成环节：检索到的片段怎么组织进提示词，也有讲究。要给模型明确的指令，比如"基于以下资料回答问题，如果资料中没有相关信息，请明确说明"。片段之间要有清晰的分隔，避免模型混淆。引用来源也要标注，方便追溯。
3.4 三者的配合：一个完整的扩展链路
MCP、SKILL、RAG 不是孤立的，它们在实际场景中是配合使用的。
假设你要做一个"技术文档助手"Agent。用户问"XXL-AI 支持哪些模型供应商"。这个问题的处理链路可能是：Agent 首先通过 SKILL 识别出这是一个"产品功能查询"类问题；然后 SKILL 触发 RAG 检索，从产品文档知识库里找到相关片段；如果知识库里的信息不够新，SKILL 可能还会调用一个 MCP 工具去查询在线的产品配置接口；最后综合知识库和接口返回的信息，生成回答。
这个链路里，SKILL 是编排者，RAG 是知识来源，MCP 是实时数据来源。三者配合，才能给出准确、及时的回答。
注意：RAG 和 MCP 的边界要分清。RAG 适合相对静态的知识，比如产品文档、规章制度、历史资料。MCP 适合动态的数据，比如实时库存、用户状态、订单信息。用错了地方，要么知识更新不及时，要么工具调用过于频繁。
4. 多供应商接入：成本、质量与可用性的平衡术
4.1 为什么不能只绑一家模型供应商
只用一个模型供应商，短期看省事，长期看风险很大。成本风险：单一供应商的定价策略变化，你没有任何议价能力。可用性风险：供应商服务抖动，你的整个系统就挂了。能力风险：不同模型在不同任务上的表现差异很大，只用一个模型意味着你在某些任务上要么过度付费，要么效果不佳。
多供应商接入的核心价值是选择权。你可以根据任务类型选择最合适的模型，根据成本预算动态调整，根据可用性自动故障转移。
4.2 供应商抽象层的设计要点
多供应商接入的技术核心是抽象层。你需要定义一套统一的接口，把不同供应商的 API 差异屏蔽掉。这个抽象层要处理几个问题。
请求格式统一：不同供应商的 API 参数名、消息格式、工具调用格式都不一样。抽象层要把统一的内部格式转换成各供应商的格式。比如 OpenAI 的函数调用格式和 Anthropic 的工具使用格式就有差异，抽象层要做转换。
响应格式统一：同样，不同供应商的响应结构也不同。抽象层要把它们转换成统一的内部格式，这样上层逻辑不用关心底层用的是哪家。
流式输出统一：流式输出是提升用户体验的关键，但不同供应商的流式协议不同。抽象层要统一成一种流式事件格式。
错误处理统一：不同供应商的错误码和错误信息不同。抽象层要归类成统一的错误类型，比如"限流""认证失败""服务不可用"，这样上层才能做统一的处理。
能力声明：不同模型支持的能力不同，有的支持函数调用，有的支持视觉输入，有的支持长上下文。抽象层要提供能力查询接口，让上层知道当前模型能做什么。
4.3 路由策略：按任务、按成本、按可用性
有了抽象层之后，下一步是路由：给定一个请求，怎么决定用哪个模型。
按任务路由是最常见的。简单任务（分类、抽取、格式化）用小模型，复杂任务（推理、创作、多步规划）用大模型。这个策略需要你对任务类型有清晰的分类，并且知道每个模型在不同任务上的表现。
按成本路由是成本敏感场景的选择。给每个请求设置成本预算，在预算内选择能力最强的模型。或者反过来，在满足质量要求的前提下选择最便宜的模型。
按可用性路由是容错策略。主模型不可用时，自动切换到备用模型。这需要健康检查和熔断机制。
按负载路由是性能策略。当某个供应商限流时，把请求分散到其他供应商。
实际落地中，这些策略往往是组合使用的。比如：先按任务类型筛选候选模型，再按可用性排除故障模型，最后按成本选择最优模型。
4.4 实测中的坑：格式差异、限流处理与降级策略
多供应商接入的坑，我踩过不少，分享几个典型的。
格式差异的坑：不同供应商对同一个概念的表达方式不同。比如"系统提示词"，有的供应商是单独的参数，有的供应商是消息列表里的第一条。工具调用的结果返回格式也不同，有的返回 JSON 字符串，有的返回结构化对象。抽象层如果处理不干净，上层就会遇到各种奇怪的解析错误。
限流处理的坑：不同供应商的限流策略不同，有的是按请求数，有的是按 token 数，有的是按并发数。限流触发后的行为也不同，有的直接返回错误，有的会排队。你需要为每个供应商配置合适的重试策略和退避算法。
降级策略的坑：从大模型降级到小模型时，提示词可能需要调整。大模型能理解的复杂指令，小模型可能理解不了。工具调用的格式也可能不兼容。降级不是简单的换个模型地址，而是要有一套完整的适配逻辑。
成本核算的坑：不同供应商的计费方式不同，有的按输入输出分别计费，有的按总量计费，有的有缓存折扣。要做准确的成本核算，需要仔细对接每个供应商的计费接口。
5. 工程化底座：让 Agent 系统跑得稳的那些"不性感"的事
5.1 配置管理：环境、密钥、模型参数的统一治理
Agent 系统的配置项非常多：模型 API 密钥、数据库连接、向量库地址、MCP 服务地址、各种超时和重试参数。这些配置如果散落在代码里，维护起来就是灾难。
配置管理的基本原则是分层和隔离。分层是指配置按环境分（开发、测试、生产），按作用域分（全局、应用级、Agent 级）。隔离是指敏感配置（密钥）和普通配置分开管理，敏感配置要加密存储，访问要审计。
XXL-AI 作为平台，应该提供统一的配置中心。用户在一个地方管理所有配置，不同环境用不同的配置集，密钥加密存储，修改有版本记录。这样既方便管理，也方便排查"为什么生产环境和测试环境行为不一致"这类问题。
5.2 可观测性：日志、指标、追踪三件套
Agent 系统的可观测性比传统系统更重要，因为它的行为是不确定的。同样的输入，模型可能给出不同的输出。没有可观测性，你根本不知道系统在干什么。
日志要记录每个关键步骤的详细信息：请求参数、模型响应、工具调用、检索结果、错误堆栈。日志要结构化，方便查询和分析。
指标要覆盖几个维度：请求量、成功率、延迟分布、token 消耗、成本。这些指标要能按 Agent、按模型、按工具维度聚合，这样才能定位到具体是哪个环节的问题。
追踪要能还原一次完整请求的调用链路。一个用户请求可能触发多个 Agent、多次模型调用、多个工具调用，追踪系统要把这些串起来，形成一个完整的调用树。这样排查问题时，你能看到时间花在哪里、哪个环节出错了。
5.3 版本管理与灰度发布：Agent 迭代的安全网
Agent 的迭代和传统软件不同。改一个提示词，可能让整个 Agent 的行为发生巨大变化。没有版本管理和灰度发布，每次迭代都是一次冒险。
版本管理要覆盖所有可变部分：提示词、工具配置、知识库、编排流程、模型选择。每次变更都要有记录，能回滚。
灰度发布要支持按比例分流。新版本先给一小部分流量，观察指标正常后再逐步扩大。如果指标异常，自动回滚。
A/B 测试是灰度发布的进阶。同时运行两个版本，对比它们的效果指标，用数据决定哪个版本更好。这对提示词优化特别有用。
5.4 安全与权限：Agent 调用外部能力的边界控制
Agent 能调用外部工具，这既是能力也是风险。如果权限控制不当，Agent 可能执行危险操作，比如删除数据、发送消息、调用付费接口。
权限控制要做到最小权限原则：每个 Agent 只能调用它需要的工具，每个工具只能访问它需要的数据。权限要能动态配置，不能硬编码。
操作审计要记录所有工具调用：谁调的、什么时候调的、调了什么、结果是什么。审计日志要不可篡改，保留足够长的时间。
敏感操作确认：对于高风险操作，要有人工确认环节。比如 Agent 要执行退款操作，应该先让客服确认。
输入输出过滤：要防止提示词注入攻击。用户输入可能包含恶意指令，试图让 Agent 执行非预期操作。输入要过滤，输出要检查。
6. 从零搭建一个 XXL-AI 风格的 Agent 应用：实操路径
6.1 环境准备与平台初始化
假设你要基于 XXL-AI 搭建一个 Agent 应用，第一步是环境准备。
你需要准备几类基础设施：模型服务，至少配置两个供应商，一个主力一个备用；向量数据库，用于 RAG 知识存储；关系数据库，用于存储配置、日志、元数据；MCP 服务，把你需要的外部能力封装成 MCP Server。
平台初始化时，先配置模型供应商。填入 API 地址、密钥、模型列表。然后配置 MCP 服务，填入服务地址，平台会自动发现可用的工具。接着创建知识库，上传文档，配置切分和向量化参数。最后创建 Agent，配置编排流程。
6.2 定义第一个 Agent：从需求到编排图
以一个"技术问答助手"为例。需求是：用户提问技术问题，Agent 基于内部技术文档回答，如果文档里没有，就明确告知。
编排图可以这样设计：入口节点接收用户问题；然后是一个 RAG 检索节点，从技术文档知识库检索相关片段；接着是一个条件节点，判断检索结果的相关性；如果相关性高，走 LLM 生成节点，基于检索结果生成回答；如果相关性低，走另一个 LLM 节点，告知用户没有找到相关信息。
这个编排图很简单，但已经体现了核心思路：用条件节点控制流程，用 RAG 节点注入知识，用 LLM 节点生成回答。
6.3 接入 MCP 工具与 SKILL 封装
如果问答助手还需要查询实时的产品信息，就要接入 MCP 工具。假设你有一个产品信息查询服务，把它封装成 MCP Server，暴露一个"查询产品信息"的工具。然后在编排图里加一个工具节点，当 RAG 检索不到时，调用这个工具查询实时信息。
SKILL 封装是把常用的能力组合打包。比如"技术问答"这个 SKILL，包含 RAG 检索、条件判断、LLM 生成这一整套逻辑。封装成 SKILL 后，其他 Agent 也能复用这套逻辑，不用重新编排。
6.4 配置 RAG 知识库与检索策略
RAG 知识库的配置直接影响问答质量。几个关键参数：切分长度，建议 500 到 1000 字符，根据文档特点调整；重叠长度，建议切分长度的 10% 到 20%；检索条数，建议 3 到 5 条，太多会引入噪声；相似度阈值，建议 0.7 左右，低于阈值的片段不采用。
检索策略建议用混合检索：向量检索召回语义相关的，关键词检索召回字面匹配的，两者合并后重排序。这样能兼顾语义理解和精确匹配。
6.5 多供应商配置与路由规则
配置两个模型供应商：一个能力强但贵的主力模型，一个能力弱但便宜的备用模型。路由规则：默认用主力模型；当主力模型限流或不可用时，自动切换到备用模型；对于简单的分类任务，直接用备用模型以节省成本。
路由规则要能动态调整，不能硬编码。平台应该提供配置界面，让你随时修改路由策略。
6.6 上线前的检查清单与压测建议
上线前，我建议做几项检查。功能检查：每个编排节点都能正常执行，工具调用返回正确，RAG 检索召回相关。异常检查：模型超时、工具失败、知识库为空这些异常情况，系统能优雅处理。性能检查：单请求延迟在可接受范围，并发请求下系统稳定。成本检查：单请求的 token 消耗和成本在预算内。
压测时，重点关注几个指标：P99 延迟，最慢的 1% 请求有多慢；错误率，失败请求的占比；限流触发率，有多少请求因为限流被拒绝；成本，压测期间的总消耗。这些指标能帮你发现系统的瓶颈。
7. 我在 Agent 平台落地中踩过的坑与经验
7.1 提示词版本混乱导致的线上事故
有一次，我们的客服 Agent 突然开始用非常生硬的语气回复用户。排查了半天，发现是有人直接在生产环境的配置里改了提示词，把"请用友好的语气"改成了"请简洁回复"。这个改动没有经过测试，直接影响了线上。
教训是：提示词必须版本管理，生产环境的修改必须走发布流程。后来我们规定，所有提示词变更都要先在测试环境验证，通过 A/B 测试对比效果，才能发布到生产。平台如果支持提示词版本管理和灰度发布，这类问题就能避免。
7.2 RAG 召回率低的排查过程
另一个坑是 RAG 召回率低。用户问的问题，知识库里明明有答案，但就是检索不到。排查过程是这样的：先看检索日志，发现检索到的片段确实不相关；然后检查向量化，发现文档切分得太碎，一个完整的答案被切成了好几段，每段都不完整；调整切分策略后，召回率明显提升。
这个经历让我意识到，RAG 的效果很大程度上取决于文档处理质量。切分策略、向量化模型、检索参数，每一个环节都要仔细调优。没有一劳永逸的配置，要根据实际数据不断迭代。
7.3 多供应商切换时的格式兼容问题
多供应商切换时，我们遇到过工具调用格式不兼容的问题。主力模型返回的工具调用参数是 JSON 对象，备用模型返回的是 JSON 字符串。抽象层没有统一处理，导致切换到备用模型后，工具调用全部失败。
解决方案是在抽象层加一层转换：不管底层返回什么格式，统一转换成内部标准格式。这个转换逻辑要覆盖所有支持的供应商，每接入一个新供应商都要测试。
7.4 成本失控的预警与优化
有一次月底对账，发现模型成本比预期高了 3 倍。排查发现，有个 Agent 的编排流程里，RAG 检索节点被配置成了每次都检索 10 条，而且没有相似度阈值过滤。大量不相关的片段被喂给模型，token 消耗暴涨。
优化措施：把检索条数降到 5 条，加上 0.7 的相似度阈值，成本立刻降了一半。另外，我们还加了成本预警：当单日成本超过阈值时，自动发送告警。平台如果内置成本监控和预警，这类问题就能早发现。
7.5 给后来者的几条实用建议
最后分享几条我总结的建议。
从简单场景开始。不要一上来就做复杂的多 Agent 协作，先把单 Agent 加 RAG 跑通，再逐步加工具、加编排、加多供应商。每一步都验证稳定后再往下走。
重视可观测性。日志、指标、追踪，这三样东西在 Agent 系统里比在传统系统里更重要。前期多花点时间搭建可观测性，后期排查问题会省很多时间。
配置化而非硬编码。提示词、路由规则、检索参数，这些都应该配置化。硬编码意味着每次调整都要改代码、重新部署，效率太低。
建立评测集。准备一批典型问题和预期答案，每次修改后跑一遍评测，看效果是提升还是下降。没有评测集，优化就是盲人摸象。
控制成本。Agent 系统的成本很容易失控，因为模型调用是按 token 计费的。设置预算、监控消耗、优化提示词长度、选择合适的模型，这些都是控制成本的手段。
安全不能忽视。Agent 能调用外部工具，这意味着它能产生实际影响。权限控制、操作审计、敏感操作确认，这些安全措施不能省。
保持迭代。Agent 系统不是一次建成就完事的，它需要持续优化。收集用户反馈、分析失败案例、调整提示词和检索策略，这是一个长期的过程。
提示：如果你正在选型 Agent 开发平台，重点考察它的编排能力是否灵活、扩展机制是否开放、多供应商支持是否完善、可观测性是否到位。这四点决定了平台能不能支撑你的长期迭代。
