本文介绍如何通过调用 API 与扣子编程对话并调用端插件。
扣子编程提供端插件使用的示例项目源码, 通过扣子编程 Python SDK 实现与智能体对话并调用端插件,具体请参见 agent_chat.py。
通过 OpenAPI 使用端插件需要关注以下几个请求:
|
API |
是否必须 |
API 路径 |
|---|---|---|
|
可选(可以复用以前的会话) |
||
|
必选 |
||
|
必选 |
调用创建会话 API。请求和返回示例如下:
curl --location --request POST 'https://api.coze.cn/v1/conversation/create'\
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
{
"code": 0,
"data": {
"created_at": 1742820175,
"id": "737917310581999****",
"last_section_id": "748535563872637****",
"meta_data": {
"uuid": "newid1234"
}
},
"detail": {
"logid": "20250324204255377CD0E3FBFB055ADCEE"
},
"msg": ""
}
调用发起对话 API。返回结果中, status 为 requires_action,表示已经召回了端插件。
conversation_id :创建会话返回的 ID,例如上文中的 737917310581999****。
请求和返回示例如下:
curl --location --request POST 'https://api.coze.cn/v3/chat?conversation_id=748535563872637****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
--data-raw '{
"bot_id": "75049216555930***",
"user_id": "123456789",
"stream": true,
"auto_save_history":true,
"additional_messages":[
{
"role":"user",
"content":"河南的降水概率",
"content_type":"text"
}
]
}'
// event:conversation.chat.requires_action 内容
{
"id": "743436994609809****",
"conversation_id": "743436839342099****",
"bot_id": "737916542868753****",
"created_at": 1730949143,
"completed_at": 1730949146,
"last_error": {
"code": 0,
"msg": ""
},
"status": "requires_action",
"usage": {
"token_count": 0,
"output_count": 0,
"input_count": 0
},
"required_action": {
"type": "submit_tool_outputs",
"submit_tool_outputs": {
"tool_calls": [
{
"id": "BUJJS0JKQ0dHR0VeFkNCQF5HEEZBXhJFEUJeEhFCRkESSktDREISSUI=",
"type": "function",
"function": {
"name": "get_rain_probability",
"arguments": "{\"location\":\"河南\"}"
},
"require_info": null
}
]
}
},
"section_id": "743436839342099****"
}
调用提交工具执行结果 API。关键参数说明如下:
conversation_id :创建会话 API 返回的 ID,例如上文中的 737917310581999****。chat_id :发起对话 API 返回的 ID,例如上文中的 743436994609809****。tool_call_id :发起对话 API 返回的 tool_calls.id,例如上文中的 BUJJS0JKQ0dHR0VeFkNCQF5HEEZBXhJFEUJeEhFCRkESSktDREISSUI=。请求和返回示例如下:
curl --location 'https://api.coze.cn/v3/chat/submit_tool_outputs?conversation_id=737917310581999****&chat_id=743436994609809****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
--data '{
"stream": true,
"auto_save_history": true,
"tool_outputs": [
{
"tool_call_id": "BUJJS0JKQ0dHR0VeFkNCQF5HEEZBXhJFEUJeEhFCRkESSktDREISSUI=",
"output": "{\"probability\":0.5}"
}
]
}'
event:conversation.chat.in_progress
data:{"id":"7434369946098090003","conversation_id":"7434368393420996671","bot_id":"737916542868753****","created_at":1730949143,"completed_at":1730949147,"last_error":{"code":0,"msg":""},"status":"in_progress","usage":{"token_count":0,"output_count":0,"input_count":0}}
event:conversation.message.completed
data:{"id":"7434371449395265576","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"tool_response","content":"{\"probability\":0.5}","content_type":"text","chat_id":"7434369946098090003","created_at":1730949495,"updated_at":1730949495}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"河南","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"的","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"降水","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"概率","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"为","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"5","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"0","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"$\\","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"%","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"$","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.delta
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"。","content_type":"text","chat_id":"7434369946098090003"}
event:conversation.message.completed
data:{"id":"7434371449395249192","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"answer","content":"河南的降水概率为50%。","content_type":"text","chat_id":"7434369946098090003","created_at":1730949496}
event:conversation.message.completed
data:{"id":"7434371479380312079","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"verbose","content":"{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":0,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}","content_type":"text","chat_id":"7434369946098090003","created_at":1730949498,"updated_at":1730949498}
event:conversation.message.completed
data:{"id":"7434371479380328463","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"follow_up","content":"影响河南降水概率的因素有哪些?","content_type":"text","chat_id":"7434369946098090003","created_at":1730949498,"updated_at":1730949498}
event:conversation.message.completed
data:{"id":"7434371479380344847","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"follow_up","content":"河南的降水概率和其他地区相比如何?","content_type":"text","chat_id":"7434369946098090003","created_at":1730949498,"updated_at":1730949498}
event:conversation.message.completed
data:{"id":"7434371479380377615","conversation_id":"7434368393420996671","bot_id":"737916542868753****","role":"assistant","type":"follow_up","content":"如何查询河南未来几天的降水概率?","content_type":"text","chat_id":"7434369946098090003","created_at":1730949498,"updated_at":1730949498}
event:conversation.chat.completed
data:{"id":"7434369946098090003","conversation_id":"7434368393420996671","bot_id":"737916542868753****","created_at":1730949143,"completed_at":1730949498,"last_error":{"code":0,"msg":""},"status":"completed","usage":{"token_count":140,"output_count":11,"input_count":129}}
event:done
data:"[DONE]"
通过 OpenAPI 使用端插件需要关注以下几个 API 请求。
|
API |
是否必须 |
API 路径 |
|---|---|---|
|
可选(可以复用以前的会话) |
||
|
必选 |
||
|
必选 |
||
|
必选 |
||
|
必选 |
调用 API 创建会话。请求和返回示例如下:
curl --location --request POST 'https://api.coze.cn/v1/conversation/create'\
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
{
"code": 0,
"data": {
"created_at": 1742820175,
"id": "748535563872637****",
"last_section_id": "748535563872637****",
"meta_data": {
"uuid": "newid1234"
}
},
"detail": {
"logid": "20250324204255377CD0E3FBFB055ADCEE"
},
"msg": ""
}
调用发起对话 API。
conversation_id 为创建会话返回的 ID,例如上文中的 737917310581999****。
请求和返回示例如下:
curl --location --request POST 'https://api.coze.cn/v3/chat?conversation_id=737917310581999****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
--data-raw '{
"bot_id": "7504921655593****",
"user_id": "123456789",
"stream": false,
"auto_save_history":true,
"additional_messages":[
{
"role":"user",
"content":"河南的降水概率",
"content_type":"text"
}
]
}'
{
"data": {
"id": "7434376724315504681",
"conversation_id": "743437619659664****",
"bot_id": "737916542868753****",
"created_at": 1730950722,
"last_error": {
"code": 0,
"msg": ""
},
"status": "in_progress"
},
"code": 0,
"msg": ""
}
调用查看对话详情 API。返回结果中, status 为 requires_action,表示已经召回了端插件。
curl --location 'https://api.coze.cn/v3/chat/retrieve?conversation_id=737917310581999****&chat_id=743436994609809****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****'
--header 'Content-Type: application/json' \
{
"code": 0,
"data": {
"bot_id": "737916542868753****",
"completed_at": 1730950724,
"conversation_id": "743437619659664****",
"created_at": 1730950722,
"id": "743437672431550****",
"required_action": {
"submit_tool_outputs": {
"tool_calls": [
{
"function": {
"arguments": "{\"location\":\"河南\"}",
"name": "get_rain_probability"
},
"id": "BUJJERJDFxISEEFeS0pEQF5HFUZBXkpASkdeQEVAEhFGEkASFRdFSUI=",
"require_info": {},
"type": "function"
}
]
},
"type": "submit_tool_outputs"
},
"status": "requires_action"
},
"msg": ""
}
调用提交工具执行结果 API。关键参数说明如下:
conversation_id :创建会话 API 返回的 ID,例如上文中的 737917310581999****。chat_id :发起对话 API 返回的 ID,例如上文中的 743436994609809****。tool_call_id :查看对话详情 API 返回的 tool_calls.id,例如上文中的 BUJJS0JKQ0dHR0VeFkNCQF5HEEZBXhJFEUJeEhFCRkESSktDREISSUI=。请求和返回示例如下:
curl --location 'https://api.coze.cn/v3/chat/submit_tool_outputs?conversation_id=737917310581999****&chat_id=743436994609809****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****' \
--header 'Content-Type: application/json' \
--data '{
"stream": false,
"auto_save_history": true,
"tool_outputs": [
{
"tool_call_id": "BUJJERJDFxISEEFeS0pEQF5HFUZBXkpASkdeQEVAEhFGEkASFRdFSUI=",
"output": "{\"probability\":0.5}"
}
]
}'
{
"data": {
"id": "7434376724315504681",
"conversation_id": "743437619659664****",
"bot_id": "737916542868753****",
"created_at": 1730950722,
"completed_at": 1730950724,
"last_error": {
"code": 0,
"msg": ""
},
"status": "in_progress"
},
"code": 0,
"msg": ""
}
调用查看对话消息详情 API。关键参数说明如下:
conversation_id :创建会话 API 返回的 ID,例如上文中的 737917310581999****。chat_id :发起对话 API 返回的 ID,例如上文中的 743436994609809****。curl --location 'https://api.coze.cn/v3/chat/message/list?conversation_id=737917310581999****&chat_id=743436994609809****' \
--header 'Authorization: Bearer pat_xitq9LWlowpX3qGCih1lwpAdzvXNqgmpfhpV28HLWFypY37xR5Uaj2GioN****'
--header 'Content-Type: application/json' \
{
"code": 0,
"data": [
{
"bot_id": "737916542868753****",
"chat_id": "743437672431550****",
"content": "{\"name\":\"ts-weather_assistant-get_rain_probability\",\"arguments\":{\"location\":\"河南\"},\"plugin_id\":7374787648269074486,\"plugin_name\":\"weather_assistant\",\"api_id\":7375048893094101003,\"api_name\":\"get_rain_probability\",\"plugin_type\":6,\"thought\":\"需求为查询河南的降水概率,需要调用ts-weather_assistant-get_rain_probability工具进行查询\"}",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730950724,
"id": "743437673455807****",
"role": "assistant",
"type": "function_call",
"updated_at": 1730950723
},
{
"bot_id": "7379165428687536****",
"chat_id": "743437672431550****",
"content": "{\"msg_type\":\"interrupt\",\"data\":\"\",\"from_module\":null,\"from_unit\":null}",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730950724,
"id": "7434376734558109****",
"role": "assistant",
"type": "verbose",
"updated_at": 1730950724
},
{
"bot_id": "737916542868753****",
"chat_id": "74343767243155****",
"content": "{\"probability\":0.5}",
"content_type": "text",
"conversation_id": "7434376196596****",
"created_at": 1730951153,
"id": "7434378579980419111",
"role": "assistant",
"type": "tool_response",
"updated_at": 1730951152
},
{
"bot_id": "737916542868753****",
"chat_id": "743437672431****",
"content": "河南的降水概率为50$\\%$。",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730951152,
"id": "74343785799803****",
"role": "assistant",
"type": "answer",
"updated_at": 1730951153
},
{
"bot_id": "737916542868753****",
"chat_id": "74343767243155****",
"content": "{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":1,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730950724,
"id": "74343767345581****",
"role": "assistant",
"type": "verbose",
"updated_at": 1730950724
},
{
"bot_id": "737916542868753****",
"chat_id": "7434376724315504681",
"content": "{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":0,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730951156,
"id": "743437859164078****",
"role": "assistant",
"type": "verbose",
"updated_at": 1730951156
},
{
"bot_id": "737916542868753****",
"chat_id": "7434376724315504681",
"content": "降水概率的具体含义是什么?",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730951156,
"id": "74343785916407****",
"role": "assistant",
"type": "follow_up",
"updated_at": 1730951156
},
{
"bot_id": "737916542868753****",
"chat_id": "743437672431550****",
"content": "如何根据降水概率来安排户外活动?",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730951156,
"id": "743437859505464****",
"role": "assistant",
"type": "follow_up",
"updated_at": 1730951156
},
{
"bot_id": "737916542868753****",
"chat_id": "7434376724315504681",
"content": "降水概率的大小对农作物的生长有什么影响?",
"content_type": "text",
"conversation_id": "743437619659664****",
"created_at": 1730951156,
"id": "743437859505466****",
"role": "assistant",
"type": "follow_up",
"updated_at": 1730951156
}
],
"msg": ""
}
默认情况下,通过上传文件 API 上传本地文件仅返回文件 ID,在触发了端插件的对话中,提交端插件工具执行结果时,也仅支持将该文件 ID 返回给大模型,而大模型并无法直接理解文件 ID。为了使 提交工具执行结果 API 能够返回大模型可理解的文件 URL, 你可参考本步骤完成相关配置。
在端插件编辑工具页面的配置输入参数区域,添加 file 类型的输入参数,支持上传 File(通用文件)、Image(图片)、Doc(文档) 和 Code(代码文件)等文件,详细类型请参考支持的文件格式。
通过上传文件 API 上传文件到扣子编程,并在返回结果中获取文件 ID(id)。
curl -X POST 'https://api.coze.cn/v1/files/upload' \
-H "Authorization: Bearer pat_iQhcxIIxJiKxU0OaM8sLFH7MSNZKgNW6qLoAhC9XP1oOqjIuqREhzRoMjDP2****" \
-H "Content-Type: multipart/form-data"
--form 'file=@"1120.png"'
{
"code": 0,
"data": {
"bytes": 152236,
"created_at": 1715847583,
"file_name": "1120.png",
"id": "736949598110202****"
},
"msg": ""
}
当你通过 发起对话 API 与绑定了端插件的智能体对话时,如果对话触发了端插件请求本地文件,那么你可以在提交工具执行结果API 中定义output 为文件 ID, 提交工具执行结果 API 会将此文件 ID 转换为可访问的文件 URL,并返回给大模型。
提交工具执行结果 API 请求示例和返回示例如下,其中示例中的 output 为你在步骤二:上传文件中上传的文件 ID。
curl -X POST 'https://api.coze.cn/v3/chat/submit_tool_outputs?conversation_id=747295135519236****&chat_id=747303250529034****' \
-H "Authorization: Bearer pat_iQhcxIIxJiKxU0OaM8sLFH7MSNZKgNW6qLoAhC9XP1oOqjIuqREhzRoMjDP2****" \
-H "Content-Type: application/json" \
-d '{
"stream": false,
"tool_outputs": [
{
"output": "{\"image\": \"736949598110202****\"}",
"tool_call_id": "BUJJREUSERBBRUVeRBcXSl5HRhUVXkpFERdeFUBCRBUSEERGFhJ****"
}
]
}'
{
"id": "747524211921775****",
"conversation_id": "747295135519236****",
"bot_id": "746967919656768****",
"role": "assistant",
"type": "answer",
"content": "为你获取到一张图片:[点击查看](https://****.png)",
"content_type": "text",
"chat_id": "747303250529034****",
"created_at": 1740465986
}
在触发了端插件的对话中,如果涉及请求云端文件,你可参考本步骤完成相关配置。
在端插件编辑工具页面的配置输入参数区域,添加一个 File 类型或 String 类型的输入参数。两种类型均支持直接使用文件 URL。
当你通过 发起对话 API 与绑定了端插件的智能体对话时,如果对话触发了端插件请求云端文件,那么你可以在提交工具执行结果API 中定义output 为文件 URL, 提交工具执行结果 API 会将此文件 URL 返回给大模型。
提交工具执行结果 API 请求示例和返回示例如下:
curl -X POST 'https://api.coze.cn/v3/chat/submit_tool_outputs?conversation_id=747295135519236****&chat_id=747303250529034****' \
-H "Authorization: Bearer pat_iQhcxIIxJiKxU0OaM8sLFH7MSNZKgNW6qLoAhC9XP1oOqjIuqREhzRoMjDP2****" \
-H "Content-Type: application/json" \
-d '{
"stream": false,
"tool_outputs": [
{
"output": "{\"image\": \"https://****.png\"}",
"tool_call_id": "BUJJREUSERBBRUVeRBcXSl5HRhUVXkpFERdeFUBCRBUSEERGFhJ****"
}
]
}'
{
"id": "747524211921775****",
"conversation_id": "747295135519236****",
"bot_id": "746967919656768****",
"role": "assistant",
"type": "answer",
"content": "为你获取到一张图片:[点击查看](https://****.png)",
"content_type": "text",
"chat_id": "747303250529034****",
"created_at": 1740465986
}