我们正从 Assistants API 转向新的 Responses API 以获得更简单、更灵活的心智模型。
Responses 更简单——发送输入项并获取返回的输出项。借助 Responses API，您还能获得更好的性能以及新功能，例如 深度研究, MCP，且 计算机使用。此更改还允许您管理对话，而不是来回传递 previous_response_id.
有哪些变化？
| 之前 | 现在 | 为什么？ |
|---|---|---|
Assistants | Prompts | 提示词保存了配置（模型、工具、指令），且更易于进行版本控制和更新 |
Threads | Conversations | 项流而非仅仅是消息 |
Runs | Responses | Responses 发送输入项或使用对话对象并接收输出项；工具调用循环由显式管理 |
Run steps | Items | 通用化对象——可以是消息、工具调用、输出等 |
From assistants to prompts
Assistants 是持久化的 API 对象，捆绑了模型选择、指令和工具声明——完全通过 API 创建和管理。它们的替代品提示词，只能在仪表板中创建，您可以在开发产品时对其进行版本控制。
这有何帮助
- 可移植性与版本控制: 您可以快照、审查、对比和回滚提示词规格。您还可以对提示词进行版本控制，以便您的代码只需指向最新版本。
- 关注点分离: 您的应用程序代码现在负责处理编排（历史记录修剪、工具循环、重试），而您的提示词则专注于高层次的行为和约束（系统引导、工具可用性、结构化输出架构、默认温度值）。
- Realtime 兼容性: 当您通过 Realtime API 连接时，可以复用相同的提示词配置，从而在聊天、流式传输和低延迟交互会话中获得统一的行为定义。
- 工具与输出一致性: 使用提示词时，您启动的每一个 Responses 或 Realtime 会话都会继承一致的规范，因为提示词封装了工具架构和结构化输出的预期。
实际迁移步骤
- 识别每个现有 Assistant 的 指令 + 工具 bundle.
- 在仪表板中，将该捆绑配置重新创建为一个命名的提示词。
- 将提示词 ID（或其导出的配置规格）存储在源代码控制中，以便应用程序代码可以引用一个稳定的标识符。
- 在推出期间，通过交换提示词 ID 来进行 A/B 测试——无需通过编程方式创建或删除 assistant 对象。
将提示词视为一个 版本化的行为配置文件 将其插入到 Responses 或 Realtime API 中。
From threads to conversations
Thread（线程）是存储在服务器端的消息集合。Threads 只能 存储消息。Conversations（对话）存储项，其中可以包括消息、工具调用、工具输出和其他数据。
请求示例
Thread 对象
1
2
3
4
thread = openai.beta.threads.create(
messages=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}],
metadata={"user_id": "peter_le_fleur"},
)Conversation 对象
1
2
3
4
conversation = openai.conversations.create(
items=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}],
metadata={"user_id": "peter_le_fleur"},
)响应示例
Thread 对象
1
2
3
4
5
6
7
8
9
{
"id": "thread_CrXtCzcyEQbkAcXuNmVSKFs1",
"object": "thread",
"created_at": 1752855924,
"metadata": {
"user_id": "peter_le_fleur"
},
"tool_resources": {}
}Conversation 对象
1
2
3
4
5
6
7
8
{
"id": "conv_68542dc602388199a30af27d040cefd4087a04b576bfeb24",
"object": "conversation",
"created_at": 1752855924,
"metadata": {
"user_id": "peter_le_fleur"
}
}From runs to responses
Run（运行）是针对 threads 执行的异步过程。请参见下面的示例。Responses 更简单：提供一组要执行的输入项，然后返回一个输出项列表。
Responses 被设计为可独立使用，但您也可以将它们与提示词和对话对象结合使用，以存储上下文和配置。
请求示例
Run 对象
1
2
3
4
5
6
7
8
thread_id = "thread_CrXtCzcyEQbkAcXuNmVSKFs1"
assistant_id = "asst_8fVY45hU3IM6creFkVi5MBKB"
run = openai.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant.id)
while run.status in ("queued", "in_progress"):
time.sleep(1)
run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)Response 对象
1
2
3
4
5
response = openai.responses.create(
model="gpt-4.1",
input=[{"role": "user", "content": "What are the 5 Ds of dodgeball?"}]
conversation: "conv_689667905b048191b4740501625afd940c7533ace33a2dab"
)响应示例
Run 对象
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
"id": "run_FKIpcs5ECSwuCmehBqsqkORj",
"assistant_id": "asst_8fVY45hU3IM6creFkVi5MBKB",
"cancelled_at": null,
"completed_at": 1752857327,
"created_at": 1752857322,
"expires_at": null,
"failed_at": null,
"incomplete_details": null,
"instructions": null,
"last_error": null,
"max_completion_tokens": null,
"max_prompt_tokens": null,
"metadata": {},
"model": "gpt-4.1",
"object": "thread.run",
"parallel_tool_calls": true,
"required_action": null,
"response_format": "auto",
"started_at": 1752857324,
"status": "completed",
"thread_id": "thread_CrXtCzcyEQbkAcXuNmVSKFs1",
"tool_choice": "auto",
"tools": [],
"truncation_strategy": {
"type": "auto",
"last_messages": null
},
"usage": {
"completion_tokens": 130,
"prompt_tokens": 34,
"total_tokens": 164,
"prompt_token_details": {
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0
}
},
"temperature": 1.0,
"top_p": 1.0,
"tool_resources": {},
"reasoning_effort": null
}Response 对象
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
"id": "resp_687a7b53036c819baad6012d58b39bcb074adcd9e24850fc",
"created_at": 1752857427,
"conversation": {
"id": "conv_689667905b048191b4740501625afd940c7533ace33a2dab"
},
"error": null,
"incomplete_details": null,
"instructions": null,
"metadata": {},
"model": "gpt-4.1-2025-04-14",
"object": "response",
"output": [
{
"id": "msg_687a7b542948819ba79e77e14791ef83074adcd9e24850fc",
"content": [
{
"annotations": [],
"text": "The \"5 Ds of Dodgeball\" are a humorous set of rules made famous by the 2004 comedy film **\"Dodgeball: A True Underdog Story.\"** In the movie, dodgeball coach Patches O’Houlihan teaches these basics to his team. The **5 Ds** are:
1. **Dodge**
2. **Duck**
3. **Dip**
4. **Dive**
5. **Dodge** (yes, dodge is listed twice for emphasis!)
In summary:
> **“If you can dodge a wrench, you can dodge a ball!”**
These 5 Ds are not official competitive rules, but have become a fun and memorable pop culture reference for the sport of dodgeball.",
"type": "output_text",
"logprobs": []
}
],
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"temperature": 1.0,
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"background": false,
"max_output_tokens": null,
"previous_response_id": null,
"reasoning": {
"effort": null,
"generate_summary": null,
"summary": null
},
"service_tier": "scale",
"status": "completed",
"text": {
"format": {
"type": "text"
}
},
"truncation": "disabled",
"usage": {
"input_tokens": 17,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 150,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 167
},
"user": null,
"max_tool_calls": null,
"store": true,
"top_logprobs": 0
}迁移您的集成
请按照以下迁移步骤，从 Assistants API 迁移至 Responses API，且不会失去任何功能支持。
1. 从您的 Assistant 创建提示词
- 识别您的应用程序中最重要的 assistant 对象。
- 在仪表板中找到这些对象并点击
Create prompt.
这将从每个现有的 assistant 对象中创建出一个提示词对象。
2. 将新的用户聊天迁移至对话和响应
我们不会提供用于将 Threads 迁移至 Conversations 的自动化工具。我们建议改为将新的用户线程迁移至对话，并根据需要对旧线程进行回填。
以下是一个关于如何回填线程的示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
thread_id = "thread_EIpHrTAVe0OzoLQg3TXfvrkG"
for page in openai.beta.threads.messages.list(thread_id=thread_id, order="asc").iter_pages():
messages += page.data
items = []
for m in messages:
item = {"role": m.role}
item_content = []
for content in m.content:
match content.type:
case "text":
item_content_type = "input_text" if m.role == "user" else "output_text"
item_content += [{"type": item_content_type, "text": content.text.value}]
case "image_url":
item_content + [
{
"type": "input_image",
"image_url": content.image_url.url,
"detail": content.image_url.detail,
}
]
item |= {"content": item_content}
items.append(item)
# create a conversation with your converted items
conversation = openai.conversations.create(items=items)完整示例比较
以下是一些使用 Assistants API 和 Responses API 的简单集成示例，以便您进行比较。
用户聊天应用
Assistants API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
thread = openai.threads.create()
@app.post("/messages")
async def message(message: Message):
openai.beta.threads.messages.create(
role="user",
content=message.content
)
run = openai.beta.threads.runs.create(
assistant_id=os.getenv("ASSISTANT_ID"),
thread_id=thread.id
)
while run.status in ("queued", "in_progress"):
await asyncio.sleep(1)
run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
messages = openai.beta.threads.messages.list(
order="desc", limit=1, thread_id=thread.id
)
return { "content": messages[-1].content }Responses API
1
2
3
4
5
6
7
8
9
10
conversation = openai.conversations.create()
@app.post("/messages")
async def message(message: Message):
response = openai.responses.create(
prompt={ "id": os.getenv("PROMPT_ID") },
input=[{ "role": "user", "content": message.content }]
)
return { "content": response.output_text }'