本文档描述 Assistants API 的公共请求头和请求对象、公共响应头和响应对象信息。当您调用具体接口时，可进行参考。排查问题时，可附加公共响应头中的

公共请求头

参数	语义	是否必填	取值/类型	备注
Content-Type	Content-Type	是
Authorization	鉴权Token	是	string	格式为：Bearer xxxx 可以从千帆AppBuilder平台获取

请求对象

Thread

参数名称	类型	是否必须	备注
messages	array[Message]	否	本次对话追加的messages
metadata	map<string, string>	否	一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符，值的长度最多可为512个字符

Message

参数名称	类型	是否必须	备注
role	string	是	当前接口的角色 当作为请求内容时，role仅可以为user 当系统返回Meesage对象时，role可能为user或者assistant
content	string	是	消息内容
file_ids	array[string]	否	可选字段 例如图生文，或者retrieval有都有输入文件的需求，使用该字段 整体最多不超过10个文件
metadata	map<string, string>	否	一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符，值的长度最多可为512个字符

ModelParameters

参数名称	类型	是否必须	备注
chat_parameters	object	否	回复模型超参
+temperature	float	否	采样温度，较高的数值会使输出更随机。取值范围严格大于0，小于等于1，默认为0.8
+top_p	float	否	核采样方法的概率阈值，影响输出文本的多样性，较低的数值会使输出的文本更加多样性。取值范围大于等于0，小于等于1，默认为0.8
+penalty_score	float	否	惩罚分数，影响输出文本的多样性和质量，较高的数值使输出的文本更加多样性。取值范围大于等于1，小于等于2，默认为1.0
thought_parameters	object	否	思考模型超参
+temperature	float	否	采样温度，较高的数值会使输出更随机。取值范围严格大于0，小于等于1，默认为0.01
+top_p	float	否	核采样方法的概率阈值，影响输出文本的多样性，较低的数值会使输出的文本更加多样性。取值范围大于等于0，小于等于1，默认为0
+penalty_score	float	否	惩罚分数，影响输出文本的多样性和质量，较高的数值使输出的文本更加多样性。取值范围大于等于1，小于等于2，默认为1.0

Tool

参数名称	类型	是否必须	备注
type	string	是	枚举： file_retrieval: 知识库检索工具能够理解文档内容，支持用户针对文档内容的问答。 code_interpreter: 代码解释器, 代码解释器能够生成并执行代码，从而协助用户解决复杂问题，涵盖科学计算（包括普通数学计算题）、数据可视化、文件编辑处理（图片、PDF文档、视频、音频等）、文件格式转换（如WAV、MP3、text、SRT、PNG、jpg、MP4、GIF、MP3等）、数据分析&清洗&处理（文件以excel、csv格式为主）、机器学习&深度学习建模&自然语言处理等多个领域。 function: 支持fucntion call模式调用工具
function	Function	否	Function工具描述 仅当type为function 时需要且必须填写

Function

参数名称	类型	是否必须	备注
name	string	是	函数名 只允许数字、大小写字母和中划线和下划线，最大长度为64个字符。一次运行中唯一。
description	string	是	函数描述
parameters	object	是	函数请求参数，JSON Schema 格式，参考JSON Schema描述 在此基础上，新增约束如下： 1. 当某一字段为object类型时，properties字段必选，properties内可为空。 2. 当某一字段为array类型时，items字段必选，items内可为空。
responses	object	否	函数响应参数，JSON Schema 格式，参考JSON Schema描述 在此基础上，新增约束如下： 1. 当某一字段为object类型时，properties字段必选，properties内可为空。 2. 当某一字段为array类型时，items字段必选，items内可为空。

ToolOutput

参数名称	类型	是否必须	描述
tool_call_id	string	是	工具调用的ID。 来源于上一轮Run请求时required_action.id字段。
run_id	string	否	仅当非流式提交工具结果时使用 来源于上一轮Run请求时id字段
output	string	是	function call工具的输出。 如果是json，也需要对json序列化成string。

公共响应头

参数	语义	是否必填	取值/类型	备注
Content-Type	Content-Type	是	string
Content-Length	消息长度	是	string
Date	响应时间	是	string	使用IMF-fixdate格式
Statement	声明	是	string	值固定为 Al-generated
X-Appbuilder-Request-Id	请求id	是	string	唯一id，使用uuid4规则生成

响应对象

RunObject

