百宝箱开放平台 ✖️ 智能体调用 ✖️ Python SDK

支付宝小程序云

785人浏览 · 2025-09-29 15:02:29

支付宝小程序云 · 2025-09-29 15:02:29 发布

Python SDK

百宝箱提供 Python SDK，开发者可以通过调用 SDK 将百宝箱提供的各项开放能力集成到自有的应用中。

前提条件

在调用本服务前，请先完成应用的发布。

环境准备

百宝箱 Python SDK 适用于 Python3.6 及以上版本。安装 Python SDK 前，建议执行以下命令确认你已经安装了 3.6 及以上版本的 Python。

# 查看 Python 版本  
python --version

# 回显信息显示已安装 3.8.2 版本
Python 3.8.2

安装 SDK

开发者可以通过 pip 安装 TboxSDK，命令示例如下。

pip install tboxsdk

调用 SDK

1. 调用对话型智能体

from tboxsdk.tbox import TboxClient

def stream_chat():
    """对话型应用请参考以下调用方式"""
    tbox = TboxClient(authorization="{your_token}")
    response = tbox.chat(app_id="{your_app_id}", query="你好", user_id="{user_id}")
    for chunk in response:
        print(chunk)

if __name__ == "__main__":
    stream_chat()

其中，各参数说明如下。

参数名	必填	类型	说明	示例
app_id	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	202506e******00450562
user_id	是	String	用户 ID，指使用智能体的用户 ID，需开发者自行定义与维护。请尽量使用 OAID 或手机号，百宝箱会根据此信息帮助您构建用户画像。	-
conversation_id	否	String	会话id，用于用户多轮对话时组装上下文信息。	首次对话时无需传入，多轮对话时，按照SDK中之前返回的conversationId内容传入。
client_properties	否	dict	系统及环境变量参数。如果你在对话型工作流应用中，开启了“系统及环境信息”中的变量开关，操作如下：你可以将对应的参数传入到 client_properties 中。每个变量对应的key值如下：用户id：user_id 触发时间：time 坐标：pos 经度：pos_lng 纬度：pos_lat 运行环境：runtime_env UA：user_agent 附加数据：_biz_params
files	否	List<File>	文件列表，用于在对话中提供多模态（文档、图片、音频及视频）数据。说明：使用文件上传能力前，请先为智能体配置具有文件处理能力的大模型或插件。	-
search_engine	否	Boolean	本次对话是否使用联网搜索。说明：使用联网搜索前，需要先开启智能体对话配置中的联网搜索开关。 True：使用联网搜索； False：默认值，不使用联网搜索。	False
stream	否	Boolean	是否流式响应，默认True	True

1.1. 创建会话

from tboxsdk.tbox import TboxClient

def create_conversation():
    tbox = TboxClient(authorization="{your_token}")
    create_response = tbox_client.create_conversation(app_id="202411APWG5400162068")
    if create_response.get("errorCode") == "0":
        conversation_id = create_response.get("data")
        print(f"创建会话成功，会话ID: {conversation_id}")

if __name__ == "__main__":
    create_conversation()

其中，各参数说明如下。

参数名	必填	类型	说明	示例
app_id	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	202506e******00450562

1.2. 查询会话列表

from tboxsdk.tbox import TboxClient

def get_conversations():
    tbox = TboxClient(authorization="{your_token}")
    response = tbox_client.get_conversations(app_id="202411APWG5400162068")
    print(f"--------------------------------------------------------")
    print(f"response: {response}")
    print(f"--------------------------------------------------------")
    
    if response.get("errorCode") == "0":
        conversations = response.get("data", {}).get("conversations", [])
        print(f"找到 {len(conversations)} 个会话")
        
        for conv in conversations:
            print(f"会话ID: {conv['conversationId']}")
            print(f"用户ID: {conv['userId']}")
            print(f"渠道: {conv['source']}")
            print(f"创建时间: {conv['createAt']}")
            print("---")

if __name__ == "__main__":
    get_conversations()

其中，各参数说明如下。

参数名	必填	类型	说明	示例
app_id	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	202506e******00450562
user_id	否	String	用户ID，发起对话时指定，需要在智能体内唯一。不传返回全部用户的会话列表	test_user_zs
source	否	Enum<String>	对话渠道，用于筛选指定渠道的对话，不传值将返回所有渠道发生的会话动作。 AGENT_SDK：SDK 渠道 OPENAPI：OpenAPI 渠道 IOT_SDK：IOT SDK 渠道	AGENT_SDK
page_num	否	Integer	分页页码，从 1 开始，默认为 1	1
page_size	否	Integer	分页条数，默认为 10，最大 50	10
sort_order	否	String	会话列表排序方式，默认 DESC ASC：按创建时间升序排序，最早创建的会话排在最前返回； DESC：按创建时间降序排序，最近创建的会话排在最前返回	DESC

