定制 Agent 的项目风险不在模型,在边界:改哪一层、谁提供接口、以什么身份调用、联调顺序怎么排。这四个问题在开工前写清楚,后面每一次变更都省一轮返工。
先把定制拆成三层
企业说的“定制”,通常混着三件事:改配置、做集成、写代码。三者交付主体和风险完全不同,报价与合同也应当分开写。
第一层是配置层。知识库结构、工作流编排、提示词、发布渠道、权限分配都属于这一层,业务方与实施方在管理台里就能完成。这一层主要使用平台配置,实施排期取决于流程复杂度与测试范围。
第二层是集成层。把 Agent 接到 OA、ERP 或业务数据库上,靠的是应用对外接口、插件机制与工具调用。系统提供外部接口与插件体系用于衔接第三方工具,也支持把应用发布到企业微信、公众号、个人微信、飞书、钉钉与嵌入页面等渠道。
第三层是代码层。这一层要看授权形态:商业版由社区版镜像与商业版镜像组成,社区版部分可以由客户修改,商业版镜像不支持修改。因此“改产品本身”的定制需求,要么落在应用层用配置与插件解决,要么由原厂评估后另行报价并写入订单与合同。
三层范围分别对应配置清单、接口联调记录和代码变更说明;验收按实际改动逐层核对。
集成面按读、写、审批分三档
同一套业务系统,接入方式按风险分三档,成本与审批要求依次上升。
读操作最低。查询库存、读取工单状态、拉取客户资料都属于这一档,通常只需要一个只读凭据与一个接口定义。风险在数据范围:接口返回的字段越多,扩散面越大,接口定义里要写明字段白名单。
写操作次之。创建工单、回填处理结论、更新客户标签属于这一档,多了一层“写错怎么办”。工程上要配幂等键与失败回滚,业务上要配确认环节:涉及业务系统写入的操作保留人工确认,不让模型直接提交正式单据。
审批操作最高。审批、驳回、撤回会改变业务状态,通常不交给 Agent 自主执行。可行的做法是 Agent 准备材料与建议,人在原系统里点确认。实施方案同时列出确认人、提交字段和返回的业务单号,便于核对每次审批的来龙去脉。
接口清单按档位登记字段、身份、失败处理与负责人,作为联调依据。
模型沿用:先清点再决定替换
客户已有算力和模型时,第一步是清点,替换放在清点之后。FastGPT 支持接入不同模型服务并可扩展。已有模型先核接口协议、输入输出与工具调用支持,满足应用要求后即可继续沿用。
清点表要分五类:语言模型、向量模型、重排模型、语音合成、语音识别。五类各自绑定不同环节,只清点语言模型会漏掉检索与语音链路的依赖。表里对每个模型记四项:服务地址、部署位置、版本、调用凭据归属。
清点完成后再决定三件事。第一件,哪些模型留在原处,哪些迁到新环境。第二件,向量模型是否随知识库一起切换,切换意味着重建索引。第三件,重排模型是否保留,它对检索结果排序影响明显,替换要单独做对比测试。
模型替换属于效果变量,不能当技术细节处理。同一批问题、同一份知识库,换模型前后各跑一轮,把命中率与引用质量记录下来,替换决策才有依据。
OA 与 ERP 的接入方式
OA 与 ERP 的差异不在技术,在治理。OA 通常已有统一身份与流程引擎,ERP 通常有严格的账号体系与操作留痕要求。接入同一个 Agent,两边的约束条件不同。
OA 侧比较顺的路径是走身份集成。专业版起支持 SSO 单点登录与 OA 系统集成,按双方身份系统配置完成登录与账号映射后进入应用,权限仍由应用内的组织架构与资源授权决定。分工要写清:SSO 负责“你是谁”,应用负责“你能看什么”。
ERP 侧通常走服务账号加接口。服务账号的权限按接口清单逐个开,能读的字段与能写的单据分开授权。这条设计与“给一个人开权限”不同,服务账号一旦泄露影响面更大,凭据轮换周期要写进运维手册。
两边都要确认调用身份。使用服务账号时,接入侧仍需记录真实业务操作人,并将其与接口请求关联;使用个人身份也要检查目标系统实际保存的字段。设计阶段确定凭据、授权与留痕方式,接口联调时验证记录能否对应到业务对象和操作人。
工具调用与 MCP 的配额边界
对话 Agent 通过支持工具调用的模型选择挂载工具并生成参数;工作流可以把工具作为明确步骤,也可以用工具调用节点动态调度。输入可来自上游变量、固定配置或模型提取,联调时应检查实际采用的参数与返回结果。
MCP 是另一条路径。它可以复用外部已有的工具服务,减少重复对接。需要提前知道的是配额:MCP 应用工具调用与外部渠道消息统一接入团队对话的每分钟请求数限制,超限会返回额度与重试等待时间,外部渠道消息去重后计数。
这条规则带来两个设计要求。第一,高频自动化流程要写退避与重试,不能假设调用一定成功。第二,压测时要把 MCP 调用与页面会话的额度合起来估,两者共享同一份额度,单独测一侧会低估峰值。
插件把能力封装为平台内复用工具,MCP 连接外部工具服务,选择依据是接口形态与维护责任。
权限:以什么身份调用决定审计质量
第一层是应用可见范围。哪些部门能用这个 Agent,在组织架构与资源授权里配。第二层是知识库与文件权限。文件级权限开关打开后,列表与详情按文件鉴权;检索还要确认是否启用当前成员身份鉴权,同一知识库不同成员看到的引用可能不同。第三层是接口凭据。凭据归哪个团队、谁能创建、怎么轮换,要在运维手册里固定。
三层里最容易漏的是第二层与第三层的交界。知识库按文件权限过滤,但接口调用用的是服务账号,服务账号可能拥有比当前用户更大的读取范围,于是“检索结果按人过滤”这条在接口链路上失效。核对动作是同一个问题分别用页面身份与接口身份跑一遍,比较返回条目。差异存在属于正常,差异没有被记录才是问题。
联调顺序与验收动作
联调顺序按依赖排,不要按人排。
第一步,模型连通。五类模型逐个调通,记录响应时间与错误码。第二步,知识库就绪。导入样本、等索引完成,确认待索引状态不会进入召回。第三步,接口连通。按读、写、审批三档逐个调通,每个接口至少跑通成功与失败两条路径。第四步,身份打通。页面身份与接口身份各跑一遍。第五步,流程串起来。从用户提问到业务系统落单,走一条完整链路。第六步,异常演练。断网、超时、返回格式异常各演练一次,记录降级表现。
联调记录按接口、模型、身份和异常路径归档,便于后续升级时复用。
联调期间有一个容易忽略的约束:工作流辅助生成属于商业版能力,生成结果是候选版本,需要使用者手动应用、检查与调试后再保存发布,并且要求应用编辑权限与管理员启用辅助生成及沙盒。把这条写进实施计划,避免把“生成”当成“上线”。
变更与版本:升级不破坏集成
集成做完不等于稳定。版本升级会带来三类变化:接口字段、工具调用行为、权限模型。
以 v4.17.3 为例,几处与集成直接相关:MCP 和外部渠道纳入团队每分钟请求数限制;成员可配置专属模型与渠道,团队所有者可替换失效的语言、语音播放和重排模型引用;通用分页参数超过 500 按 500 处理;知识库导出接口改为只导出单个知识库,开启文件级权限时只导出当前成员可读文件。
这些变化对集成脚本都有影响。升级前先做一次兼容性检查:逐个接口比对请求与响应字段,特别关注分页与导出类接口。升级后跑一遍联调清单的第一、三、四步,六步全跑属于完整回归,三步覆盖接口与身份的重点路径,完整业务回归仍按变更影响范围安排。
升级窗口还要考虑镜像约束。启用 Agent 沙盒时,主服务、Agent 沙盒与预览代理须使用配套版本,代码执行沙盒按自己的发布说明更新。把这条写进变更单,避免升了一半留下不一致的中间态。
外部工具构建的 Agent 如何接入
外部工具生成的应用,先看交付形态。若交付的是可运行服务,可以通过 HTTP 接口或 MCP 工具衔接:外部服务继续执行原有逻辑,FastGPT 在工作流中传入业务字段并接收结果。若交付的是源码项目,则先由实施方部署、开放接口,再进入联调。
接入时列明运行位置、鉴权方式、输入输出、超时与会话状态的保存方。用同一项任务验证成功返回、外部服务不可用和重复提交三种情况,写入业务系统前保留确认动作。FastGPT 工作流候选版本的生成与外部应用包的格式转换是两项工作,项目清单应分别登记。
失败表现与责任划分
常见失败表现可以归到四类,每类对应不同责任人。
接口连通失败、字段缺失、返回格式变化,属于集成方与系统运维方。检索结果与预期不符、引用质量下降,属于知识库与模型配置方。权限越界或该看到的看不到,属于权限设计方。响应慢、调用被限流,属于容量与配额规划方。
先按实际失败证据定位责任方;涉及业务中断或权限越界的情况先恢复与隔离,再安排模型与容量优化。
接口、模型、身份与异常处理各有负责人,定制 Agent 才能沿着企业已有系统持续运行。后续增加部门时,优先复用已验证的工具与流程,重新配置该部门的数据范围与凭据。
数据来源
| 主题 | 版本 | 来源 |
|---|---|---|
| 授权形态、镜像组成、模型与渠道支持、支持范围 | 当期商业方案 | FastGPT 商务咨询:授权、部署与支持范围 |
| Agent 工具选择与工作流调用方式 | 现行功能文档 | 选择工具与 Skill |
| 沙盒不混部 | v4.16.0 | self-host/upgrading/4-16/4160 |
| MCP 配额、成员级模型、分页与导出、辅助生成 | v4.17.3 | self-host/upgrading/4-17/4173 |
| HTTP 与 MCP 工具接入 | 现行功能文档 | HTTP 工具 · MCP 工具 |
| 文件级检索鉴权条件 | 现行功能文档 | 集合权限 |
| 文件级权限、发布快照 | v4.17.1 | self-host/upgrading/4-17/4171 |