开篇介绍：

hello 大家，本篇博客又是一个比较轻松的内容，哈哈，那么在本篇博客中，我们就来学习一下Coze—AI中的SDK。

一、先搞懂：为什么 SDK 是新手的 “救命稻草”？

在正式讲 Coze SDK 之前，我们先解决一个核心问题：既然已经有 API 了，为什么还要学 SDK？

1.1 什么是 SDK？（麻婆豆腐式通俗解释）

SDK（Software Development Kit，软件开发工具包），本质是平台方为开发者准备的 “一站式懒人工具包”：

场景API（应用程序接口）SDK（软件开发工具包）
类比麻婆豆腐的 “详细菜谱”麻婆豆腐的 “预制料理包”
你需要做的事1. 自己买豆腐、牛肉末、豆瓣酱等所有原料；2. 自己切豆腐、剁豆豉、焙香花椒并磨粉；3. 严格按步骤控制火候、勾芡次数；4. 全程自己处理 “炒糊了”“味道淡了” 等问题1. 打开料理包，里面有切好焯水的豆腐、配好比例的酱料；2. 按 3 步简单操作（热锅倒油→炒酱料→煮豆腐）；3. 无需关心调料比例、火候控制，料理包已优化；4. 几乎零失败，新手也能做出大师级味道
对应开发场景1. 自己写 HTTP 请求代码；2. 手动配置请求头（Authorization/Content-Type）；3. 自己解析 JSON 响应、处理异常；4. 反复调试参数格式、令牌权限1. 导入 SDK 库，调用现成函数；2. 无需关心请求头、URL 拼接；3. SDK 自动解析响应、封装异常；4. 一行代码调用智能体聊天、工作流执行

简单说：API 是 “原材料 + 说明书”，需要你全程手动操作；SDK 是 “半成品 + 简易指南”，把最复杂的环节都封装好了，你只需要关注核心逻辑。

1.2 Coze API vs Coze SDK：新手该选谁？

我用表格对比一下两者的核心差异，看完就知道为什么 SDK 是首选：

对比维度Coze APICoze SDK（cozepy）
代码量调用一次聊天需要写 30 + 行代码（请求头、参数、响应解析）调用一次聊天只需 5-10 行代码（导入库→初始化→调函数）
学习成本需要懂 HTTP 请求、JSON 解析、异常处理只需懂 Python 基础语法，会调用函数即可
出错概率高（容易漏写 Bearer、参数格式错误、响应解析出错）低（SDK 封装了所有格式校验，只传核心参数）
维护成本高（换功能要重写请求逻辑）低（换功能只需调用不同的 SDK 函数）
新手友好度极低（全是细节坑）极高（开箱即用，无需关注底层）

1.3 Coze SDK 能做什么？

Coze Python SDK（cozepy）几乎封装了 Coze 平台的所有核心能力，你能想到的操作，SDK 都能一键实现：

  • 工作空间管理：查看 / 获取工作空间列表、详情
  • 智能体管理：查看智能体列表、获取智能体配置、修改智能体基本信息
  • 会话交互：和智能体聊天（同步 / 流式）、查看会话记录、统计 Token 消耗
  • 工作流管理：执行自定义工作流、查看工作流列表、获取工作流详情
  • 其他能力：消息管理、文件上传、权限控制等

总结：如果你是新手，直接学 SDK 就够了；API 适合需要极致定制化的资深开发者。

二、前置准备：0 基础也能搞定的环境搭建

要使用 Coze Python SDK，首先得搭好 Python 开发环境 —— 这一步看似简单，但新手很容易踩坑，我会拆成 “傻瓜式步骤”，跟着做就行。

2.1 Python 安装：从下载到验证（Windows/macOS 通用）

Python 是 Coze SDK 的运行基础，我们选 Python 3.8 及以上版本（兼容 cozepy 所有功能）。

2.1.1 Windows 系统安装步骤
  1. 打开 Python 官网：https://www.python.org/downloads/
  2. 点击 “Download Python 3.11.x”（选 3.11 版本，稳定且兼容）；
  3. 下载完成后，双击安装包，务必勾选 “Add Python 3.11 to PATH”（这是最关键的一步，避免后续配置环境变量）；
  4. 点击 “Install Now”，等待安装完成；
  5. 验证是否安装成功：
    • 按下 Win+R，输入 “cmd” 打开命令提示符；
    • 输入python --version（如果提示 “不是内部命令”，换成python3 --version）；
    • 若显示 “Python 3.11.x”，说明安装成功。
2.1.2 macOS 系统安装步骤
  1. 方法 1（推荐）：用 Homebrew 安装（先打开终端，输入/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装 Homebrew）；
  2. 终端输入brew install python@3.11；
  3. 验证：终端输入python3 --version，显示版本号即成功。
