夜雨聆风
0基础开发Coze智能体:第五章 插件介绍及应用
插件概述
插件是扣子生态系统中非常核心的功能，也是让扣子跻身国内智能体开发平台第一梯队的关键因素。 扣子的插件可以简单理解为实现特定功能的工具包，用户可以根据自身需要，为智能体或者工作流节点添加插件，以达成预期的目标。
通过插件，我们能够非常方便的拓展大模型的能力边界，实现功能拓展。当前扣子平台的插件商店，有非常多的优质插件可用。
创建插件
端侧插件依赖硬件设备，本次课程主要讲解云侧插件
云侧插件 – 基于已有服务创建
以调用coze工作流为例，首先在 https://www.coze.cn/open/oauth/pats 创建令牌
为了方便理解，我这里使用个人访问令牌做演示，有效期最长为30天，如果你希望能长期使用，建议你采用服务访问令牌或OAuth 访问令牌。
具体内容说明，参考：https://www.coze.cn/open/docs/developer_guides/preparation
生成的令牌仅在创建成功后展示一次，记得复制并保存。如果不小心忘记了，新建一个令牌。
新建插件
配置插件头像、名称、描述、创建方式、插件URL、Header列表和授权方式。
创建工具
配置基本信息
填写工具名称、描述、路径、请求方法、配置输入参数和输出参数等，根据实际情况填写。
测试插件
参考API文档，把相关参数填入，试运行插件
更新输出参数
点击编辑按钮，选择“自动解析”
填写插件相关参数
保存自动解析的输出参数
验证效果
查看数据是否正常写入
发布插件
执行工作流的API文档：https://www.coze.cn/open/docs/developer_guides/workflow_run
云侧插件 – 在 Coze IDE 中创建
新建插件
配置插件头像、名称、描述、创建方式和代码运行环境
创建工具
填写工具名称和介绍
默认页面
还是以调用工作流为例，通过http请求调用api 安装依赖包，输入 requests ，安装
编写代码
定义插件的输入参数，编写插件代码
这里直接让大模型帮我们写代码
我需要开发扣子插件调用工作流，工作流输入参数为name 和 nickname，输出参数为output。插件输入参数为access_token、workflow_id、name 和 nickname参考下方资料，帮忙编写插件代码。## 插件示例代码from runtime importArgsfrom typings.invoke_workflow.invoke_workflowimportInput, Output"""Each file needs to export a function named `handler`. This function is the entrance to the Tool.Parameters:args: parameters of the entry function.args.input - input parameters, you can get test input value by args.input.xxx.args.logger - logger instance used to print logs, injected by runtime.Remember to fill in input/output in Metadata, it helps LLM to recognize and use tool.Return:The return data of the function, which should match the declared output parameters."""def handler(args: Args[Input])->Output: return {"message": "Hello, world!"}## 调用工作流的api文档基础信息请求方式POST请求地址https://api.coze.cn/v1/workflow/run权限run确保调用该接口使用的个人令牌开通了 run 权限，详细信息参考鉴权方式。接口说明执行已发布的工作流。请求参数Header参数取值说明AuthorizationBearer $Access_Token用于验证客户端身份的访问令牌。你可以在扣子平台中生成访问令牌，详细信息，参考准备工作。Content-Typeapplication/json解释请求正文的方式。Body参数类型是否必选示例说明workflow_idString必选73664689170551*****待执行的 WorkflowID，此工作流应已发布。进入 Workflow 编排页面，在页面 URL 中，workflow 参数后的数字就是 WorkflowID。例如 https://www.coze.com/work_flow?space_id=42463***&workflow_id=73505836754923***，Workflow ID 为 73505836754923***。parametersMap[String, Any]可选{"user_id":"12345","user_name":"George"}工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表。如果工作流输入参数为 Image 等类型的文件，可以调用上传文件 API 获取 file_id，在调用此 API 时，在 parameters 中以序列化之后的 JSON 格式传入 file_id。例如 “parameters” : { "input": "{\"file_id\": \"xxxxx\"}" }。bot_idString可选73428668*****需要关联的智能体 ID。 部分工作流执行时需要指定关联的智能体，例如存在数据库节点、变量节点等节点的工作流。进入智能体的开发页面，开发页面 URL 中 bot 参数后的数字就是智能体t ID。例如 https://www.coze.com/space/341****/bot/73428668*****，智能体 ID 为 73428668*****。确保调用该接口使用的令牌开通了此智能体所在空间的权限。确保该智能体已发布为 API 服务。extJSONMap可选用于指定一些额外的字段，以 Map[String][String] 格式传入。例如某些插件 会隐式用到的经纬度等字段。目前仅支持以下字段：latitude：String 类型，表示经度。longitude：String 类型，表示纬度。user_id：String 类型，表示用户 ID。is_asyncBoolean可选true是否异步运行。异步运行后可通过本接口返回的 execute_id 调用查询工作流异步执行结果API 获取工作流的最终执行结果。true：异步运行。false：（默认）同步运行。异步运行的参数 is_async 仅限扣子个人进阶版、团队版、企业版和专业版使用，否则调用此接口会报错 6003Workflow execution with is_async=true is a premium feature available only to CozeProfessional users。app_idString可选749081945898306****该工作流关联的应用的 ID返回参数参数类型示例说明codeLong0调用状态码。0 表示调用成功。其他值表示调用失败。你可以通过 msg 字段判断详细的错误原因。msgStringSuccess状态信息。API 调用失败时可通过此字段查看详细错误信息。dataString工作流执行结果，通常为 JSON 序列化字符串，部分场景下可能返回非 JSON 结构的字符串。execute_idString741364789030728****异步执行的事件 ID。tokenLong预留字段，无需关注。costString0预留字段，无需关注。debug_urlStringhttps://www.coze.cn/work_flow?execute_id=741364789030728****&space_id=736142423532160****&workflow_id=738958910358870****工作流试运行调试页面。访问此页面可查看每个工作流节点的运行结果、输入输出等信息。detailObjectofResponseDetail返回的详情。ResponseDetail参数类型示例说明logidString20241210152726467C48D89D6DB2****本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。
把生成好的代码粘贴到 Coze IDE
import requestsimport jsonfrom runtime import Argsfrom typings.invoke_workflow.invoke_workflow import Input, Outputdefhandler(args: Args[Input]) -> Output: # 获取所有输入参数 name = args.input.name nickname = args.input.nickname access_token = args.input.access_token workflow_id = args.input.workflow_id # 验证必填参数 ifnotall([name, nickname, access_token, workflow_id]): raise ValueError("所有输入参数(name, nickname, access_token, workflow_id)都是必填项") # 构造API请求 url = "https://api.coze.cn/v1/workflow/run" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json" } payload = { "workflow_id": workflow_id, "parameters": { "name": name, "nickname": nickname } } try: # 发送API请求 response = requests.post(url, headers=headers, json=payload, timeout=30) response.raise_for_status() result = response.json() # 检查API响应状态 if result.get("code") != 0: error_msg = result.get("msg", "未知错误") args.logger.error(f"工作流执行失败: {error_msg} | 响应: {result}") raise RuntimeError(f"工作流执行失败: {error_msg}") # 解析工作流输出 output_data = json.loads(result["data"]) return {"output": output_data} except requests.exceptions.RequestException as e: args.logger.error(f"API请求异常: {str(e)}") raise RuntimeError(f"网络请求失败: {str(e)}") except json.JSONDecodeError as e: args.logger.error(f"API响应解析失败: {response.text}") raise RuntimeError("工作流响应格式错误") except Exception as e: args.logger.error(f"未处理的异常: {str(e)}") raise RuntimeError(f"插件执行出错: {str(e)}")
测试代码
●access_token：填写访问令牌 ●workflow_id：通过工作流页面获取
●name：工作流参数，名称 ●nickname：工作流参数，花名
更新输出参数
验证效果
发布插件
使用插件
如何选择插件
.1. 官方插件
.2. 自己开发或者用知名开发者提供的插件
.3. 查看插件的数据，从调用成功率、使用人数/次数、耗时等指标考量
智能体
创建智能体
添加插件
添加两个插件进去
编写人设与回复逻辑
如果用户输入的信息中包含名称、花名、工作流ID、访问令牌，提取对应的内容，调用工作流{#LibraryBlock id="7530257856889831424" uuid="Ns3MXac_Pc1e3N64XCD4E"type="plugin" apiId="7530258448685187087"#}invoke_workflow{#/LibraryBlock#}。如果用户输入的信息中包含工作流参数、工作流ID、解释请求正文的方式、认证类型，调用工作流{#LibraryBlock id="7530261097295888434" uuid="Cwi24m7LDTV2sT0XS1pSU"type="plugin" apiId="7530261346399780873"#}invoke_workflow{#/LibraryBlock#}。
调试智能体
工作流
创建工作流
添加插件
维护插件
编辑插件
复制插件
删除插件
其他高级功能
更多内容参考：https://www.coze.cn/open/docs/guides/plugin_version
插件常见问题
更多内容参考：https://www.coze.cn/open/docs/guides/plugin_faq
