OpenAI 智能体工程指南：10 条实战技巧和 3 种构建模式

OpenAI 给出了一份智能体（Agent）工程的实战手册：怎么用技能（Skills）、Shell 工具和上下文压缩（Compaction） 这三个 API 能力，让智能体长时间跑着干活而不崩。

这是 OpenAI 官方开发者博客的文章，有推广 Responses API 的动机。但技巧本身相当实用，尤其是来自企业 AI 搜索公司 Glean（估值 72 亿美元）的生产案例数据。不过文中提到的 Agent Skills 开放标准，其实是 Anthropic 在 2025 年底发起的，OpenAI 是采纳者。智能体工具链的标准化正在跨公司推进。

全文三部分：三个概念的心智模型、10 条实战技巧、3 种构建模式。

一个简单的心智模型

技能（Skills）：模型按需加载的“操作手册”

技能是一组文件加上一个 SKILL.md 清单，清单里有前置元数据（frontmatter）和指令。可以理解成一个版本化的操作手册，模型在需要干活的时候翻阅。

平台把每个技能的名称、描述和路径暴露给模型，模型用这些元数据来决定是否调用。调用了就去读 SKILL.md 获取完整工作流程。

注： Agent Skills 是一个开放标准，最早由 Anthropic 在 2025 年底发布。目前已被 OpenAI Codex、GitHub Copilot、Cursor、Google Gemini CLI 等二十多个 AI 工具采纳。核心思路是“渐进式披露”：模型先看到技能的元数据，觉得需要时才加载完整指令，避免浪费 token。

Shell 工具：智能体的“执行环境”

Shell 工具让模型在真正的终端环境里工作。两种模式：

• OpenAI 托管容器：Debian 12，预装 Python 3.11、Node.js 22、Java 17、Go 1.23、Ruby 3.1
• 本地 Shell 运行时：你自己执行命令，语义一样，但机器在你手里

托管 Shell 走 Responses API，请求自带有状态的工作、工具调用、多轮续接和产出物（artifacts）。

上下文压缩（Compaction）：让长对话跑下去

工作流越来越长，迟早撞上上下文窗口的墙。服务端压缩通过自动管理上下文窗口和压缩对话历史来解决这个问题。

Responses API 提供两种方式：

• 服务端自动压缩：上下文超过阈值时在流式输出中自动执行
• 独立压缩端点 /responses/compact：想自己控制压缩时机时用

三个能力里，Compaction 可能是对开发者最有直接价值的。手动管理上下文窗口一直是长期运行智能体的痛点，之前的常见做法是暴力截断历史，但这样经常把智能体推理到一半的关键信息也截掉。自动压缩保留关键上下文、丢弃噪声，思路上比截断好得多。

电商平台 Triple Whale 的早期数据显示，他们的智能体 Moby 在一次涉及 500 万 token 和 150 次工具调用的会话中全程保持了准确率。

为什么三者搭配更好

• 技能把稳定的流程和示例移入可复用的包，减少“提示词意大利面”
• Shell 提供完整的执行环境，能安装代码、运行脚本、写输出
• 压缩保持长期运行的连贯性，同一工作流持续执行不用手动修剪上下文

三者结合：有真正执行力的可重复工作流，而不是把系统提示词塞成一个脆弱的巨型文档。

现在很多团队的系统提示词膨胀到上万 token，混着角色设定、工作流程、格式要求、安全规则，维护一团乱。Skills 的思路是把这些拆成独立模块，按需加载。

10 条实战技巧

技巧 1：技能的描述就是模型的决策边界

技能描述应该回答三个问题：什么时候该用？什么时候不该用？输出和成功标准是什么？

一个实用做法：在描述中直接放"用于 vs 不用于"的块，保持具体（输入、涉及的工具、预期产出物）。

技巧 2：加负面示例和边缘场景来减少误触发

一个意外的失败模式：提供技能之后反而降低了正确触发率。有效的修复方法是负面示例加边缘场景覆盖。

写几条明确的“不要在这些情况下调用这个技能”（以及该怎么做），帮助模型更干净地路由，特别是有多个看起来很像的技能时。

Glean 遇到了这个问题：基于技能的路由最初在定向评测中让触发率下降了约 20%，加了负面示例和边缘场景覆盖之后恢复了。

多个技能摆在面前时，模型的选择困难和人差不多：选项越多越犹豫。明确说"这个不是你要的"比只说"这个是你要的"更能帮助决策。

技巧 3：把模板和示例放进技能里（不用时基本不花 token）

如果你一直把模板塞进系统提示词里，别这样了。

放在技能里有两个好处：需要的时候才加载（技能被调用时），对不相关的查询不增加 token 消耗。

对知识工作类输出特别有效：结构化报告、升级分诊摘要、客户方案、数据分析报告。

Glean 反馈这个模式为他们带来了生产环境中最大的质量和延迟提升，因为示例只在技能触发时才加载。

技巧 4：从一开始就为长期运行设计

长期运行的智能体很少能靠一次性提示词搞定。从一开始就规划连续性：