2.1.3 新手避坑：Python 和 pip 的环境问题
  • 问题 1：输入python没反应，只有python3能用？解决方案：后续所有命令把python换成python3，pip换成pip3即可。
  • 问题 2：pip 安装包提示 “权限不足”？解决方案：Windows 加--user（如pip install --user cozepy）；macOS 加sudo（如sudo pip3 install cozepy）。

2.2 PyCharm 安装：免费社区版就够用

PyCharm 是最适合新手的 Python 编辑器，自带代码提示、环境管理，比记事本 / VS Code 更友好。

  1. 打开 PyCharm 官网社区版下载页：https://www.jetbrains.com/pycharm/download/#section=windows
  2. 选择对应系统（Windows/macOS/Linux）下载；
  3. 安装步骤：
    • Windows：双击安装包，一路 “Next”，勾选 “Create Desktop Shortcut”（创建桌面快捷方式）；
    • macOS：解压后拖到 “应用程序” 文件夹；
  4. 首次打开 PyCharm：
    • 选择 “New Project”，新建一个项目；
    • 项目名称填 “CozeSDK_Demo”，解释器选择刚才安装的 Python 3.11；
    • 点击 “Create”，等待项目初始化完成。

2.3 环境验证：确保基础工具能用

在 PyCharm 中打开 “Terminal”（底部菜单栏），输入以下命令，验证 Python 和 pip 是否正常：

# 验证Python版本
python --version  # Windows
# 或
python3 --version  # macOS/Linux

# 验证pip版本
pip --version  # Windows
# 或
pip3 --version  # macOS/Linux

只要能显示版本号，说明环境没问题。

三、Coze SDK 核心安装与配置：3 步搞定

环境搭好后，我们开始安装 Coze SDK 并完成核心配置 —— 这是调用 SDK 的前提

3.1 第一步：安装 cozepy（Coze 官方 Python SDK）

cozepy 是 Coze 官方维护的 Python SDK，一行命令就能安装：

# Windows系统
pip install cozepy

# macOS/Linux系统
pip3 install cozepy

# 若安装速度慢，换国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple cozepy
验证安装是否成功

在 PyCharm 的 Terminal 中输入：

python -c "import cozepy; print('cozepy安装成功')"

如果输出 “cozepy 安装成功”，说明安装没问题；若提示 “ModuleNotFoundError”，则重新执行安装命令。

3.2 第二步：安装敏感信息保护工具（python-dotenv）

新手最容易犯的错：把 Coze 令牌直接写在代码里（比如api_token = "pat_xxxx"），一旦代码泄露，别人就能随意操作你的 Coze 账号。

我们用python-dotenv来管理敏感信息（比如令牌），把令牌存在独立的.env文件里，代码里只读取变量，不硬编码。

安装命令：

# Windows
pip install python-dotenv

# macOS/Linux
pip3 install python-dotenv

3.3 第三步：获取 Coze 个人访问令牌（PAT）

SDK 的所有调用都需要令牌（相当于 “登录密码”），新手优先用个人访问令牌（PAT），步骤如下：

  1. 打开 Coze 令牌管理页面：https://www.coze.cn/open/oauth/pats（先登录你的 Coze 账号）；
  2. 点击 “添加” 按钮，填写令牌信息：
    • 令牌名称：随便填（比如 “CozeSDK 测试令牌”）；
    • 过期时间：选 7 天（短期更安全，测试用）；
    • 权限：全勾选（测试阶段不用纠结，正式环境按需勾选）；
    • 访问工作空间：勾选你要操作的工作空间；
  3. 点击 “生成”，此时会弹出一串以pat_开头的字符（比如pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB）；
  4. 立刻复制并保存！这个令牌只显示一次，丢了就找不回来了。

3.4 第四步：配置.env 文件（保护令牌）

在 PyCharm 的项目根目录下，新建一个名为.env的文件（注意开头有个点），步骤：

  1. 右键项目根目录→New→File；
  2. 文件名输入.env（Windows 用户注意：如果提示 “必须输入文件名”，先输入env，创建后重命名为.env，并关闭文件扩展名隐藏）；
  3. 在.env文件中写入：
# Coze API令牌（替换成你自己的PAT）
COZE_API_TOKEN=pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB

至此，Coze SDK 的安装和配置就完成了 —— 接下来我们进入实战环节，用 SDK 调用 Coze 的核心功能。

四、Coze SDK 核心功能实战：从简单到复杂

4.1 基础功能：查看工作空间列表（验证 SDK 是否配置成功）

工作空间是 Coze 的核心组织单元，所有智能体、工作流都归属于某个工作空间。我们先调用 SDK 查看工作空间列表，验证令牌和配置是否正确。

4.1.1 完整代码示例
# 1. 导入必要的库
import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