1.3. 查询会话消息

from tboxsdk.tbox import TboxClient

def get_messages():
    tbox = TboxClient(authorization="{your_token}")
    # 使用一个测试用的conversationId，你需要替换为实际可用的conversationId
    response = tbox_client.get_messages(conversation_id="{conversation_id}")
    print(f"--------------------------------------------------------")
    print(f"response: {response}")
    print(f"--------------------------------------------------------")
    
    if response.get("errorCode") == "0":
        messages = response.get("data", {}).get("messages", [])
        print(f"找到 {len(messages)} 条消息")
        
        for msg in messages:
            print(f"消息ID: {msg['messageId']}")
            print(f"会话ID: {msg['conversationId']}")
            print(f"智能体ID: {msg['appId']}")
            print(f"用户问题: {msg['query']}")
            print(f"状态: {msg['status']}")
            print(f"创建时间: {msg['createAt']}")
            print(f"更新时间: {msg['updateAt']}")
            
            # 显示回答
            answers = msg.get('answers', [])
            print(f"回答数量: {len(answers)}")
            for answer in answers:
                print(f"  - 流水线: {answer.get('lane')}")
                print(f"  - 媒体类型: {answer.get('mediaType')}")
                print(f"  - 文本内容: {answer.get('text')}")
                if answer.get('url'):
                    print(f"  - 图片链接: {answer.get('url')}")
            
            # 显示文件
            files = msg.get('files', [])
            print(f"文件数量: {len(files)}")
            for file in files:
                print(f"  - 文件ID: {file.get('fileId')}")
                print(f"  - 文件类型: {file.get('type')}")
                print(f"  - 预览链接: {file.get('url')}")
            
            print("---")

if __name__ == "__main__":
    get_messages()

其中，各参数说明如下。

参数名	必填	类型	说明	示例
conversation_id	是	String	会话 ID	-
page_num	否	Integer	分页页码，从 1 开始，默认为 1	1
page_size	否	Integer	分页条数，默认为 10，最大 50	10
sort_order	否	String	会话列表排序方式，默认 DESC ASC：按创建时间升序排序，最早创建的会话排在最前返回； DESC：按创建时间降序排序，最近创建的会话排在最前返回	DESC

2. 调用生成型智能体

开发者可以通过下述示例代码，实现生成型智能体的调用。

from tboxsdk.tbox import TboxClient

def stream_completion():
    """内容生成型应用请参考以下调用方式"""
    tbox = TboxClient(authorization="{your_token}")
    response = tbox.completion(app_id="{your_app_id}", inputs={"title": "太阳"}, user_id="{user_id}")
    for chunk in response:
        print(chunk)

if __name__ == "__main__":
    stream_completion()

其中，各参数说明如下。

参数名	必填	类型	说明	示例
app_id	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	202506e******00450562
user_id	是	String	用户 ID，指使用智能体的用户 ID，需开发者自行定义与维护。请尽量使用 OAID 或手机号，百宝箱会根据此信息帮助您构建用户画像。	-
conversation_id	否	String	会话id，用于用户多轮对话时组装上下文信息。	首次对话时无需传入，多轮对话时，按照SDK中之前返回的conversationId内容传入。
inputs	否	dict	如果您的应用中有自定义参数，需要填入对应的key-value值，参考示例。	如上图，key填写为title，value填写为您想要的主题内容。
client_properties	否	dict	系统及环境变量参数。传入的key值请参考示例。	如果你在对话型工作流应用中，开启了“系统及环境信息”中的变量开关（示例如下）你可以将对应的参数传入到clientProperties中。每个变量对应的key值如下：用户id - user_id 触发时间 - time 坐标 - pos 经度 - pos_lng 纬度 - pos_lat AOI - 待废弃参数，请不要使用运行环境 - runtime_env UA - user_agent 附加数据 - _biz_params
files	否	List<File>	文件列表，用于在对话中提供多模态（文档、图片、音频及视频）数据。说明：使用文件上传能力前，请先为智能体配置具有文件处理能力的大模型或插件。	-
with_meta	否	Boolean	是否接收百宝箱返回的meta信息，默认False	False
stream	否	Boolean	是否流式响应，默认True	True

3. 上传文件

from tboxsdk.tbox import TboxClient

def upload_file():
    tbox_client = TboxClient(authorization="{your_token}")
    response = tbox_client.upload_file(file_path="{file_path}")
    print(f"--------------------------------------------------------")
    print(f"response: {response}")
    print(f"--------------------------------------------------------")
    
    if response.get("errorCode") == "0":
        file_id = response.get("data", "")
        print(f"文件ID: {file_id}")

if __name__ == "__main__":
    upload_file()

其中，各参数说明如下。