当前位置：首页 > news >正文

Chat API和Chat SDK

news 2025/9/23 12:23:04

Chat API使用

Coze Studio 并未提供像 Coze AI 那样完整的Python/Go/Java SDK，但它支持通过 Rest API 方式来与发布的Agent进行对话，即这里所说的Chat API。

准备工作

使用Chat API 必须先将智能体发布为API服务且要设置访问令牌。

发布智能体为API服务
智能体发布为 API 服务之后，才能通过调用 API 的方式使用这个智能体，例如查看智能体的基本设置、发起一个智能体对话等。
获取访问令牌
Coze Studio 社区版 API 和 Chat SDK 通过个人访问令牌鉴权。调用 API 之前，你需要先获得访问令牌。调用扣子 API 时，你需要在 Header 中通过 Authorization 参数指定访问令牌（Access token），扣子服务端会根据访问令牌验证调用方的操作权限。

获取访问令牌的操作步骤如下：

Python API

Python代码中使用Rest API 代码方式与Coze Stdio 中Agent进行对话代码如下：

import json, requests
'''使用Http 方式使用 Coze Stdio中的Agent
'''# 本地部署的 Coze Studio API 服务地址
BASE = "http://node2:8888"
# 你的 Coze API 访问令牌
TOKEN = "pat_2dffc6a017ff0840a5e53a7379bcb870d456edcee6602e00cf9c4f7aa719ee1d"
# Coze Stdio中机器人 ID
BOT_ID = "7537182040039358464"
# 自定义用户 ID，用于区分不同会话
USER_ID = "123"# 设置 HTTP 请求头，包含认证信息和请求体类型
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}# 1) 创建会话
resp = requests.post(f"{BASE}/v1/conversation/create",  # 会话创建接口headers=headers,  # 请求头json={"bot_id": BOT_ID},  # 请求体，指定使用的机器人 IDtimeout=30  # 超时时间 30 秒
)# 检查请求是否成功，否则抛出异常
resp.raise_for_status()# 解析返回 JSON，提取会话 ID
conv_id = resp.json()["data"]["id"]# 2) 发起流式聊天（SSE）
params = {"conversation_id": conv_id}  # 附加参数，指定会话 IDpayload = {"bot_id": BOT_ID,  # 机器人 ID"user_id": USER_ID,  # 用户 ID"stream": True,  # 启用流式响应"auto_save_history": True,  # 自动保存对话历史"additional_messages": [  # 附加消息，作为对话输入{"role": "user", "content": "给我讲个励志的故事", "content_type": "text"}  # 用户发送的文本消息],
}# 用于存储完整的回答内容
full_answer = []# 用于跟踪当前回答的消息 ID（便于增量拼接）
current_msg_id = None# 发送 POST 请求到聊天接口，开启 SSE 流式连接
with requests.post(f"{BASE}/v3/chat",  # 聊天接口headers=headers,  # 请求头params=params,  # 查询参数json=payload,  # 请求体stream=True,  # 开启流式传输timeout=600  # 设置超时为 600 秒
) as r:r.raise_for_status()  # 检查响应状态码r.encoding = "utf-8"  # 强制设置响应编码为 UTF-8（SSE 标准要求）for raw in r.iter_lines(decode_unicode=True):  # 按行读取流式数据# print("raw:",raw)if not raw:  # 跳过空行continueif raw.startswith("data:"):  # 只处理 data: 开头的 SSE 数据data = raw[5:].strip()  # 去掉 data: 前缀并去掉空格if data == "[DONE]":  # 如果收到 [DONE] 表示流结束breaktry:pkt = json.loads(data)  # 将 JSON 字符串解析为 Python 对象except json.JSONDecodeError:  # 如果解析失败（可能是心跳包或注释），跳过continue# 提取必要字段msg_type = pkt.get("type")  # 消息类型，例如 answer、follow_up 等role = pkt.get("role")  # 消息发送方角色，assistant 或 usercontent = pkt.get("content")  # 消息内容msg_id = pkt.get("id")  # 消息 ID# 只处理机器人（assistant）发的 answer 类型消息if msg_type == "answer" and role == "assistant":if current_msg_id is None:  # 如果是当前对话的第一条回答消息current_msg_id = msg_idif content:  # 如果有文本内容# 实时输出到终端（流式显示）print(content, end="", flush=True)full_answer.append(content)  # 保存到完整回答列表# 当流式对话完成后，打印完整拼接的回答print("\n\n====== 模型的完整回复 ======\n")print("".join(full_answer))