# 2. 加载.env文件中的环境变量（读取令牌）
load_dotenv()  # 会自动读取项目根目录的.env文件

# 3. 定义函数：获取工作空间列表
def get_coze_workspaces():
    """
    调用Coze SDK获取工作空间列表
    """
    # 从环境变量中读取令牌（避免硬编码）
    api_token = os.environ.get("COZE_API_TOKEN")
    
    # 校验令牌是否存在
    if not api_token:
        print("❌ 错误：未找到Coze令牌，请检查.env文件是否配置正确")
        return
    
    try:
        # 4. 初始化Coze客户端（核心步骤）
        coze_client = Coze(
            auth=TokenAuth(token=api_token),  # 传入令牌认证
            base_url=COZE_CN_BASE_URL         # 指定国内版Coze的域名（固定值）
        )
        
        # 5. 调用SDK函数获取工作空间列表
        workspaces = coze_client.workspaces.list()
        
        # 6. 处理返回结果（新手友好的格式化输出）
        print("✅ 成功获取工作空间列表：")
        print("-" * 60)
        # 判断返回结果是否有items属性（SDK返回的是分页对象）
        if hasattr(workspaces, "items"):
            for idx, ws in enumerate(workspaces.items, 1):
                print(f"[{idx}] 工作空间名称：{ws.name}")
                print(f"    工作空间ID：{ws.id}")
                print(f"    创建时间：{ws.created_at}")
                print(f"    成员数量：{ws.member_count}")
                print("-" * 60)
        else:
            print("⚠️ 未获取到工作空间数据")
            
    except Exception as e:
        # 捕获所有异常，方便新手排查问题
        print(f"❌ 调用SDK失败：{str(e)}")

# 4. 主函数入口
if __name__ == "__main__":
    get_coze_workspaces()
4.1.2 代码解释
  1. import部分：导入 os（读取环境变量）、cozepy 核心类、load_dotenv（加载.env 文件）；
  2. load_dotenv()：自动读取.env文件中的变量，把COZE_API_TOKEN加载到系统环境中；
  3. os.environ.get("COZE_API_TOKEN")：从环境变量中读取令牌，避免硬编码；
  4. Coze()初始化：
    • auth=TokenAuth(token=api_token)：用令牌做身份认证，SDK 会自动处理 “Bearer + 令牌” 的格式，不用手动拼；
    • base_url=COZE_CN_BASE_URL：指定国内版 Coze 的 API 域名（固定值，不用改）；
  5. coze_client.workspaces.list()：调用 SDK 的工作空间列表接口，SDK 自动处理 HTTP 请求、响应解析；
  6. 异常处理：捕获所有可能的错误（比如令牌无效、网络问题），并给出明确提示。
4.1.3 运行结果示例
✅ 成功获取工作空间列表：
------------------------------------------------------------
[1] 工作空间名称：我的第一个工作空间
    工作空间ID：1234567890
    创建时间：2025-10-01T12:00:00Z
    成员数量：1
------------------------------------------------------------
[2] 工作空间名称：测试工作空间
    工作空间ID：0987654321
    创建时间：2025-11-01T10:00:00Z
    成员数量：2
------------------------------------------------------------
4.1.4 避坑点
  • 坑 1：.env文件路径不对→确保.env在项目根目录，和运行的 py 文件同级；
  • 坑 2：令牌错误→检查.env中的令牌是否和 Coze 生成的一致，有没有多 / 少字符；
  • 坑 3：权限不足→生成令牌时勾选了对应的工作空间权限。

4.2 核心功能：和智能体聊天（同步模式）

和智能体聊天是 Coze 最常用的功能，SDK 把复杂的 API 调用封装成了简单的函数，新手只需传bot_id（智能体 ID）和问题即可。

4.2.1 先找智能体 ID

在调用前，你需要先获取智能体 ID：

  1. 打开 Coze 智能体开发页面：https://www.coze.cn/bot
  2. 点击你要调用的智能体，进入开发页面；
  3. 看浏览器地址栏，bot=后面的数字就是智能体 ID（比如https://www.coze.cn/bot/editor?bot=7536152918114779162，ID 就是 7536152918114779162）。
4.2.2 完整代码示例
import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 配置智能体信息（替换成你自己的）
BOT_ID = "7536152918114779162"  # 智能体ID
USER_ID = "test_user_001"       # 自定义用户ID（区分不同用户）

