教程
OpenAI Assistants API 8月26日关闭：迁移 Responses API 完整指南
OpenAI 已明确宣布 Assistants API 将于 2026 年 8 月 26 日关闭。对于仍在使用 Assistants、Threads、Runs、Run Steps、File Search 或 Function Calling 的应用，这已经不是“以后有空再迁移”的技术债，而是必须在截止日期前完成的生产迁移。新的 Responses API 已达到 Assistants API 的功能对等，并进一步支持 Conversations、MCP、Computer Use、Deep Research 等新能力。本文从概念映射、数据迁移、会话状态、工具调用、Prompt 版本、File Search、灰度发布和回滚等方面给出一套可执行迁移路线。
# OpenAI Assistants API 8月26日关闭：迁移 Responses API 完整指南
## 文章摘要
OpenAI 已明确宣布 Assistants API 将于 2026 年 8 月 26 日关闭。对于仍在使用 Assistants、Threads、Runs、Run Steps、File Search 或 Function Calling 的应用，这已经不是“以后有空再迁移”的技术债，而是必须在截止日期前完成的生产迁移。新的 Responses API 已达到 Assistants API 的功能对等，并进一步支持 Conversations、MCP、Computer Use、Deep Research 等新能力。本文从概念映射、数据迁移、会话状态、工具调用、Prompt 版本、File Search、灰度发布和回滚等方面给出一套可执行迁移路线。
---
## 一、为什么现在必须处理？
OpenAI 官方已经明确：
> Assistants API 将于 2026 年 8 月 26 日关闭。
如果代码中仍出现：
```python
client.beta.assistants
client.beta.threads
client.beta.threads.runs
```
就应该立即进入迁移检查。
这次变化并不是简单替换 Endpoint，而是整个 Agent 状态模型发生了变化。
## 二、Assistants API 与 Responses API 的核心映射
| Assistants API | Responses API 体系 |
|---|---|
| Assistants | Prompts / 应用配置 |
| Threads | Conversations |
| Runs | Responses |
| Run Steps | Items |
这张表是整个迁移的核心。
## 三、Assistant 为什么变成 Prompt？
旧 Assistant 通常包含：
```text
model
instructions
tools
metadata
```
新的体系更强调行为配置与运行状态分离。
Prompt 用来定义：
- Instructions；
- Model；
- Tools；
- Structured Output；
- 默认参数。
应用代码负责：
- 会话；
- 工具循环；
- Retry；
- History；
- Orchestration。
这样做的价值是可以版本化、Diff、回滚和 A/B，也更容易让同一行为定义跨 Responses 与 Realtime 复用。
## 四、Threads 为什么变成 Conversations？
旧 Thread 的核心是存消息。
Conversation 更通用，可以存储 Items，例如：
- 用户消息；
- Assistant 消息；
- Tool Call；
- Tool Result；
- 其他运行数据。
因此新的状态模型更接近：
```text
Conversation
├── user message
├── assistant item
├── function call
├── function output
├── assistant item
└── ...
```
而不是单纯的消息列表。
## 五、Runs 为什么变成 Responses？
旧流程：
```text
Thread
↓
Run
↓
等待
↓
Required Action
↓
Submit Tool Output
↓
继续 Run
```
新 Responses API 更直接：
```text
Input Items
↓
Response
↓
Output Items
```
如果需要工具：
```text
Response
↓
Tool Call Item
↓
应用执行工具
↓
Tool Output Item
↓
继续 Response
```
开发者需要更明确地控制 Tool Loop。
## 六、第一步：盘点所有 Assistant
不要直接全局搜索然后机械替换。
建议先建立清单：
```text
assistant_id
用途
model
instructions
tools
file_search
functions
metadata
流量
业务负责人
风险等级
```
先迁移低风险、低流量，再迁移核心业务。
## 七、第二步：把 Instructions 和 Tools 抽离成版本配置
推荐结构：
```text
prompts/
├── support/
│ ├── v1.yaml
│ ├── v2.yaml
│ └── evals.jsonl
├── report/
└── internal/
```
每次部署至少保存：
```text
prompt_version
model
tool_schema_version
knowledge_version
```
否则出现问题后无法复现。
## 八、第三步：Thread ID 如何迁移？
旧系统数据库可能保存：
```text
user_id
thread_id
```
新系统需要建立：
```text
user_id
conversation_id
```
不要直接把 Thread ID 当 Conversation ID。
可以增加映射表：
```sql
CREATE TABLE ai_sessions (
user_id VARCHAR(64),
old_thread_id VARCHAR(128),
conversation_id VARCHAR(128),
migration_status VARCHAR(32),
migrated_at TIMESTAMP
);
```
迁移期间让两类 ID 同时存在。
## 九、历史消息怎么办？
### 历史不重要
从迁移日开始新建 Conversation。
### 必须保留完整历史
迁移 Role、Content、Timestamp、附件和重要 Tool Output。
### 历史很长
不要全部迁移，可采用：
```text
最近 N 轮原始消息
+
历史摘要
+
关键用户事实
+
任务状态
```
否则成本和上下文污染都会上升。
## 十、第四步：重新实现 Tool Loop
建议设置硬限制：
```python
MAX_TOOL_ROUNDS = 8
for round_no in range(MAX_TOOL_ROUNDS):
response = create_response(...)
tool_calls = extract_tool_calls(response)
if not tool_calls:
return final_answer(response)
outputs = []
for call in tool_calls:
outputs.append(execute_tool_safely(call))
append_tool_outputs(outputs)
```
必须限制：
- max_tool_rounds；
- max_tool_calls；
- timeout；
- cost_budget。
否则 Agent 可能循环。
## 十一、工具执行必须继续由业务层控制
推荐流程：
```text
用户权限
↓
工具权限
↓
参数校验
↓
业务规则
↓
是否需要确认
↓
执行
↓
结果脱敏
↓
返回模型
```
模型只负责提出调用，业务系统负责是否允许调用。
## 十二、第五步：File Search 如何迁移？
如果应用大量依赖知识库，需要重点回归：
- Vector Store；
- 文件同步；
- 检索结果；
- 引用；
- 权限。
不要只验证“能搜到东西”。
应该建立固定问题集并检查：
```text
Recall@K
Citation Accuracy
Faithfulness
No-answer Rate
Permission Accuracy
```
尤其测试同名文件、旧版本、删除文件、超大 PDF、表格、多语言和无答案问题。
## 十三、第六步：不要直接把生产流量 100% 切过去
### 阶段 1：Shadow
生产仍走 Assistants，同时把相同请求发送到 Responses，但不返回用户。
比较：
- 答案质量；
- 工具调用；
- 成本；
- 延迟；
- 错误。
### 阶段 2：内部用户
员工、测试客户、内部客服先用 Responses。
### 阶段 3：1%
```text
1% Responses
99% Assistants
```
### 阶段 4：10%
观察 Error Rate、Success Rate、Tool Failure 和 User Feedback。
### 阶段 5：50%
确认无重大回归。
### 阶段 6：100%
短期保留旧实现回滚能力。
## 十四、用 Feature Flag 保证可回滚
例如：
```text
AI_RUNTIME=assistants
```
或：
```text
AI_RUNTIME=responses
```
不要采用“部署新代码、删除旧实现、祈祷没问题”的方式。
## 十五、迁移时最容易出现哪些 Bug？
### 对话上下文丢失
每次请求错误创建新 Conversation。
### Tool Output 没有正确写回
Agent 反复请求同一个工具。
### Function Schema 变化
Structured Output 或参数验证出现差异。
### 附件丢失
特别是图片、PDF 与 File Search 文件。
### 旧 Run Polling 逻辑残留
导致新实现反而更复杂。
### Retry 重复执行写操作
第一次成功但网络超时，重试后产生重复订单、重复工单或重复邮件。
## 十六、建议加入幂等设计
对于创建订单、工单、邮件、支付、数据库修改和发布内容，最好带：
```text
request_id
operation_id
idempotency_key
```
服务端保证同一个 `idempotency_key` 只执行一次。
这是所有生产 Agent 都需要的能力，不只是这次迁移。
## 十七、迁移后可以获得哪些新能力？
Responses API 可以进一步连接：
- Web Search；
- File Search；
- MCP；
- Computer Use；
- Function Tools；
- Deep Research 相关工作流。
因此这次迁移不应该只是“把旧 API 勉强继续跑起来”，而应该借机整理 Agent 架构。
## 十八、迁移前必须做 Evals
至少建立 50～200 个真实任务。
例如客服：
```text
订单查询
退款规则
发票
物流
异常状态
无答案
越权请求
恶意提示
```
每个任务记录：
```text
expected_behavior
required_tools
forbidden_tools
reference_answer
risk_level
```
客观比较 Assistants 与 Responses。
## 十九、推荐的上线门禁
可以设置：
```text
任务成功率不得下降 > 2%
高风险错误 = 0
越权调用 = 0
重复写操作 = 0
引用准确率不得下降
P95 延迟不得上升 > 20%
平均成功任务成本不得上升 > 15%
```
任何关键门禁不满足，都不应直接切 100%。
## 二十、8 月 26 日前的压缩时间表
### 第 1 天
盘点 Assistant，建立风险等级，搭建 Responses 基础封装。
### 第 2～3 天
迁移 Prompt、Conversation、Tool Loop 和 File Search。
### 第 4 天
建立 Evals，跑完整回归。
### 第 5 天
Shadow Traffic。
### 第 6 天
内部和 1%。
### 第 7 天
10%～50%。
### 第 8 天
100%，保留 Feature Flag。
不要把最后一天留给首次生产切换。
## 二十一、推荐的代码结构
```text
app/
├── ai/
│ ├── gateway.py
│ ├── responses_client.py
│ ├── conversations.py
│ ├── tool_loop.py
│ ├── tools/
│ ├── prompts/
│ └── evals/
├── features/
└── observability/
```
业务代码不应该散落 `client.responses.create(...)`，而应该统一经过 `ai_gateway.run(...)`。
这样以后换模型、Prompt、服务层和观测方式都会容易很多。
## 二十二、迁移完成后还要检查什么？
### 代码
- 是否还有 `beta.assistants`；
- 是否还有 `beta.threads`；
- 是否还有旧 Run Polling。
### 数据
- Thread 映射是否完整；
- Conversation 是否正确；
- 附件是否可访问。
### 工具
- 参数 Schema；
- 幂等；
- 权限；
- Timeout；
- Retry。
### 运维
- Trace；
- Token；
- Cost；
- Error；
- Latency；
- Tool Loop。
### 安全
- Prompt Injection；
- 越权；
- 敏感数据；
- 外部工具；
- 用户确认。
## 总结
Assistants API 在 2026 年 8 月 26 日关闭，这次迁移已经进入最后窗口。
最重要的概念变化是：
```text
Assistants → Prompts
Threads → Conversations
Runs → Responses
Run Steps → Items
```
但真正的生产迁移远不止替换四个名词。
还需要重新检查 Conversation、Tool Loop、File Search、Prompt Version、Retry、Idempotency、Evals、Shadow Traffic、Feature Flag 和 Observability。
最稳妥的策略不是 8 月 25 日晚上一次性切换，而是今天开始双轨运行，用真实流量逐步验证。
想继续了解 OpenAI API、Agent 架构、MCP 和企业 AI 工程实践，可以访问 **智元选**：https://www.zyentorpicks.com/。我们会持续整理真正需要开发者立即处理的模型与平台变化。