关注我，带你一起玩转AI！
大家好，我是罗康，公众号“无界生长”主理人，AI领域创业者，企业AI转型提效顾问/讲师，AI应用落地专家，拥有丰富的AI应用落地经验，交付各行各业AI应用几十个，付费学员6000+。
这是我的第 130 篇原创文章——《 0基础开发Coze智能体：第五章 插件介绍及应用 》
做了个非常艰难的决定，准备把付费课程的手册内容更新到公众号。
我认为，知识不值钱， 值钱的是 传递知识的过程。
我的愿景是在AI时代孵化1000个超级个体，影响10万人。
如果手册内容对你有所帮助，可以在文末打赏留下微信头像，经济条件允许，可以购买共创营产品，学习视频课程。
插件是扣子生态系统中非常核心的功能，也是让扣子跻身国内智能体开发平台第一梯队的关键因素。
扣子的插件可以简单理解为实现特定功能的工具包，用户可以根据自身需要，为智能体或者工作流节点添加插件，以达成预期的目标。
通过插件，我们能够非常方便的拓展大模型的能力边界，实现功能拓展。当前扣子平台的插件商店，有非常多的优质插件可用。
端侧插件依赖硬件设备，本次课程主要讲解云侧插件
云侧插件 - 基于已有服务创建
以调用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 importArgs
from 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
参数
取值
说明
Authorization
Bearer $Access\_Token
用于验证客户端身份的访问令牌。你可以在扣子平台中生成访问令牌，详细信息，参考准备工作。
Content-Type
application/json
解释请求正文的方式。
Body
参数
类型
是否必选
示例
说明
workflow\_id
String
必选
73664689170551*****
待执行的 WorkflowID，此工作流应已发布。
进入 Workflow 编排页面，在页面 URL 中，workflow 参数后的数字就是 WorkflowID。例如 https://www.coze.com/work\_flow?space\_id=42463***&workflow\_id=73505836754923***，Workflow ID 为 73505836754923***。
parameters
Map[String, Any]
可选
{
"user\_id":"12345",
"user\_name":"George"
}
工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表。
如果工作流输入参数为 Image 等类型的文件，可以调用上传文件 API 获取 file\_id，在调用此 API 时，在 parameters 中以序列化之后的 JSON 格式传入 file\_id。例如 “parameters” : { "input": "{\"file\_id\": \"xxxxx\"}" }。
bot\_id
String
可选
73428668*****
需要关联的智能体 ID。 部分工作流执行时需要指定关联的智能体，例如存在数据库节点、变量节点等节点的工作流。
进入智能体的开发页面，开发页面 URL 中 bot 参数后的数字就是智能体t ID。例如 https://www.coze.com/space/341****/bot/73428668*****，智能体 ID 为 73428668*****。
确保调用该接口使用的令牌开通了此智能体所在空间的权限。
确保该智能体已发布为 API 服务。
ext
JSONMap
可选
用于指定一些额外的字段，以 Map[String][String] 格式传入。例如某些插件 会隐式用到的经纬度等字段。
目前仅支持以下字段：
latitude：String 类型，表示经度。
longitude：String 类型，表示纬度。
user\_id：String 类型，表示用户 ID。
is\_async
Boolean
可选
true
是否异步运行。异步运行后可通过本接口返回的 execute\_id 调用查询工作流异步执行结果API 获取工作流的最终执行结果。
true：异步运行。
false：（默认）同步运行。
异步运行的参数 is\_async 仅限扣子个人进阶版、团队版、企业版和专业版使用，否则调用此接口会报错 6003Workflow execution with is\_async=true is a premium feature available only to CozeProfessional users。
app\_id
String
可选
749081945898306****
该工作流关联的应用的 ID
返回参数
参数
类型
示例
说明
code
Long
0
调用状态码。
0 表示调用成功。
其他值表示调用失败。你可以通过 msg 字段判断详细的错误原因。
msg
String
Success
状态信息。API 调用失败时可通过此字段查看详细错误信息。
data
String
工作流执行结果，通常为 JSON 序列化字符串，部分场景下可能返回非 JSON 结构的字符串。
execute\_id
String
741364789030728****
异步执行的事件 ID。
token
Long
预留字段，无需关注。
cost
String
0
预留字段，无需关注。
debug\_url
String
https://www.coze.cn/work\_flow?execute\_id=741364789030728****&space\_id=736142423532160****&workflow\_id=738958910358870****
工作流试运行调试页面。访问此页面可查看每个工作流节点的运行结果、输入输出等信息。
detail
ObjectofResponseDetail
返回的详情。
ResponseDetail
参数
类型
示例
说明
logid
String
20241210152726467C48D89D6DB2****
本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。
把生成好的代码粘贴到 Coze IDE
import requests
import json
from runtime import Args
from typings.invoke\_workflow.invoke\_workflow import Input, Output
defhandler(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：工作流参数，花名
更新输出参数
验证效果
发布插件
如何选择插件
官方插件 2. 2. 自己开发或者用知名开发者提供的插件
查看插件的数据，从调用成功率、使用人数/次数、耗时等指标考量
智能体
创建智能体
添加插件
添加两个插件进去
编写人设与回复逻辑
如果用户输入的信息中包含名称、花名、工作流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
Coze限时优惠
官方优惠渠道，关联账号享95折优惠。
点击阅读原文 或 复制下方链接：
https://tcnlyrb26udn.feishu.cn/wiki/HY7SwLA98ip82akU8Hec9sKCnmh?from=from\_copylink
如果想学习视频课程，深耕智能体赛道，可以购买文末商品链接，加入我们共创团队！
关注我，带你一起玩转AI！如果你觉得我分享的内容对你有帮助，麻烦点赞、分享、在看，你的支持是我创作的最大动力！
私人微信限时开放一天
欢迎加入我的智能体共创团队