def chat_with_coze_bot(question: str):
    """
    调用Coze SDK和智能体同步聊天（等智能体回复完再返回）
    """
    api_token = os.environ.get("COZE_API_TOKEN")
    if not api_token:
        print("❌ 未配置Coze令牌")
        return
    
    try:
        # 初始化客户端
        coze_client = Coze(
            auth=TokenAuth(token=api_token),
            base_url=COZE_CN_BASE_URL
        )
        
        # 调用聊天接口
        response = coze_client.chat.create(
            bot_id=BOT_ID,
            user_id=USER_ID,
            stream=False,  # 同步模式：False；流式模式：True
            additional_messages=[
                {
                    "role": "user",       # 固定值：user（用户）
                    "content": question,  # 用户的问题
                    "content_type": "text"# 固定值：text（文字）
                }
            ]
        )
        
        # 解析回复结果
        print(f"🤖 智能体回复：")
        # 遍历回复消息
        for msg in response.messages:
            if msg.role == "assistant":  # assistant代表智能体
                print(msg.content)
        
        # 可选：打印Token消耗
        print(f"\n💡 Token消耗：输入{response.usage.input_count} | 输出{response.usage.output_count} | 总计{response.usage.token_count}")
        
    except Exception as e:
        print(f"❌ 聊天失败：{str(e)}")

if __name__ == "__main__":
    # 输入你要问的问题
    user_question = input("请输入你要问智能体的问题：")
    chat_with_coze_bot(user_question)
4.2.3 代码解释
  1. BOT_ID：替换成你的智能体 ID，这是唯一需要改的核心参数；
  2. coze_client.chat.create()：SDK 的聊天接口，核心参数：
    • bot_id：智能体 ID；
    • user_id：自定义用户 ID（比如 “小明”“小红”，用于区分不同用户的会话）；
    • stream=False：同步模式，等智能体回复完所有内容再返回；
    • additional_messages：用户的问题列表，格式固定；
  3. 解析结果：response.messages包含所有聊天消息，role="assistant"的是智能体回复。
4.2.4 运行结果示例
请输入你要问智能体的问题：你好，介绍一下自己
🤖 智能体回复：
你好！我是基于Coze平台开发的智能助手，能为你解答各种问题、提供信息咨询和实用建议。我的能力来自Coze的大模型和自定义配置，如果你有任何想知道的，都可以尽管问～

💡 Token消耗：输入15 | 输出89 | 总计104

4.3 进阶功能：流式聊天（打字机效果）

同步模式需要等智能体回复完才显示内容，而流式模式（像 ChatGPT 一样）能 “边想边说”，体验更好 ——SDK 只需改一个参数就能实现。

4.3.1 完整代码示例
import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

load_dotenv()
BOT_ID = "7536152918114779162"
USER_ID = "test_user_001"

def stream_chat_with_bot(question: str):
    """
    流式聊天：智能体边回复边显示（打字机效果）
    """
    api_token = os.environ.get("COZE_API_TOKEN")
    if not api_token:
        print("❌ 未配置令牌")
        return
    
    try:
        coze_client = Coze(
            auth=TokenAuth(token=api_token),
            base_url=COZE_CN_BASE_URL
        )
        
        # 流式调用（stream=True）
        stream = coze_client.chat.create(
            bot_id=BOT_ID,
            user_id=USER_ID,
            stream=True,  # 开启流式模式
            additional_messages=[
                {"role": "user", "content": question, "content_type": "text"}
            ]
        )
        
        # 处理流式响应（逐行打印）
        print(f"🤖 智能体回复（流式）：")
        full_content = ""
        for chunk in stream:
            if chunk.event == "message":
                # 拼接流式内容
                content = chunk.data.content or ""
                full_content += content
                # 不换行打印，模拟打字机
                print(content, end="", flush=True)
        
        # 打印Token消耗（最后获取）
        print(f"\n\n💡 Token消耗：{chunk.data.usage.token_count}")
        
    except Exception as e:
        print(f"❌ 流式聊天失败：{str(e)}")

if __name__ == "__main__":
    user_question = input("请输入问题：")
    stream_chat_with_bot(user_question)
4.3.2 核心差异
  • stream=True：开启流式模式；
  • 处理响应时用for chunk in stream：遍历流式返回的每一个片段；
  • print(content, end="", flush=True)：不换行打印，实现打字机效果。

4.4 实用功能：执行 Coze 工作流

如果你在 Coze 上创建了自定义工作流（比如翻译、文案生成、数据处理），SDK 也能一键调用，比 API 简单 10 倍。

4.4.1 先找工作流 ID
  1. 打开 Coze 工作流页面：https://www.coze.cn/workflow
  2. 点击你的工作流，进入编辑页面；
  3. 浏览器地址栏中workflow=后面的数字就是工作流 ID。
4.4.2 完整代码示例
import os
import json
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

load_dotenv()

# 配置工作流信息（替换成你的）
WORKFLOW_ID = "8675309876543210"  # 工作流ID
WORKSPACE_ID = "1234567890"       # 工作空间ID