• 跨步骤复用同一个容器，依赖、缓存文件和中间输出都保留
• 传递 previous_response_id 让模型在同一线程中继续工作
• 把压缩当作长期运行的默认基础设施，不是紧急回退方案

这个组合减少重启行为，让多步骤任务在线程增长时保持连贯。

技巧 5：需要确定性时，直接告诉模型用哪个技能

默认行为是模型自己决定什么时候用技能，很多时候这正是你要的。

但在有明确契约的生产工作流中，宁可确定性而不要智能，就直接说“使用 XX 技能”。这是你能拉的最简单的可靠性杠杆，把模糊路由变成明确契约。

灵活场景下模型的自主判断是优势，流水线场景下反而是风险。知道什么时候放手、什么时候收回控制权，是构建可靠智能体的关键。

技巧 6：技能 + 网络 = 高风险组合

技能和开放网络访问组合在一起，会创造数据泄露的高风险路径。用了网络就要保持白名单严格，假设工具输出不可信，在面向消费者的流程中避免“开放网络 + 强大操作”的组合。

合理的默认配置：

• 技能：允许
• Shell：允许
• 网络：仅在最小白名单前提下启用，按请求、按窄范围任务限制

技巧 7：用 /mnt/data 作为产出物的交接边界

托管 Shell 工作流中，把 /mnt/data 当作写输出的标准位置。后续要检索、审查或传入下一步的产出物都写在这里：报告、清洗后的数据集、完成的电子表格。

一个好用的心智模型：工具写入磁盘，模型推理磁盘上的内容，开发者从磁盘取回。

技巧 8：白名单是双层系统

网络控制分两层：

• 组织级白名单（管理员配置，设定最大允许的目标域名）
• 请求级 network_policy（必须是组织白名单的子集）

组织白名单要小且稳定，是你信任的"已批准目标"集合。请求白名单要更小，只包含这个任务需要的目标。请求中包含组织白名单之外的域名会直接报错。

技巧 9：用 domain_secrets 做认证调用

白名单中的域名需要认证头时，用 domain_secrets，模型永远看不到真实凭据。

运行时模型看到的是占位符（比如 $API_KEY），一个边车进程只为已批准的目标注入真实值。智能体从容器内调用受保护 API 时，这是个很好的默认做法。

技巧 10：云端和本地用同一套 API

不用把所有东西都托管：技能在托管和本地 Shell 模式下都能工作；Shell 有本地执行模式，你自己执行 shell_call 并返回 shell_call_output；用 Agents SDK 的话，也可以接入自己的执行器。

实用的开发循环：本地开始（快速迭代、方便调试）→ 切到托管容器（要可重复性和隔离性时）→ 两种模式下技能保持不变，执行环境变了，工作流不变。

三种构建模式

模式 A：安装 → 获取 → 写产出物

托管 Shell 最简单的用法：智能体装依赖、获取外部数据、生成交付物。比如装几个库，抓数据或调 API，写一份报告到 /mnt/data/report.md。

这个模式建立了清晰的审查边界：应用可以把产出物展示给用户、记日志、做 diff，或者传入后续步骤。

模式 B：技能 + Shell 打造可重复工作流

构建了一两个成功的 Shell 工作流之后，下一个问题来了：能跑，但提示词一漂移可靠性就下降。

技能就是为这个场景设计的：

1. 把工作流（步骤、护栏、模板）编码进技能
2. 把技能挂载到 Shell 环境
3. 让智能体按照技能确定性地生成产出物

对电子表格分析编辑、数据清洗加摘要生成、重复性业务的标准化报告生成特别有效。

模式 C（进阶）：技能作为企业工作流载体

一个早期观察：从“单工具调用”到“多工具编排”之间存在准确率断崖。技能通过让工具推理更程序化来填补这个缺口，同时不让系统提示词膨胀。

Glean 的案例：一个面向 Salesforce 的技能把评测准确率从 73% 提升到 85%，首字节延迟降低 18.1%。实操策略包括精细路由、负面示例、在技能内嵌入模板和示例。Glean 还用技能编码企业工作流中的重复任务：客户方案规划、升级分诊、品牌对齐的内容生成。

这是技能展现威力的形态：活的标准操作流程（SOP），随组织演进而更新，由智能体一致地执行。

73% 到 85% 的提升幅度不小，但文中没交代评测基准和样本量。"首字节延迟降低 18.1%"也没说绝对值。数字的方向对，精确度存疑。

最后

这篇文章作为 OpenAI 的官方实战指南，10 条技巧大部分能直接用。最有价值的洞察是**"技能描述就是决策边界"和"负面示例提升路由精度"**，对任何构建多技能智能体的开发者都有参考意义。

读者需要自己补充的信息：Agent Skills 标准是 Anthropic 发起的，OpenAI 是采纳者之一；文中完全没提成本；托管容器和 Compaction 是 OpenAI 平台专有能力，不要和“开放标准”混淆。

Skills 作为跨平台的开放标准，正在被 Claude Code、GitHub Copilot、Cursor、OpenAI Codex 等主流 AI 工具同时采纳。智能体的能力不再只靠模型本身的智能，还靠模块化的“流程知识”。