字段	类型	描述
id	string	Run id
object	string	thread.run
assistant_id	string	对应assistant 的assistant_id
thread_id	string	对应thread 的 thread id
instructions	string	系统人设指令 概述Agent的整体功能和定位，需要它扮演一个什么样的"角色"。 1. 可以参考“你是xxx，你具有xx的特点，你可以做xxx，你需要满足用户xxx的需求”这样的结构。 2. 可以指定一些与能力边界相关要求（对于哪些类型的问题，无法回答） 示例： 你是一个音乐智能语音助手，可以通过调用技能的方式满足用户听音乐，看电影，追剧，刷短视频，听有声读物，信息问答等需求。你无法提供与政治和政策相关的内容；当用户提出与音乐、视频等娱乐信息不相关的问题时，你需要委婉地拒绝用户。
thought_instructions	string	思考规范 与业务逻辑和规则相关的指令。希望模型遵守的行为规范和准则、要求都尽可能清晰、详尽地在这里给出描述。包括但不限于： 在什么情况下需要调用什么工具；在调用xxx工具之前需要先调用xxx工具获取什么信息； xxx工具填参的要求和偏好；（优先设定在工具描述中，如果较复杂，可以在这里强调） 在模型判断结果无法满足用户时采取什么行动（换一个工具，或者改变参数调同一个工具，或是告知用户无法满足但努力基于当前信息提供结果，等）； 示例： 你需要遵循以下要求： 1.当用户给出特定的歌曲名，或者给出特定歌手，或者给出特定风格的音乐时，优先调用music_player工具 2.如果发现用户给出的是歌词，或者判断不出歌曲的名字、歌手时，请优先调用调用web_search工具获取歌名以及歌手，然后再去调用music_player工具 3.当web_search返回结果存在内容错误、质量差、不相关、资源陈旧以及信息量不足等情况时，你可以尝试优化查询词并重新调用web_search。
chat_instructions	string	回复规范 与模型最终给出的回复内容相关的指令。包括但不限于： 1. 语气偏好 2. 回复格式要求 3. 回复内容的丰富程度 4. 开头和结尾的形式要求，例如在结尾时需要向用户提问引导话题深入进行 示例： 1.你需要对用户的需求和问题给予耐心细致的回应；根据用户的输入，灵活调整对话内容，确保对话流畅自然。 2.当需要推荐电影给用户时，你需要按照以下格式输出：[电影名称](url)：推荐理由 3.可以在回复中适当插入emoji表情，提升亲切感
tools	array[Tool]	Assistant当前使用的所有的工具列表
file_ids	array[string]	Assistant当前使用的所有的文件列表
status	string	状态枚举： queued：当Run对象首次创建就会变成queued等待运行，正常情况下，很快就会变成in_progress状态。 in_progress：run正在执行中，这时候可以调用run_step接口来查看具体的执行状态。 requires_action：如果Assistant需要执行函数调用(function call)，就会转到这个状态，然后你必须按给定的参数调用指定的方法，并提交输出之后，run才可以继续运行，进入in_progress状态。 expired：当没有在expires_at之前提交函数调用输出，run将会过期。另外，如果在expires_at之前没获取输出，run也会变成expired状态。 cancelling：当调用cancel接口后，run就会变成cancelling，取消成功后就会变成cancelled状态 cancelled：Run已成功取消。 failed：运行失败，可以通过查看Run对象中的last_error对象来查看失败的原因。参考 LastError对象。 completed：执行完成，可以获取Assistant返回的消息了，也可以继续向Assistant提问了。
required_action	RequiredAction	有关function_call运行所需操作的详细信息。 如果不需要function_call调用，则将为null或不返回此字段。
last_error	LastError	错误信息。运行没有正常结束时包含的错误信息。 如果没有错误，则将为null或不返回此字段。
final_answer	FinalAnswer	仅在stream=false时存在 运行正常结束时包含message结果。 如果没有正常结束，则将为null或不返回此字段。
created_at	integer	创建时间戳
started_at	integer	开始运行时间戳。
expired_at	integer	实际过期的时间戳。以status=expired状态结束时记录相关的时间戳。
cancelled_at	integer	取消时间戳。以status=cancelled状态结束时记录相关的时间戳。
failed_at	integer	失败时间戳。以status=failed状态结束时记录相关的时间戳。
completed_at	integer	成功时间戳。以status=completed状态结束时记录相关的时间戳。

RunStepObject

字段	类型	描述
id	string	Run Step id
object	string	thread.run.step
assistant_id	string	对应assistant 的assistant_id
thread_id	string	对应thread 的 thread_id
run_id	string	对应run的id
status	string	状态枚举：同上
created_at	integer	创建时间戳
started_at	integer	开始运行时间戳。
expired_at	integer	实际过期的时间戳。以status=expired状态结束时记录相关的时间戳。
cancelled_at	integer	取消时间戳。以status=cancelled状态结束时记录相关的时间戳。
failed_at	integer	失败时间戳。以status=failed状态结束时记录相关的时间戳。
completed_at	integer	成功时间戳。以status=completed状态结束时记录相关的时间戳。
last_error	LastError	错误信息。运行没有正常结束时包含的错误信息。 如果没有错误，则将为null或不返回此字段。
type	string	固定为null
step_detail	StepDetail	本次step的详情

StepDetail

字段	类型	描述
type	string	枚举： message_creation：run运行过程中，产生了大模型的最终消息时，将message内容通知调用方 tool_calls：run运行中，触发了function_call的requires_action动作时，将tool_calls的信息（含tool_calls_id，arguments等）通知调用方
message_creation	object	当type为message_creation时有值
+message_id	string	消息ID
tool_calls	array[object]	当type为tool_calls时有值 function_call的事件，注意这里是个array
+id	string	工具调用的ID
+type	string	固定为function
+function	object	function_call参数
++name	string	function名
++arguments	string	function调用参数
++output	string	function输出

ErrorResponse

字段	类型	描述
error	object	公共报错信息
+code	integer	错误码
+message	string	错误描述
+type	string	错误类型
+param	string	错误参数

RequiredAction

字段	类型	描述
type	string	固定submit_tool_outputs
submit_tool_outputs	object	有关此运行继续所需的工具输出的详细信息。
+tool_calls	array [object]	相关工具调用的列表。
++id	string	工具调用的ID。当您在中使用提交工具输出来运行端点提交工具输出时，必须引用此ID。
++type	string	需要输出的工具调用的类型。就目前而言，这始终是函数。
++function	object	函数定义。
+++name	string	函数的名称
+++arguments	string	模型希望您传递给函数的参数，需要是一个json dump string

FinalAnswer

字段	类型	描述
type	string	固定为message
message	object
+message_id	string	message对应id
+content	Content	message内容

Content

字段	类型	描述
type	string	当前固定为text
text	object	若type为text，则此处有值
+value	string	正文

LastError

字段	类型	描述
code	string	错误码
message	string	错误描述