def run_coze_workflow(input_content: str, target_lang: str = "英语"):
    """
    调用Coze SDK执行自定义工作流（比如翻译工作流）
    """
    api_token = os.environ.get("COZE_API_TOKEN")
    if not api_token:
        print("❌ 未配置令牌")
        return
    
    try:
        coze_client = Coze(
            auth=TokenAuth(token=api_token),
            base_url=COZE_CN_BASE_URL
        )
        
        # 构造工作流输入参数（需转成JSON字符串）
        parameters = json.dumps({
            "content": input_content,  # 工作流的输入参数名（和你定义的一致）
            "language": target_lang    # 工作流的输入参数名
        })
        
        # 执行工作流
        response = coze_client.workflows.run(
            workflow_id=WORKFLOW_ID,
            workspace_id=WORKSPACE_ID,
            parameters=parameters,
            is_async=False  # 同步执行
        )
        
        # 解析工作流结果
        print(f"✅ 工作流执行成功！")
        print(f"执行结果：{response.result}")
        print(f"调试链接：{response.debug_url}")  # 可在Coze查看执行详情
        
    except Exception as e:
        print(f"❌ 工作流执行失败：{str(e)}")

if __name__ == "__main__":
    # 测试翻译工作流
    content = input("请输入要翻译的文字：")
    target_lang = input("请输入目标语言（比如英语/法语）：")
    run_coze_workflow(content, target_lang)
4.4.3 关键参数解释
  • parameters：工作流的输入参数，必须是 JSON 字符串（用json.dumps()转换）；
  • is_async=False：同步执行，等工作流完成后返回结果；如果是耗时较长的工作流，可设为True（异步执行）；
  • debug_url：Coze 提供的调试链接，点击可查看工作流的执行步骤、参数、输出，新手排查问题超有用。

4.5 管理功能：查看智能体列表与详情

如果你有多个智能体，可通过 SDK 批量查看智能体信息，比如名称、配置、发布状态等。

4.5.1 完整代码示例
import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

load_dotenv()
WORKSPACE_ID = "1234567890"  # 工作空间ID

def get_bot_list_and_detail():
    """
    查看工作空间内的智能体列表，并获取第一个智能体的详细配置
    """
    api_token = os.environ.get("COZE_API_TOKEN")
    if not api_token:
        print("❌ 未配置令牌")
        return
    
    try:
        coze_client = Coze(
            auth=TokenAuth(token=api_token),
            base_url=COZE_CN_BASE_URL
        )
        
        # 1. 获取智能体列表
        bots = coze_client.bots.list(
            workspace_id=WORKSPACE_ID,
            publish_status="all"  # all=全部，published_online=已发布，unpublished_draft=草稿
        )
        
        print("📋 智能体列表：")
        print("-" * 80)
        bot_ids = []
        for idx, bot in enumerate(bots.items, 1):
            bot_ids.append(bot.id)
            print(f"[{idx}] 名称：{bot.name}")
            print(f"    ID：{bot.id}")
            print(f"    状态：{'已发布' if bot.is_published else '草稿'}")
            print(f"    描述：{bot.description or '无'}")
            print("-" * 80)
        
        # 2. 获取第一个智能体的详细配置
        if bot_ids:
            first_bot_id = bot_ids[0]
            bot_detail = coze_client.bots.get(
                bot_id=first_bot_id,
                is_published=True  # True=已发布版本，False=草稿版本
            )
            
            print(f"\n🔍 第一个智能体（{bot_detail.name}）的详细配置：")
            print(f"使用模型：{bot_detail.model_info.model_name}")
            print(f"温度参数（创意度）：{bot_detail.model_info.temperature}")
            print(f"上下文轮数：{bot_detail.model_info.context_round}")
            print(f"最大回复字数：{bot_detail.model_info.max_tokens}")
            print(f"\n提示词：\n{bot_detail.prompt_info.prompt[:200]}...")  # 只显示前200字
        
    except Exception as e:
        print(f"❌ 获取智能体信息失败：{str(e)}")

if __name__ == "__main__":
    get_bot_list_and_detail()
4.5.2 核心价值
  • 批量管理智能体：不用手动在 Coze 页面一个个看；
  • 查看智能体配置：比如模型类型、温度参数、提示词，方便批量调整；
  • 区分发布状态：快速筛选已发布 / 草稿的智能体。

五、Coze SDK 进阶技巧：让代码更健壮

新手学会基础调用后，还需要掌握一些进阶技巧，让代码更稳定、更易维护。

5.1 优雅的异常处理：捕获特定错误

基础的Exception捕获太笼统，我们可以捕获 SDK 的特定异常（或按错误类型分类），精准排查问题：

import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from cozepy.exceptions import AuthError, NotFoundError, PermissionError
from dotenv import load_dotenv

load_dotenv()