JAVA API

Java代码中使用Rest API 代码方式与Coze Stdio 中Agent进行对话代码，需要在IDEA中创建Maven项目，并引入如下依赖：

<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.17.2</version>
</dependency>
完整代码如下：

package org.example;import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Map;import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;public class CozeSSEClient {// 本地部署的 Coze Studio API 服务地址private static final String BASE = "http://node2:8888";// 你的 Coze API 访问令牌private static final String TOKEN = "pat_2dffc6a017ff0840a5e53a7379bcb870d456edcee6602e00cf9c4f7aa719ee1d";// Coze Stdio中机器人 IDprivate static final String BOT_ID = "7536753703852703744";// 自定义用户 ID，用于区分不同会话private static final String USER_ID = "123";//Jackson 的 ObjectMapper 实例，用于 JSON 编解码private static final ObjectMapper MAPPER = new ObjectMapper();//HttpClient 实例，支持设置超时、发送请求等private static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(15))// 设置连接超时为 15 秒.build();public static void main(String[] args) throws Exception {// 1) 创建会话String convId = createConversation(BOT_ID);// 2) 发起流式对话（SSE）String question = "如何保持早起的习惯？";String full = chatStream(convId, BOT_ID, USER_ID, question);System.out.println("\n\n====== 模型的完整回复 ======");System.out.println(full);}/*** 调用 /v1/conversation/create 创建会话，返回 conversation_id* */private static String createConversation(String botId) throws Exception {String url = BASE + "/v1/conversation/create";String body = "{\"bot_id\":\"" + escape(botId) + "\"}";// 请求体 JSON 字符串，指定 bot_idHttpRequest req = HttpRequest.newBuilder(URI.create(url)).timeout(Duration.ofSeconds(30))  // 设置请求超时 30 秒.header("Authorization", "Bearer " + TOKEN)  // 授权头.header("Content-Type", "application/json") // 内容类型.POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) // POST JSON 请求.build();// 发送请求并以 UTF-8 解码响应HttpResponse<String> resp = CLIENT.send(req, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));// 如果 HTTP 状态码不是 2xx，抛异常if (resp.statusCode() / 100 != 2) {throw new IOException("create conversation failed: " + resp.statusCode() + " - " + resp.body());}// 将响应体 JSON 反序列化为 MapMap<String, Object> root = MAPPER.readValue(resp.body(), new TypeReference<>() {});// 获取 data 节点Map<String, Object> data = (Map<String, Object>) root.get("data");if (data == null || data.get("id") == null) {throw new IOException("missing conversation id in response: " + resp.body());}// 返回 conversation_id 字符串return String.valueOf(data.get("id"));}/*** 调用 /v3/chat（SSE）进行流式聊天：* - 强制以 UTF-8 读取（SSE 规范要求 UTF-8）* - 只聚合 type=answer 且 role=assistant 的内容* - 同时把流式增量实时打印出来*/private static String chatStream(String conversationId, String botId, String userId, String question) throws Exception {// 拼接 URL，conversation_id 作为 query 参数String url = BASE + "/v3/chat?conversation_id=" + conversationId;// 构造请求体 JSON，包含参数、模式设定和问题内容String payload = MAPPER.writeValueAsString(Map.of("bot_id", botId,"user_id", userId,"stream", true,"auto_save_history", true,"additional_messages", new Object[]{Map.of("role", "user", "content", question, "content_type", "text")}));HttpRequest req = HttpRequest.newBuilder(URI.create(url)).timeout(Duration.ofSeconds(600))  // 最长允许 600 秒执行时间.header("Authorization", "Bearer " + TOKEN).header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8)).build();// 接收响应为 InputStream，以便逐行读取 SSEHttpResponse<java.io.InputStream> resp =CLIENT.send(req, HttpResponse.BodyHandlers.ofInputStream());//打印响应体 ，调试可以打开，查看响应体内容，实际运行过程中不要解开，因为读取完响应就没有数据了//System.out.println(new String(resp.body().readAllBytes(), StandardCharsets.UTF_8));// 检查 HTTP 状态码是否为 2xx，否则抛出异常if (resp.statusCode() / 100 != 2) {// 如果返回 HTML（可能被错误路由到前端），直接抛异常便于排查String err = new String(resp.body().readAllBytes(), StandardCharsets.UTF_8);throw new IOException("chat failed: " + resp.statusCode() + " - " + err);}StringBuilder fullAnswer = new StringBuilder();// 创建 BufferedReader，从流中按 UTF-8 解码并读取每行 SSE 数据try (BufferedReader br = new BufferedReader(new InputStreamReader(resp.body(), StandardCharsets.UTF_8))) {String line;while ((line = br.readLine()) != null) {if (line.isBlank()) continue;         // 跳过空行if (!line.startsWith("data:")) continue;  // 只处理以 "data:" 开头的行String data = line.substring(5).trim();   // 去除前缀，提取 JSON 字段内容if ("[DONE]".equals(data)) break;         // 若为结束标记，则中断循环Map<String, Object> pkt;try {pkt = MAPPER.readValue(data, new TypeReference<>() {});  // 将 JSON 转 Map} catch (Exception ignored) {continue;  // 若解析失败（非 JSON 包），忽略跳过}// 提取消息字段String type = str(pkt.get("type"));String role = str(pkt.get("role"));String content = str(pkt.get("content"));// 只处理机器人 assistant 返回的 answer 类型内容if ("answer".equals(type) && "assistant".equals(role) && content != null && !content.isEmpty()) {System.out.print(content);      // 实时打印内容（形成流式体验）System.out.flush();fullAnswer.append(content);     // 收集至最终完整回复}}}return fullAnswer.toString();  // 返回最终完整回复文本}/*** 安全转换对象为字符串，null 转 null，否则调用 toString**/private static String str(Object o) { return o == null ? null : String.valueOf(o); }/*** 转义 JSON 字符串里的双引号，避免格式错乱**/private static String escape(String s) { return s.replace("\"", "\\\""); }
}

