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},  # 请求体，指定使用的机器人 ID
    timeout=30  # 超时时间 30 秒
)

# 检查请求是否成功，否则抛出异常
resp.raise_for_status()

# 解析返回 JSON，提取会话 ID
conv_id = resp.json()["data"]["id"]

# 2) 发起流式聊天（SSE）
params = {"conversation_id": conv_id}  # 附加参数，指定会话 ID

payload = {
    "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:  # 跳过空行
            continue
        if raw.startswith("data:"):  # 只处理 data: 开头的 SSE 数据
            data = raw[5:].strip()  # 去掉 data: 前缀并去掉空格
            if data == "[DONE]":  # 如果收到 [DONE] 表示流结束
                break
            try:
                pkt = json.loads(data)  # 将 JSON 字符串解析为 Python 对象
            except json.JSONDecodeError:  # 如果解析失败（可能是心跳包或注释），跳过
                continue

            # 提取必要字段
            msg_type = pkt.get("type")  # 消息类型，例如 answer、follow_up 等
            role = pkt.get("role")  # 消息发送方角色，assistant 或 user
            content = 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_id
                if 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项目，并引入如下依赖：

<!--引入jackson依赖，将Java 对象（POJO）序列化为 JSON-->
<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中机器人 ID
    private 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_id

        HttpRequest 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 反序列化为 Map
        Map<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，以便逐行读取 SSE
        HttpResponse<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，就能直接在你的网页/应用中通过组件 &#x3c;ChatFramework/>、&#x3c;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" }}>
      <ChatFramework
        chat={{
          appId: "7536753703852703744", // 在 Coze 开源版里即智能体ID
          type: ChatType.Bot,
        }}
        setting={{
          apiBaseUrl: "http://node2:8888", // 你的 Coze Studio URL地址
          language: Language.ZH_CN,
          logLevel: "debug",
        }}
        auth={{
          token: "pat_3edb4ddb0689beb7000ff88b5c5e9f9020fc06d82206c9e6abe9eca32ee7194d",                // 你的 Personal Access Token
          onRefreshToken: () => "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
> vite



  VITE 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对话：