def robust_chat(question: str):
    api_token = os.environ.get("COZE_API_TOKEN")
    coze_client = Coze(auth=TokenAuth(api_token), base_url=COZE_CN_BASE_URL)
    
    try:
        response = coze_client.chat.create(
            bot_id="7536152918114779162",
            user_id="test_user",
            stream=False,
            additional_messages=[{"role": "user", "content": question, "content_type": "text"}]
        )
        print(response.messages[0].content)
        
    except AuthError:
        print("❌ 令牌无效或已过期，请重新生成PAT")
    except NotFoundError:
        print("❌ 智能体ID不存在，请检查ID是否正确")
    except PermissionError:
        print("❌ 令牌没有调用该智能体的权限，请重新生成令牌并勾选权限")
    except TimeoutError:
        print("❌ 请求超时，请检查网络或重试")
    except Exception as e:
        print(f"❌ 未知错误：{str(e)}")

if __name__ == "__main__":
    robust_chat("你好")

5.2 超时设置与重试机制：应对网络波动

网络不稳定时，SDK 调用可能超时，我们可以设置超时时间，并添加重试机制（用tenacity库）：

# 先安装tenacity
# pip install tenacity

import os
from tenacity import retry, stop_after_attempt, wait_fixed
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

load_dotenv()

# 初始化客户端时设置超时（单位：秒）
coze_client = Coze(
    auth=TokenAuth(os.environ.get("COZE_API_TOKEN")),
    base_url=COZE_CN_BASE_URL,
    timeout=30  # 超时时间30秒
)

# 添加重试机制：失败后重试3次，每次间隔2秒
@retry(stop=stop_after_attempt(3), wait=wait_fixed(2))
def chat_with_retry(question: str):
    response = coze_client.chat.create(
        bot_id="7536152918114779162",
        user_id="test_user",
        stream=False,
        additional_messages=[{"role": "user", "content": question, "content_type": "text"}]
    )
    return response

if __name__ == "__main__":
    try:
        result = chat_with_retry("你好")
        print(result.messages[0].content)
    except Exception as e:
        print(f"❌ 重试3次后仍失败：{str(e)}")

5.3 日志记录：追踪 SDK 调用过程

添加日志可以方便排查问题，尤其是线上环境：

import os
import logging
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from dotenv import load_dotenv

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[logging.FileHandler("coze_sdk.log"), logging.StreamHandler()]
)
logger = logging.getLogger(__name__)

load_dotenv()

def chat_with_log(question: str):
    api_token = os.environ.get("COZE_API_TOKEN")
    if not api_token:
        logger.error("未配置Coze令牌")
        return
    
    try:
        logger.info(f"开始调用智能体聊天，问题：{question}")
        coze_client = Coze(auth=TokenAuth(api_token), base_url=COZE_CN_BASE_URL)
        response = coze_client.chat.create(
            bot_id="7536152918114779162",
            user_id="test_user",
            stream=False,
            additional_messages=[{"role": "user", "content": question, "content_type": "text"}]
        )
        logger.info(f"聊天成功，Token消耗：{response.usage.token_count}")
        print(response.messages[0].content)
        
    except Exception as e:
        logger.error(f"聊天失败：{str(e)}")

if __name__ == "__main__":
    chat_with_log("你好")

日志会同时输出到控制台和coze_sdk.log文件，方便后续查看。

六、Coze SDK 常见问题与避坑指南

新手使用 SDK 时，难免会遇到各种问题，我整理了最常见的 10 个问题及解决方案：

6.1 安装类问题

问题现象原因解决方案
ModuleNotFoundError: No module named 'cozepy'cozepy 未安装成功，或安装到了其他 Python 环境1. 重新执行pip install cozepy；2. 检查 PyCharm 的解释器是否和安装 cozepy 的 Python 一致；3. 用pip show cozepy查看安装路径，确认解释器能找到
安装 cozepy 时提示 “权限不足”系统权限限制1. Windows：pip install --user cozepy；2. macOS/Linux：sudo pip3 install cozepy
安装速度极慢网络问题，默认镜像源在国外换国内镜像源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple cozepy

6.2 配置类问题

问题现象原因解决方案
os.environ.get("COZE_API_TOKEN")返回 None.env 文件路径不对，或文件名错误1. 确保.env 文件在项目根目录；2. 检查文件名是.env（有开头的点），不是env或.env.txt；3. 手动指定.env 路径：load_dotenv(dotenv_path="/path/to/.env")
令牌无效 / 鉴权失败令牌错误、过期，或权限不足1. 核对令牌是否和 Coze 生成的一致；2. 去 Coze 令牌页面查看是否过期；3. 重新生成令牌，勾选所有需要的权限

6.3 调用类问题

