🧠 OpenAI Agent 工具全面开发者指南
从 RAG 到 Computer Use ------ 深入解析全新 Responses API
I. 导言：新的 Agent 范式与 Responses API
A. 定义："工具使用"（Tool Use）
工具使用 (Tool Use) 是一个核心范式，标志着大型语言模型（LLM）从被动的文本生成器向主动"代理"（Agent）的转变。
模型不再局限于已训练的知识，而是通过调用外部工具与世界交互，例如：
- 执行代码
- 访问专有知识库
- 调用系统与服务
这构成了"可执行任务"的智能代理的技术基础。
B. 重大转变：从 Assistants API 到 Responses API
核心变化：
- Assistants API：早期实验性产物，通过 Assistant/Thread 管理持久化对象，结构相对僵化。
- Responses API ：为 GPT-5 等"推理模型"设计，具备更高灵活性与性能，默认即 Agentic（agentic by default）。
安全背景：
- Assistants API 的向量存储曾被恶意利用（如 SesameOP 事件），促使 OpenAI 向更安全的 Responses API 迁移。
结论：
Responses API 是未来标准接口，结合安全、性能与推理能力，为构建智能 Agent 提供统一平台。
C. 内置 Agent 工具生态系统
OpenAI 现提供"代理平台即服务（PaaS for Agents）"，开发者可直接调用内置托管工具，而无需自行搭建 RAG 管道或执行环境。
核心内置工具包括：
| 工具 | 功能 |
|---|---|
file_search |
文件语义搜索 / 私有知识检索 |
code_interpreter |
执行 Python 代码与可视化 |
web_search |
实时网页搜索 |
image_generation |
图像生成与优化提示 |
computer_use |
与计算机 GUI 交互 |
remote MCP servers |
连接外部系统服务 |
II. 基石：检索增强生成（RAG）
A. 概念
RAG（Retrieval-Augmented Generation）
在生成（Generate）答案前，先检索（Retrieve）相关信息来增强（Augment）提示。
RAG 解决了 LLM 的"上下文记忆问题"，相当于为模型提供"开卷参考书"，让其回答更具实时性和专业性。
B. 通用 RAG 工作流程
- 摄入与分块（Ingestion & Chunking）
将文件分解成语义块（chunk）。 - 嵌入（Embedding）
通过向量化模型将文本转为高维向量。 - 存储（Storage）
向量存入数据库（vector store）。 - 查询（Querying）
将用户问题向量化。 - 检索（Retrieval）
搜索语义相似的内容块。 - 生成（Generation）
将检索结果注入提示中生成增强回答。
III. 深度解析：file_search（文件搜索）
A. 定义
托管式 RAG 工具，允许模型在上传文件中通过语义或关键词搜索查找相关信息。
B. 知识库构建步骤
-
上传文件：
pythonclient.files.create(purpose="assistants") -
创建向量存储：
pythonclient.vector_stores.create() -
关联文件与向量库：
pythonclient.vector_stores.files.create() -
检查状态：
等待状态变为
"completed"即可使用。
C. 查询机制
在 client.responses.create() 中：
json
{
"tools": [{"type": "file_search"}],
"tool_config": {"vector_store_ids": ["vs_123"]}
}返回内容包括：
file_search_call：检索元数据message：模型回答与文件引用（file_citation）
D. 内部机制（自动优化）
| 功能 | 描述 |
|---|---|
| 查询重写 | 自动优化用户问题以提升检索效果 |
| 查询分解 | 将复杂查询拆分并并行执行 |
| 混合搜索 | 同时进行关键词与语义搜索 |
| 结果重排 | 自动 rerank 提升相关性 |
E. 自定义控制
filters：按元数据过滤max_num_results：控制返回数量include：返回详细搜索结果
IV. 深度解析：code_interpreter（代码解释器）
A. 功能
在安全沙盒中执行 Python 代码，支持数据分析、可视化与文件生成。
B. 应用场景
- 迭代式问题解决：自动调试循环
- 文件输入：支持
.csv,.json,.pdf,.xlsx等 - 文件输出：生成报告、图表（返回
file_id）
C. 特性
- 会话状态保持（约 1 小时）
- 输出管理：需手动下载生成文件
- 沙盒环境：完全托管，无需额外部署
V. 深度解析：web_search（网页搜索）
A. 功能与激活
让模型访问最新互联网信息。
激活方式：
json
{"tools": [{"type": "web_search"}]}B. 三种模式
| 模式 | 特征 | 适用场景 |
|---|---|---|
| 非推理搜索 | 快速返回结果 | 事实核查 |
| Agentic 搜索 | 迭代优化关键词 | 多步骤查询 |
| 深度研究 | 长时多源分析 | 专题报告 |
C. 引文要求（强制）
必须 在界面中展示来源引用（
url_citation），并保持可点击。
D. 高级控制
- 域名白名单
filters - 来源完整性
sources - 地理位置优化
location
VI. 深度解析：Connectors 与 MCP（模型上下文协议）
A. 概念
mcp（Model Context Protocol）：赋予模型"行动力"，连接外部服务（如 Google Workspace、Dropbox）。
B. 类型
| 类型 | 描述 |
|---|---|
| Connectors | OpenAI 托管服务，需 OAuth 授权 |
| Remote MCP Servers | 开发者自建服务器，自由扩展 |
C. 工作机制
- mcp_list_tools：首次加载工具列表
- mcp_call：执行远程工具调用
D. 控制与成本
- 审批循环：需
mcp_approval_request/response - 成本：仅计算 token 使用，无额外调用费用
VII. 深度解析：image_generation（图像生成）
A. 新范式（Responses API）
- 直接使用
{"type": "image_generation"} - 主模型（如 GPT-4o）自动调用 DALL·E
- 自动提示优化（
revised_prompt字段可见） - 输出：Base64 图像字符串
B. 旧范式（Assistants API）
- 需使用 Function Calling 手动封装
- 后端二次调用 DALL·E API
- 流程繁琐、高延迟
Responses API 版本实现完全自动化。
VIII. 深度解析：computer_use（计算机使用，预览版）
A. 概念
赋予模型"眼睛与手"，直接操作 GUI 界面（点击、输入、导航）。
B. 工作流循环
- 发送初始请求：包含目标、屏幕尺寸、截图
- 模型建议动作 ：返回如
click、type等指令 - 客户端执行动作：模拟鼠标/键盘操作
- 捕获结果：上传新截图
- 循环继续：直至任务完成
C. 能力
- 自主导航 GUI
- 动态响应 UI 变化
- 跨应用任务执行
IX. 结论与工具对比总结
A. 核心结论
Responses API 是未来方向。
所有新项目应直接基于它构建，旧项目需规划迁移。
B. 工具能力对比表
| 工具类型 | 核心功能 | 典型输入 | 输出 | 有状态 | 需外部配置 |
|---|---|---|---|---|---|
file_search |
检索私有知识 | vector_store_ids | 带引用文本 | 否 | 是 |
code_interpreter |
执行代码、分析数据 | 文件数据 | 文本、file_id | 是 | 否 |
web_search |
实时互联网搜索 | 用户查询 | 带URL引用文本 | 是 | 否 |
mcp |
调用外部服务 | 工具参数 | JSON响应 | 是 | 是 |
image_generation |
生成/编辑图像 | 文本提示 | Base64图像 | 否 | 否 |
computer_use |
操作计算机GUI | 截图、目标 | action指令 | 是 | 是 |