扣子怎么把智能体发布成 API 给外部调用
智能体在扣子里调好了,想让自己的网站或小程序调用。走 API 渠道发布拿凭证,这篇讲发布流程、会话怎么续、令牌怎么保管。
在扣子里把智能体调通之后,下一步往往是接到自己的产品里:网站右下角的客服、小程序里的问答、内部系统的一个按钮。做法是按 API 渠道发布,拿到调用凭证,再用对话接口把用户消息发过去。难点不在接口本身,在会话隔离和凭证保管。
入口在哪
- 智能体编排页面上有发布入口,点开是渠道列表,里面有 API 这一项,位置随版本略有差别。
- 调用凭证在个人设置或工作空间设置里创建,属于账号级,不跟着单个智能体走。
- 国内版和国际版是两套站点,渠道和域名不同,以控制台里给出的接口地址为准。
具体步骤
- 先把智能体调好:提示词、开场白、知识库都确认过再发布。改了之后要重新发布才对外生效。
- 在发布渠道里选中 API 并完成发布,记下这个智能体的标识。
- 创建访问令牌。创建时通常只完整显示一次,立刻存进服务端的环境变量。
- 用对话接口发请求,带上智能体标识、用户标识和消息内容。是否流式由参数控制,前端展示用流式更好;流式是逐段推送的,客户端要边收边渲染,别等全部结束再显示。
- 保存返回的会话标识,同一用户下一轮带上它才能接着上文聊。
- 在服务端做一层转发,前端只调你自己的接口,令牌永远不出服务端。
几个坑
- 用户标识乱传。全都传同一个值,几个人的会话会串在一起;每人一个稳定值才隔离得开。
- 令牌写进前端代码。浏览器里能直接看到,等于公开。必须放在服务端,转发时再带上。
- 流式返回没按分块解析,前端收到的是一堆拼在一起的半截 JSON,得按行或按事件拆。
- 改了智能体没重新发布,线上还是旧版本,排查半天以为是接口问题。
怎么验证
先用一条固定消息打通链路,看返回状态码和内容是否正常。再发第二轮,带上会话标识,看它能不能接上文。换一个用户标识发同样的问题,两边的上下文应该互不影响。最后在控制台看调用记录和额度消耗,确认请求真的落到了这个智能体上。
常见问题
接口能通但回答和调试时不一样
常见原因是线上版本没更新,或者请求没带会话标识导致每轮都是新会话。确认已重新发布,并检查会话标识有没有正确回传。
能不能不经过自己的服务器直接调
技术上可以,但令牌会暴露在前端,任何人都能拿去用并消耗你的额度。除非是纯内部工具且网络隔离,否则不建议。
会话标识什么时候该换
一个用户一个长期会话可以,但话题切换时最好新开一个,否则上下文越积越长,回答会被前面的内容带偏。
一句话总结:发布到 API 渠道拿令牌,令牌只放服务端,用户标识和会话标识分开管,改完智能体记得重新发布。