问题现象原因解决方案
智能体 ID 不存在ID 抄错，或智能体不属于当前工作空间1. 重新从浏览器地址栏复制智能体 ID；2. 确认智能体所在的工作空间和令牌的工作空间一致
工作流执行失败：“工作流未发布”调用的工作流是草稿状态打开 Coze 工作流页面，点击 “发布” 按钮
流式聊天解析失败未处理流式响应的结束标志参考 4.3 的代码，用for chunk in stream遍历，判断chunk.event
请求超时网络波动，或智能体 / 工作流执行耗时过长1. 设置超时时间（timeout=30）；2. 添加重试机制；3. 检查智能体 / 工作流是否有耗时操作

七、实战项目：搭建自己的命令行 AI 聊天机器人

学完所有知识点后，我们整合一下，搭建一个简单但实用的命令行 AI 聊天机器人 —— 这个项目包含了 SDK 的核心用法，可以直接复用。

7.1 项目需求

  1. 支持和 Coze 智能体实时聊天（流式模式）；
  2. 支持查看聊天记录的 Token 消耗；
  3. 支持退出聊天功能；
  4. 完善的异常处理和日志记录。

7.2 项目结构

CozeSDK_Demo/
├── .env                # 令牌配置文件
├── coze_chat_bot.py    # 主程序
└── coze_sdk.log        # 日志文件（自动生成）

7.3 完整代码（coze_chat_bot.py）

import os
import logging
from dotenv import load_dotenv
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
from cozepy.exceptions import AuthError, NotFoundError, PermissionError

# ---------------------- 1. 配置日志 ----------------------
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[
        logging.FileHandler("coze_sdk.log", encoding="utf-8"),
        logging.StreamHandler()
    ]
)
logger = logging.getLogger(__name__)

# ---------------------- 2. 加载配置 ----------------------
load_dotenv()
API_TOKEN = os.environ.get("COZE_API_TOKEN")
BOT_ID = os.environ.get("COZE_BOT_ID")  # 可以把BOT_ID也放到.env里
USER_ID = "cli_chat_user"

# 校验配置
if not API_TOKEN or not BOT_ID:
    logger.error("请在.env文件中配置COZE_API_TOKEN和COZE_BOT_ID")
    exit(1)

# ---------------------- 3. 初始化Coze客户端 ----------------------
try:
    coze_client = Coze(
        auth=TokenAuth(token=API_TOKEN),
        base_url=COZE_CN_BASE_URL,
        timeout=30
    )
    logger.info("Coze客户端初始化成功")
except Exception as e:
    logger.error(f"Coze客户端初始化失败：{str(e)}")
    exit(1)

# ---------------------- 4. 核心聊天函数 ----------------------
def stream_chat(question: str):
    """流式聊天函数"""
    try:
        logger.info(f"用户提问：{question}")
        # 调用SDK流式聊天接口
        stream = coze_client.chat.create(
            bot_id=BOT_ID,
            user_id=USER_ID,
            stream=True,
            additional_messages=[
                {"role": "user", "content": question, "content_type": "text"}
            ]
        )
        
        # 处理流式响应
        print("\n🤖 智能体回复：")
        full_content = ""
        token_count = 0
        for chunk in stream:
            if chunk.event == "message":
                content = chunk.data.content or ""
                full_content += content
                print(content, end="", flush=True)
            # 获取Token消耗
            if chunk.data and hasattr(chunk.data, "usage"):
                token_count = chunk.data.usage.token_count
        
        print(f"\n💡 本次Token消耗：{token_count}")
        logger.info(f"智能体回复：{full_content[:50]}... | Token消耗：{token_count}")
        return True
    
    except AuthError:
        logger.error("令牌无效或已过期")
        print("❌ 错误：令牌无效或已过期，请重新生成PAT")
    except NotFoundError:
        logger.error("智能体ID不存在")
        print("❌ 错误：智能体ID不存在，请检查配置")
    except PermissionError:
        logger.error("令牌无权限调用该智能体")
        print("❌ 错误：令牌没有调用该智能体的权限，请重新生成令牌")
    except TimeoutError:
        logger.error("请求超时")
        print("❌ 错误：请求超时，请检查网络或重试")
    except Exception as e:
        logger.error(f"聊天失败：{str(e)}")
        print(f"❌ 错误：{str(e)}")
    return False

# ---------------------- 5. 主程序入口 ----------------------
def main():
    print("=" * 60)
    print("🎉 Coze AI命令行聊天机器人（输入'退出'结束聊天）")
    print("=" * 60)
    
    while True:
        # 获取用户输入
        user_input = input("\n请输入你的问题：").strip()
        if user_input.lower() in ["退出", "exit", "quit"]:
            logger.info("用户退出聊天")
            print("👋 再见！")
            break
        if not user_input:
            print("⚠️ 请输入有效问题")
            continue
        
        # 调用聊天函数
        stream_chat(user_input)

if __name__ == "__main__":
    main()

7.4 .env 文件配置

