说明

初始化之前，请确认已完成以下操作：

已安装扣子编程 Python SDK。更多信息，可参见安装 Python SDK。
已实现授权流程，并通过环境变量等方式配置了访问密钥。详细说明可参考配置访问密钥。
请确保扣子编程 Python SDK 版本已升级至 0.17.0 及之后版本，以免调用发起对话或执行对话流 API 失败。

初始化 SDK

初始化扣子编程 client 之后，才可以向扣子编程服务端发送 OpenAPI 请求。初始化时推荐通过环境变量动态获取访问密钥，以免硬编码引发数据安全风险。
初始化代码如下：

import os

from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
# 扣子编程建议你通过环境变量的方式管理访问密钥，关于环境变量的详细说明可参考 Python 官方文档。
coze = Coze(auth=TokenAuth(os.getenv("coze_api_token")), base_url=COZE_CN_BASE_URL)

创建并发布智能体为 API 服务

通过 API 方式和智能体对话之前，你需要先创建一个智能体，并将其发布为 API 服务。你可以通过扣子编程平台或调用相关的 API 实现智能体的创建和发布。

通过扣子编程创建和发布智能体的操作请参见搭建一个 AI 助手智能体、发布智能体为 API 服务。
通过 API 创建和发布智能体的接口文档请参见创建智能体、发布智能体。
说明

调用 API 创建智能体时，部分配置对应的 API 参数暂未开放，你只能为智能体添加知识库等有限的配置。

示例代码如下：
完整的示例代码，请参见 examples/bot_publish.py示例源码。

import os  # noqa
from pathlib import Path

# Get an access_token through personal access token oroauth.
coze_api_token = os.getenv("COZE_API_TOKEN")

from cozepy import Coze, TokenAuth, BotPromptInfo, Message, ChatEventType, MessageContentType  # noqa

# Init the Coze client
coze = Coze(auth=TokenAuth(token=coze_api_token), base_url=COZE_CN_BASE_URL)

# Call the upload file interface to get the avatar id.
avatar = coze.files.upload(file=Path("/path/avatar.jpg"))

# Invoke the create interface to create a bot in the draft status.
bot = coze.bots.create(
    # The bot should exist under a space and your space id needs configuration.
    space_id="workspace id",
    # Bot name
    name="translator bot",
    # Bot avatar
    icon_file_id=avatar.id,
    # Bot system prompt
    prompt_info=BotPromptInfo(prompt="your are a translator, translate the following text from English to Chinese"),
)

# Call the publish interface to publish the bot on the api channel.
coze.bots.publish(bot_id=bot.bot_id)

# Call the coze.chat.stream method to create a chat. The create method is a streaming
# chat and will return a Chat Iterator. Developers should iterate the iterator to get
# chat event and handle them.
for event in coze.chat.stream(
    # The published bot's id
    bot_id=bot.bot_id,
    # biz user id, maybe random string
    user_id="user id",
    # user input
    additional_messages=[Message.build_user_question_text("chinese")],
):
    if (
        event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA
        and event.message.content.type == MessageContentType.TEXT
    ):
        print(event.message.content, end="")

发起对话

发起对话接口用于向指定智能体发起一次对话，支持在对话时添加对话的上下文消息，以便智能体基于历史消息做出合理的回复。开发者可以按需选择响应方式，即流式或非流式响应，响应方式决定了开发者获取智能体回复的方式。

流式响应：智能体在生成回复的同时，将回复消息以数据流的形式逐条发送给客户端。处理结束后，服务端会返回拼接后完整的智能体回复。详细说明可参考流式响应。
非流式响应：无论对话是否处理完毕，立即发送响应消息。开发者可以通过接口查看对话详情确认本次对话处理结束后，再调用查看对话消息详情接口查看模型回复等完整响应内容。详细说明可参考非流式响应。

本文档以流式响应为例，演示通过 API 方式和智能体对话相关示例代码。你也可以查看 Coze Python SDK 示例代码目录，查看发起对话接口的其他实现方式，例如非流式响应、对话中发送多模态内容等。
示例代码如下：

import os  # noqa

# Get an access_token through personal access token oroauth.
coze_api_token = os.getenv("COZE_API_TOKEN")

from cozepy import Coze, TokenAuth, Message, ChatStatus, MessageContentType, ChatEventType  # noqa

# Init the Coze client through the access_token.
coze = Coze(auth=TokenAuth(token=coze_api_token), base_url=COZE_CN_BASE_URL)

# Create a bot instance in Coze, copy the last number from the web link as the bot's ID.
bot_id = "bot id"
# The user id identifies the identity of a user. Developers can use a custom business ID
# or a random string.
user_id = "user id"

# Call the coze.chat.stream method to create a chat. The create method is a streaming
# chat and will return a Chat Iterator. Developers should iterate the iterator to get
# chat event and handle them.
for event in coze.chat.stream(
    bot_id=bot_id, user_id=user_id, additional_messages=[Message.build_user_question_text("How are you?")]
):
    if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
        message = event.message
        print(f"role={message.role}, content={message.content}")