Coze 智能体只能网页用Python SDK 三步接入自己的业务系统关键词Coze API、Python SDK、TokenAuth、流式对话、文件上传、智能体接入目录一、为什么要把 Coze 接入自己的系统二、Coze API 简介与调用方式三、环境安装与鉴权3.1 创建个人访问令牌3.2 三种鉴权方式对比3.3 安装 cozepy3.4 测试连通性四、对话 API 的四个核心概念五、实战上传产品手册并流式问答六、其他常用操作速查常见问题和 AI 大模型开发的关系总结一、为什么要把 Coze 接入自己的系统前面几篇都在 Coze 网页端搭工作流、配知识库、跑多模态节点。这些能力很好用但终究是在 Coze 平台内部。如果要把智能体能力真正交付给业务往往需要把它接到自己的 App、小程序、企业微信、后台系统里。Coze API 就是做这件事的它把你在平台上搭好的 Bot 和工作流暴露成标准的 HTTP 接口或 SDK让你的后端可以像调用普通服务一样调用智能体。20251204165123216.pngpos_idimg-NQohkW78-1786754782963)常见的接入场景包括在现有 App 里加一个“AI 客服”入口把 Coze 工作流嵌入企业审批、报表、运维系统用 Coze 处理用户上传的文件再把结果写回业务数据库。二、Coze API 简介与调用方式APIApplication Programming Interface本质上是一套“调用规则”。服务提供方把能力封装好外部程序按规则传参就能使用这些能力而无需关心内部实现。Coze API 提供了两种调用方式方式特点适用场景HTTP API直接发 HTTP 请求灵活但参数较多非 Python 技术栈或需要精细控制请求SDK官方封装好的 Python/JS/Java 等客户端Python 后端快速接入推荐用法上图Coze API 调用流程应用发起 HTTP POST 请求经网关验证后由工作流引擎执行最终返回 JSON 响应。对算法工程师和 Python 后端开发者来说直接使用cozepy是最省心的选择。三、环境安装与鉴权3.1 创建个人访问令牌调用 API 之前需要先在 Coze 开放平台创建一个令牌Personal Access TokenPAT。路径是API 管理 → 授权 → 添加新令牌。需要配置三项名称便于识别如“内部系统调用”过期时间个人令牌最长 30 天工作空间选择该令牌能访问的空间。创建完成后把令牌复制下来后面初始化 SDK 时会用到。3.2 三种鉴权方式对比Coze 支持三种访问令牌生产环境推荐按安全级别选择鉴权方式有效期安全性适用场景PAT个人访问令牌最长 30 天中等个人测试、教学、内部小工具SAT服务访问令牌可永久中高服务端长期运行OAuth 访问令牌短高线上生产环境、多用户授权教学阶段先用 PAT实际项目里尽量迁移到 SAT 或 OAuth。3.3 安装 cozepy先准备一个 Python 环境然后安装官方 SDKconda create-ncozepython3.12.7 conda activate coze pipinstallcozepycozepy同时支持同步和异步调用也支持 PAT、SAT、OAuth 等多种鉴权方式。3.4 测试连通性初始化客户端最简代码如下fromcozepyimportCOZE_CN_BASE_URL,Coze,TokenAuth cozeCoze(authTokenAuth(token你的 PAT 令牌),base_urlCOZE_CN_BASE_URL,)# 列出工作空间验证令牌是否生效workspacescoze.workspaces.list(user_id你的用户ID,coze_account_id你的账户ID)forwsinworkspaces:print(ws.model_dump_json(indent2))这里不要去死记每个字段重点是理解“初始化认证对象 → 创建客户端 → 调用资源方法”这套通用模式。面对任何新平台的 SDK都可以按这个思路快速上手。四、对话 API 的四个核心概念在写对话代码前先理清四个对象概念说明会话Conversation用户与智能体之间的一段连续交互包含多条消息会自动处理上下文截断消息Message用户或智能体产生的单条内容可以是文本、图片、文件等对话Chat对智能体的一次调用会触发工作流或模型执行并产生新消息上下文段落Section会话内的独立上下文单元清除上下文时会新建 Section避免历史干扰上图Coze 对话对象关系一个会话包含多个上下文段落每个段落中包含若干条消息。简单记忆会话是容器段落是分区消息是内容对话是一次调用动作。五、实战上传产品手册并流式问答下面换一个和原文不同的场景把一份产品手册 PDF 上传到 Coze让 Bot 基于文档内容回答用户问题。importosfrompathlibimportPathfromcozepyimport(COZE_CN_BASE_URL,ChatEventType,Coze,Message,MessageObjectString,TokenAuth,)# 1. 初始化客户端cozeCoze(authTokenAuth(token你的 PAT 令牌),base_urlCOZE_CN_BASE_URL,)bot_id你的机器人IDuser_id业务用户唯一标识# 2. 上传文件单文件最大 512MBfile_pathdocs/智能手表X1用户手册.pdfifnotos.path.exists(file_path):raiseFileNotFoundError(f找不到文件:{file_path})uploadedcoze.files.upload(filePath(file_path))print(f文件上传成功file_id:{uploaded.id})# 3. 构造包含文件的多模态消息additional_messages[Message.build_user_question_objects([MessageObjectString.build_file(file_iduploaded.id),])]# 4. 发起流式对话并处理事件print(----- Bot 回答 -----\n)streamcoze.chat.stream(bot_idbot_id,user_iduser_id,additional_messagesadditional_messages,)foreventinstream:ifevent.eventChatEventType.CONVERSATION_MESSAGE_DELTA:# 流式输出内容print(event.message.content,end,flushTrue)elifevent.eventChatEventType.CONVERSATION_CHAT_COMPLETED:print(\n\nToken 用量:,event.chat.usage.token_count)breakelifevent.eventChatEventType.CONVERSATION_CHAT_FAILED:print(\n对话失败:,event.chat.last_error)break这段代码的流程很清晰鉴权初始化用 TokenAuth 把 PAT 包成认证对象传给 Coze 客户端文件上传调用coze.files.upload拿到file_id构造消息用MessageObjectString.build_file把文件引用放进用户消息流式对话调用coze.chat.stream遍历事件分别处理增量内容、完成事件、失败事件。如果你的 Bot 配置了知识库或工作流这段代码同样适用上传文件后Coze 会按你预设的流水线处理。六、其他常用操作速查Coze Python SDK 的示例仓库coze-py/examples覆盖了绝大多数场景。开发时按模块找对应 demo再改参数即可模块示例文件用途授权auth_pat.py/auth_oauth_jwt.pyPAT 或 OAuth 鉴权对话chat_stream.py/chat_multimodal_stream.py流式对话、多模态对话工作流workflow_stream.py/workflow_async.py运行工作流会话conversation.py创建/管理会话与消息知识库dataset_create.py创建知识库、上传文件文件files_upload.py文件上传变量variable_retrieve.py/variable_update.py读取/设置用户变量官方仓库地址https://github.com/coze-dev/coze-py/tree/main/examples常见问题Q1个人访问令牌PAT能不能用于生产环境PAT 明文存储、有效期短适合测试和内部工具。生产环境建议用 SAT 或 OAuth尤其是涉及多用户、外部用户访问时。Q2为什么 SDK 只能看到部分机器人coze.workspaces.list返回的是当前令牌有权限的工作空间coze.chat.stream调用的 Bot 必须已经在对应空间发布为 API 服务。Q3文件上传后对话报错“文件类型不支持”检查 Bot 配置的工作流或模型是否支持文件输入。不是所有 Bot 都默认开启了文档解析能力。Q4流式输出时为什么看不到内容确认 Bot 本身开启了流式响应另外检查事件类型是否正确处理了CONVERSATION_MESSAGE_DELTA有些事件是元数据或结束标志不会携带内容。Q5遇到新 API 不会用怎么办按这套通用路径读官方文档 → 找相似 demo → 本地跑通 → 让 AI 辅助解读 → 改参数适配业务。不要硬背 API。和 AI 大模型开发的关系用 Python 直接调用大模型 API通常是下面这个样子importopenai clientopenai.OpenAI(api_key...)responseclient.chat.completions.create(modelgpt-4o,messages[{role:user,content:你好}])Coze SDK 的调用模式几乎一致只是它封装的不只是模型而是完整的 Agent# 普通大模型调用模型 → 回答coze.chat.stream(bot_id...,user_id...,additional_messages...)# Coze 调用Bot模型 工作流 知识库 插件 数据库 → 回答对于 AI 应用开发者来说Coze 的价值在于把 Prompt 工程、RAG、工具调用、多模态、工作流编排这些能力产品化而 API/SDK 则让你能把它无缝嵌入自己的业务系统。总结Coze API 是把平台上搭好的 Bot/工作流接入自有系统的关键通道Python SDKcozepy封装了鉴权、对话、文件上传、工作流等能力推荐优先使用调用前先创建令牌教学/测试用 PAT生产环境用 SAT 或 OAuth理解 Conversation、Message、Chat、Section 四个概念是写对对话代码的前提流式对话要处理MESSAGE_DELTA、CHAT_COMPLETED、CHAT_FAILED三种核心事件。掌握 API 调用之后Coze 就从“一个在线搭建工具”变成了“可被业务系统集成的智能体服务层”。#Coze#API#PythonSDK#智能体接入#流式对话