# Coze令牌
COZE_API_TOKEN=pat_xzio1K9Lr55oDO3WT5jNj77UpbtuArvdibldjcUKdcRd3QVSgS7XBWr4lXQWTnEB
# 智能体ID
COZE_BOT_ID=7536152918114779162

7.5 运行效果

============================================================
🎉 Coze AI命令行聊天机器人（输入'退出'结束聊天）
============================================================

请输入你的问题：你好，介绍一下Coze

🤖 智能体回复：
Coze（扣子）是字节跳动推出的一站式AI开发平台，无需复杂的编程能力，就能快速创建智能体、工作流等AI应用。你可以通过可视化界面配置提示词、调用工具、设计工作流，还能通过API/SDK将智能体集成到自己的产品中，覆盖客服、创作、数据分析等多个场景～
💡 本次Token消耗：128

请输入你的问题：退出
👋 再见！

八、总结与展望

8.1 核心知识点回顾

  1. SDK 的本质：是平台封装好的 “懒人工具包”，比 API 更适合新手，无需关注底层 HTTP 请求；
  2. Coze SDK 核心步骤：安装 cozepy→获取 PAT 令牌→配置.env 文件→初始化 Coze 客户端→调用 SDK 函数；
  3. 核心功能：工作空间管理、智能体聊天（同步 / 流式）、工作流执行、智能体管理；
  4. 进阶技巧：异常处理、超时设置、重试机制、日志记录，让代码更健壮；
  5. 避坑关键：令牌要保护（不硬编码）、ID 要核对（从地址栏复制）、权限要勾选（生成令牌时）。

8.2 后续学习方向

  1. 异步调用：对于耗时较长的工作流，学习 SDK 的异步调用方式；
  2. 工具调用：通过 SDK 让智能体调用自定义工具（比如天气 API、数据库查询）；
  3. 批量操作：用 SDK 批量发布 / 修改智能体、导出聊天记录；
  4. 集成到 Web 应用：结合 FastAPI/Flask，把 Coze SDK 集成到 Web 应用中，搭建自己的 AI 网站。

结语

写到这里，这趟 “轻松版” Coze SDK 学习之旅也该收尾了。回头看会发现，我们从头到尾都没绕过复杂的技术术语，也没让你死记硬背任何底层原理 —— 因为 SDK 的本质，就是字节把繁琐的 API 调用 “打包” 成了新手也能上手的 “懒人工具”。

你不用懂 HTTP 请求怎么构造，不用管 JSON 怎么解析，甚至不用纠结 “Bearer” 前缀该怎么加，只需要做好三件事：装对环境、护好令牌、调对函数，就能把 Coze 的 AI 能力握在手里。就像我们最后做的命令行聊天机器人，几行核心代码，就能实现和智能体的实时对话，这就是 SDK 最核心的价值：把 “怎么实现” 的复杂问题，变成 “我要做什么” 的简单选择。

不用怕自己是 Python 新手，也不用纠结代码写得够不够 “专业”。技术的学习从来不是 “一步到位”，而是 “先跑起来，再慢慢优化”：今天能跑通 “查看工作空间”，明天能调通 “流式聊天”，后天能执行自己做的翻译工作流 —— 每一个能实际运行的小案例，都是比背会一百个函数更重要的收获。

Coze SDK 给我们打开的，不只是 “调用 AI” 的入口，更是 “定制 AI” 的可能性：你可以把它集成到自己的小程序里做智能客服，也可以写个脚本批量处理文本，甚至给团队搭个专属的 AI 助手 —— 这些听起来复杂的事，用 SDK 来做，其实都是 “调函数” 的简单延伸。

最后想和你说：学习本就该是轻松的，尤其是面对 AI 这样的新事物。不用怕试错，不用追求 “一口吃成胖子”，哪怕今天只学会了一个coze_client.chat.create()，只要能用上、能解决你一个小问题，这趟学习就有了意义。

不妨现在就打开 PyCharm，把我们的示例代码里的 ID 换成你自己的，问智能体一个你真正关心的问题 —— 当你看到屏幕上跳出智能体的回复时，会发现：原来把 AI 能力变成自己的工具，真的就这么简单。

期待你用 Coze SDK 做出第一个属于自己的 AI 小应用，也期待你在使用中慢慢发现更多有趣的玩法。毕竟，技术的魅力从来不是掌握多少知识点，而是用它解决多少实际问题。祝你玩得开心，也祝你在 AI 开发的路上，一直能保持这份 “轻松学、大胆试” 的心态～

# 人工智能 # python
Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

RoboChallenge：具身策略的大规模真实机器人评估

avatar DAMO开发者矩阵
cover

“伟大征程 100”：评估具身智体 的100 项细节-导向任务

avatar DAMO开发者矩阵
cover

学做机器人！PythonRobotics：机器人算法学习的全能教科书

avatar DAMO开发者矩阵