问题: 如何在本地调用已经发布的Coze智能体

👇 点击展开/折叠 面试背诵模板（建议先背这个） 在本地调用已发布的Coze智能体，核心是通过Coze OpenAPI发起HTTP请求与云端智能体对话。前置准备：在Coze控制台将智能体发布为API服务，获取Bot ID和个人访问令牌（PAT）。调用方式有两种：一是直接调用原生HTTP API，发送POST请求至/v3/chat接口，支持流式和非流式响应；二是使用官方SDK（Python/Node.js等），封装了鉴权、流解析等逻辑。若需在本地运行并连接本地AI Agent（如Claude Code），可使用coze-bridge npm包作为桥接守护进程。
---

一、前置准备（必须完成）

① 发布智能体为API服务
在Coze平台完成智能体配置后，必须将其发布为API服务，否则无法通过接口调用。发布时需在发布渠道中勾选“API”选项。

② 获取Bot ID
Bot ID是调用API时必须传入的智能体唯一标识。可在Bot编辑页面的URL末尾找到，格式通常为数字字符串。注意不是Bot名称，名称和ID不可混用。

③ 创建个人访问令牌（PAT）
在Coze控制台的“个人中心”→“API管理”中创建PAT（Personal Access Token）。调试和本地开发场景推荐使用PAT鉴权，生产环境的多用户场景可改用OAuth2。Token需通过Header传递：Authorization: Bearer YOUR_API_TOKEN。

二、方式一：原生HTTP API调用（通用方案）

直接发送HTTP请求，无第三方依赖，任何能发HTTP请求的语言或工具均可使用。

核心接口：POST https://api.coze.cn/v3/chat

  • 流式响应：智能体边生成边返回，适合需要“打字机效果”的前端展示
  • 非流式响应：请求立即返回，需轮询获取最终结果

请求示例（cURL）：

1
2
3
4
5
6
7
8
9
10
curl -X POST https://api.coze.cn/v3/chat \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "YOUR_BOT_ID",
    "user_id": "YOUR_USER_ID",
    "additional_messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ]
  }'

适用场景：跨多语言异构系统、硬件嵌入式、不想引入第三方依赖包、需要深度自定义请求逻辑的场景。

三、方式二：官方SDK调用（开发效率方案）

Coze提供官方多语言SDK（Python、Node.js等），封装了鉴权、流式响应解析、会话管理、自动重试等逻辑。

环境配置：

1
2
# 设置环境变量（推荐）
export COZE_API_KEY="YOUR_PAT_TOKEN"

Python示例：

1
2
3
4
5
6
7
8
9
from coze import Coze

client = Coze(api_key="YOUR_PAT_TOKEN")
response = client.chat(
    bot_id="YOUR_BOT_ID",
    user_id="YOUR_USER_ID",
    message="你好"
)
print(response.content)

适用场景：Python/JS后端业务开发、快速迭代、频繁使用流式对话/工作流、需要OAuth多用户登录的场景。

四、方式三：本地Agent桥接（高级方案）

如需让Coze云端智能体调用本地AI Agent（如Claude Code、Codex CLI），可使用coze-bridge。

coze-bridge是字节跳动发布的npm包，作为本机后台守护进程（daemon），将Coze云端的Agent Service与本地AI Agent桥接起来。核心基于ACP（Agent Client Protocol）协议，该协议是一个基于JSON-RPC 2.0的开放协议。

启动命令：

1
npx -y coze-bridge@latest --pat-token=sat_xxx --pair-code=xxx

五、关键注意事项

注意点 说明
域名区分 国内区使用api.coze.cn，国际区使用api.coze.com
Token安全 不要将Token硬编码在前端或上传至公开仓库，生产环境应通过环境变量或密钥管理系统保存
Bot ID校验 确保传入的是数字ID而非Bot名称，否则调用失败
工作流调用 调用独立工作流需使用workflow_id，且必须先发布
流式响应处理 若使用原生API，需手动解析SSE数据流；SDK内置迭代器可直接循环取值