Chat SDK使用（了解）

ChatSDK 是 Coze Studio 提供的一个前端开发工具包（Software Development Kit，简称 SDK），用于在网页或应用中快速嵌入并使用 Coze Stdio的智能体（Agent）聊天功能。它封装了与 Coze 平台交互的逻辑，包括消息的发送与接收、会话管理、UI 组件渲染等，让开发者不必从零编写 API 调用和聊天界面逻辑，只需按照提供的接口调用即可实现一个完整的聊天窗口。

简单来说：ChatSDK = Coze Stdio聊天功能的“前端组件+API封装”，需要基于一个React前端项目，只需要配置 Agent ID、Coze Stdio地址和鉴权的Token，就能直接在你的网页/应用中通过组件 <ChatFramework/>、<ChatSlot/> 即可渲染出完整的聊天界面，从而使用AI 聊天。

注意：React 是一个由 Facebook开发和维护的前端 JavaScript 框架/库，主要用于构建用户界面（UI），尤其是单页应用（SPA, Single Page Application）。

准备工作

使用Chat API 必须先将智能体发布为API服务且要设置访问令牌。

发布智能体为“Chat SDK”渠道
使用Chat SDK 前我们需要先在 Coze Stdio里把 Agent 发布到 “Chat SDK” 渠道。智能体发布为“ Chat SDK ”渠道之后，才能在前端项目中使用这个智能体。

获取访问令牌
Coze Studio 社区版 API 和 Chat SDK 通过个人访问令牌鉴权。使用Chat SDK之前，你需要先获得访问令牌。调用扣子 API 时，你需要在 Header 中通过 Authorization 参数指定访问令牌（Access token），扣子服务端会根据访问令牌验证调用方的操作权限。

获取访问令牌的操作步骤如下：

安装Node.js

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境，它让 JavaScript 不仅能在浏览器里运行，还可以在服务器或本地电脑的命令行中运行，这样使得 JavaScript 从前端语言扩展成了全栈语言。

nodejs 自带npm（Node Package Manager），npm 是全球最大的开源包管理平台，用来安装、管理各种 JavaScript 库和工具，如 ChatSDK、React、Vite 等。所以使用Chat SDK 必须要安装Node.js ,通过其提供的npm 来安装和管理Chat SDK。

按照如下步骤在Centos7 中安装Node.js ，Coze Studio Chat SDK要求Node.js版本为v18以上，这里安装v18.19.1版本，下载地址：https://unofficial-builds.nodejs.org/download/release/v18.19.1/node-v18.19.1-linux-x64-glibc-217.tar.xz

