[智能体-503]： Step3「让 Bot 做事」Coze智能体如何调用插件的

Coze 智能体完整调用插件全流程详解

一、底层基础前提

Coze 插件本质是可视化封装的 Function Call（函数调用），分为云端插件 / 端插件 / MCP 三类，但核心调度逻辑统一：大模型读取插件描述自主判断是否调用，由对应执行载体完成接口请求。 整体链路对应 Bot 搭建 Step3「让 Bot 做事」，依赖 Step1 提示词工程完成调度规则约束。

二、标准完整调用步骤（云端插件，最通用）

步骤 1：插件配置绑定（事前静态配置）

1. 在 Coze 后台创建 / 添加插件（官方 / 第三方 / 自定义云端插件）；
2. 录入接口地址、请求方法、入参、鉴权密钥、功能描述（核心：插件描述文本）；
3. 将插件绑定到目标 Bot，平台自动把插件的函数定义、描述写入 Bot 的全局工具列表。

步骤 2：会话初始化，插件描述注入提示词

用户发起对话时，Coze 后端自动执行：

1. 加载 Bot 系统提示词（预设调度规则：什么场景调用什么插件）；
2. 把所有绑定插件的功能描述、参数结构拼接进上下文，下发给 LLM；
3. LLM 读取全部插件能力说明，建立 “需求 - 插件” 匹配认知。

步骤 3：用户输入问题，LLM 意图判断

用户发送提问（user_id+conversation_id + 文本 query）传入 LLM，模型执行逻辑判断：

1. 解析用户真实需求；
2. 匹配插件描述：判断是否需要调用外部 API 获取数据；
   • 无需插件：直接生成纯文本回答，流程结束；
   • 需要插件：输出结构化 Function Call 指令（插件标识、请求参数 JSON）。

步骤 4：Coze 云端网关执行插件 API 调用

1. Coze 服务解析模型返回的结构化调用指令；
2. 携带后台预存的鉴权密钥，向插件对应的外部公网 API 发起网络请求；
3. 接收第三方接口返回原始业务数据（如天气、订单、搜索结果）。

步骤 5：工具结果回传给大模型二次生成

1. 将「原始用户提问 + 插件返回的真实数据」重新封装为完整 Prompt 送入 LLM；
2. LLM 结合工具返回的客观数据，按照系统提示词的输出规范，生成通顺、有据可依的自然语言答复。

步骤 6：结果返回给调用端

完整回答逐层下发：Coze 后端 → 网页前端 / OpenAPI / Python SDK 客户端，同时在 SSE 流中透出tool_call、tool_output事件。

三、端插件调用流程差异

端插件不在 Coze 云端执行，核心变化在步骤 4：

1. LLM 依旧生成插件调用指令，下发给前端 / 客户端；
2. 本地客户端（浏览器 / APP）解析指令，在终端本地发起 API / 本地脚本调用；
3. 本地执行完成后，把结果回传给 Coze 云端 LLM，再统一生成最终回答； 优势：可访问本地文件、内网本地服务，接口流量不经过 Coze 云端。

四、MCP 插件调用流程差异

MCP 基于开放标准协议，独立服务部署：

1. Coze 通过 MCP 协议地址对接独立 MCP Server，加载 MCP 内全部工具描述；
2. LLM 生成调用指令后，Coze 云端通过标准化 MCP 协议向独立 MCP 服务发起请求；
3. MCP 服务完成工具执行后回传数据，再交由 LLM 整合生成回答； 优势：一套 MCP 服务可同时对接 Coze、Cursor、Claude 等多款 AI 产品，跨平台复用工具。

五、多轮连续插件调用场景（工作流联动）

若业务需要连续调用多个插件（例如：先查定位→再查当地天气→再推荐穿搭）：

1. 单次插件返回数据不足以回答问题时，LLM 会再次生成第二条 Function Call 指令；
2. 循环执行「调用插件→拿回数据→判断是否继续调用」；
3. 也可通过 Step4 工作流编排，可视化固定多插件执行顺序，强制按预设流程调用，无需模型自主判断。

六、结合 OpenAPI/SDK 调用的补充说明

外部通过 curl、Python SDK 访问 Bot 时，插件调用逻辑完全在 Coze 后端闭环，调用方无感知：

1. 客户端仅传入bot_id、user_id、用户提问文本；
2. 插件匹配、接口请求、数据回传全部由 Coze 云端自动完成；
3. SDK/SSE 流仅能收到tool_call、tool_output事件，无法干预底层插件接口执行逻辑。

七、核心关键影响因素

1. 插件描述质量：描述越清晰，LLM 越能精准匹配需求、正确填充参数，减少调用失败；
2. 系统提示词规则：可强制约束 “某类问题必须调用指定插件”，避免模型跳过工具直接编造答案；
3. 接口可用性：插件对应外部 API 超时、鉴权失效会导致工具调用失败，模型会输出兜底回复。