1)上传nodejs安装包并配置

```
# 将 node-v18.19.1-linux-x64-glibc-217.tar.xz 上传至如下目录
[root@node2 ~]# mkdir -p /software/nodejs && cd /software/nodejs

#解压
[root@node2 nodejs]# tar -xJf node-v18.19.1-linux-x64-glibc-217.tar.xz
[root@node2 nodejs]# mv node-v18.19.1-linux-x64-glibc-217 nodejs-v18
**

2)配置环境变量

```
[root@node2 nodejs]# vim /etc/profile

#加入如下内容
export NODE_HOME=/software/nodejs/nodejs-v18/
export PATH=$PATH:$NODE_HOME/bin

#保存并生效
[root@node2 nodejs]# source /etc/profile
```

3) 验证安装

```
[root@node2 ~]# node -v
v18.19.1
[root@node2 ~]# npm -v
10.2.4

ChatSDK使用

使用ChatSDK需要有一个前端项目，所以这里首先创建一个前端项目，然后在该项目中使用ChatSDK 与已发布的Agent进行对话。按照如下步骤配置：

1) 使用vite初始化一个React项目

Vite 是一个前端项目构建工具。

[root@node2 ~]# cd ~
#准备一个空目录作为项目根目录
[root@node2 ~]# mkdir coze-chat-demo && cd coze-chat-demo#在当前目录生成一个基于 React 的 Vite 前端项目骨架
[root@node2 ~]# npm create vite@5 . -- --template react
（需要输入y）#安装react相关依赖
[root@node2 ~]# npm install react@18.2.0 react-dom@18.2.0#安装chatsdk
[root@node2 ~]# npm install @coze/chat-sdk@0.1.11-beta.19

2) 配置App.jsx文件

在前端项目中，src/App.jsx 是 React 应用的根组件，负责定义整个应用的主结构和布局，也是全局状态与逻辑的入口。它由入口文件 main.jsx 挂载到 index.html 中的指定 DOM 节点，并作为其他页面或功能组件的容器，贯穿应用运行的全程。

创建App.jsx文件，内容如下：

import "@coze/chat-sdk/webCss";
import ChatSdk from "@coze/chat-sdk/webJs";
const { ChatFramework, ChatSlot, ChatType, Language } = ChatSdk;export default function App() {return (<div style={{ height: "100vh" }}><ChatFrameworkchat={{appId: "7536753703852703744", // 在 Coze 开源版里即智能体IDtype: ChatType.Bot,}}setting={{apiBaseUrl: "http://node2:8888", // 你的 Coze Studio URL地址language: Language.ZH_CN,logLevel: "debug",}}auth={{token: "pat_3edb4ddb0689beb7000ff88b5c5e9f9020fc06d82206c9e6abe9eca32ee7194d",                // 你的 Personal Access TokenonRefreshToken: () => "pat_3edb4ddb0689beb7000ff88b5c5e9f9020fc06d82206c9e6abe9eca32ee7194d", // 刷新后的 token}}user={{id: "demo-user-1",name: "Demo User",}}><ChatSlot className="chat-slot" /></ChatFramework></div>);
}

注意：以上appID 替换为你的Coze中智能体的BotID ;apiBaseUrl替换为你的Coze Stdio URL地址；token替换为你的令牌。

创建好App.jsx后，将该文件上传至前端项目/root/coze-chat-demo/src目录中，替换该目录中的App.jsx文件。

3) 修改vite.config.js

进入前端项目/root/coze-chat-demo/中，修改该目录下的vite.config.js文件，全部内容如下：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'export default defineConfig({plugins: [react()],server: {host: '0.0.0.0',    // 监听所有网卡port: 5173,         // 使用固定端口（默认）strictPort: true,   // 如果端口占用则报错而不是改端口},
})

该配置文件中主要配置可以通过非本机节点访问该前端项目。

4) 启动前端项目测试ChatSDK

#进入到项目地址
[root@node2 ~]# cd /root/coze-chat-demo/
#启动项目
[root@node2 coze-chat-demo]# npm run dev> coze-chat-demo@0.0.0 dev
> viteVITE v5.4.19  ready in 299 ms➜  Local:   http://localhost:5173/➜  Network: http://192.168.179.6:5173/➜  press h + enter to show help

启动项目后，在浏览器中直接访问：http://你的ip:5173/ 可以看到前端页面，并可以进行与Agent对话：