跳到主要内容

OpenAI Agents SDK 指南

本文聚焦 OpenAI Agents SDK 在 TypeScript 项目中的定位、适用边界和基础学习顺序。

内容只基于 OpenAI 官方文档整理，不凭印象补定义。

1. 定位​

按照 OpenAI 官方文档，Agents SDK 是一套用于“在代码里构建 agent”的 SDK。OpenAI 在官方概览里把它描述为：适合从代码优先的 agent 应用起步，并在需要时逐步扩展到更高级的运行时模式。

它可以视为一层 agent 应用运行框架，而不只是一次模型调用封装。

它要解决的不是：

  • 只发一次 prompt 拿一次回答

而是更偏向：

  • 让一个系统围绕目标做多步工作
  • 在过程中调工具
  • 必要时切换给别的 specialist agent
  • 对输入/输出做 guardrails
  • 保留 trace 方便调试与观测

OpenAI 官方文档对 agent 的定义也很清楚：agent 是一个配置好的 LLM，至少包含：

  • instructions
  • model
  • tools

从这个定义出发，Agents SDK 关心的核心已经不是“单次补全文本”，而是“如何把模型、工具、协作、状态和运行过程组织成一个可执行系统”。

2. 它适合什么问题​

结合 OpenAI 官方 Agents 概览、Quickstart、Tools、Agent Orchestration 文档，可以把适用问题理解为下面几类。

2.1 适合多步任务​

如果任务不是一步生成，而是：

  • 先理解目标
  • 再决定是否调用工具
  • 根据工具结果继续推进
  • 最后再组织最终输出

那就是 Agents SDK 的典型适用区间。

例如：

  • 调研助手
  • 内部知识助手
  • 客服分流与 specialist 协作
  • 带工具的数据处理/执行助手
  • 需要运行过程可追踪的 agent 工作流

2.2 适合工具使用明显的任务​

OpenAI 官方 Tools 文档明确把工具分成多类：

  • Hosted OpenAI tools
  • Built-in execution tools
  • Function tools
  • Agents as tools
  • MCP servers
  • Experimental: Codex tool

因此 SDK 的一个核心价值就是：

不是只让模型“回答”，而是让模型在受控边界内“做事”。

2.3 适合多 agent 协作​

如果系统已经开始出现下面这些需求：

  • 一个 agent 负责总控
  • 某些子任务要交给 specialist
  • 有时 specialist 只是子工具
  • 有时 specialist 要正式接管当前对话

那 Agents SDK 的 agents as tools 和 handoffs 就开始有价值了。

2.4 适合需要可观测性的任务​

OpenAI 官方 Tracing 文档说明，SDK 内置 tracing，会记录：

  • LLM generations
  • tool calls
  • handoffs
  • guardrails
  • custom events

这对真实项目非常关键，因为 agent 系统最怕“能跑，但出了问题不知道为什么”。

3. 它不适合什么问题​

这部分官方文档不会直接给你一个“禁用清单”，但从 OpenAI 的页面定位可以反推得很明确。

3.1 不适合只有一次生成的简单场景​

如果任务只是：

  • 简单问答
  • 一次文案生成
  • 一次结构化抽取
  • 没有工具、没有多步决策、没有协作

那通常直接用 OpenAI client library 调 Responses API 就够了，不一定需要引入 Agents SDK 这层运行框架。

OpenAI 在 Agents SDK 概览里也区分了：

  • 直接 API client 适合直接模型请求
  • Agents SDK 适合应用自己掌握 orchestration、tool execution、approvals 和 state 的情况

3.2 不适合必须完全确定性的流程​

如果业务流程是：

  • 步骤固定
  • 路由固定
  • 不希望模型决定下一步
  • 每一步都应由代码显式编排

那更适合把模型作为某个步骤里的能力，而不是把整个流程交给 agent 决策。

OpenAI 官方 Agent Orchestration 文档也明确区分了两种方向：

  • 让 LLM 决定流程
  • 由代码决定流程

所以不是“用了 Agents SDK 就必须全自动”，但如果任务本身根本不需要 agent 决策，直接 workflow 往往更稳。

3.3 不适合一上来就堆很多通用 agent​

官方编排文档强调：

  • 要投资在 good prompts
  • 要有 specialized agents
  • 要持续监控与迭代
  • 要做 evals

这背后其实说明了一件事：

Agents SDK 适合做边界清楚的 agent 系统，不适合一开始就做一个“什么都能做”的大总管。

4. 核心概念​

4.1 Agent​

官方 Agents 文档将 Agent 定义为配置好的 LLM，核心包括：

  • instructions
  • model
  • tools

其中：

  • instructions 决定角色、目标和行为约束
  • model 决定用哪个模型及其参数
  • tools 决定它可以调用哪些能力

Agent 可以理解为一个带职责说明、模型配置和能力边界的智能执行单元。

4.2 Tools​

官方 Tools 文档把工具能力分层得很清楚。对大多数 TypeScript 项目，最常见的是下面四类：

  • function tools：把本地函数包装成模型可调用工具
  • hosted tools：比如 web search、file search
  • agents as tools：把另一个 agent 暴露成一个可调用工具
  • MCP servers：接入外部或本地 MCP 能力

tool 是 agent 对外部世界采取动作的边界。

4.3 Handoffs​

官方 Handoffs 文档的定义是：handoff 让一个 agent 把对话的一部分委托给另一个 agent。

它和 agent.asTool() 的差别非常重要。

  • agents as tools：manager 还掌控全局，specialist 只是帮它做子任务
  • handoffs：specialist 会接管当前这一段对话，成为新的 active agent

OpenAI 官方编排文档给出的判断标准如下：

  • 如果 specialist 只是子任务帮手，不该接管用户对话，用 agents as tools
  • 如果 routing 本身就是流程的一部分，而且 specialist 应该接管后续对话，用 handoffs

4.4 Guardrails​

官方 Guardrails 文档把 guardrails 分成：

  • input guardrails
  • output guardrails
  • tool guardrails

它们的用途不是“让系统更聪明”，而是“让系统更可控”。

几个关键边界要特别记住：

  • input guardrails 只在链路里的第一个 agent 上生效
  • output guardrails 只在最终产出结果的 agent 上生效
  • tool guardrails 是围绕每次 function-tool 调用执行的

所以如果工作流里有 manager、handoff、多次工具调用，往往不能只靠 agent 级 input/output guardrails，还要考虑 tool guardrails。

4.5 Tracing​

官方 Tracing 文档说明，Agents SDK 内置 tracing，并且在服务端运行时默认开启。

默认 trace 里会记录：

  • 整个 run()
  • 每次 agent run
  • 每次模型生成
  • 每次 function tool 调用
  • 每次 guardrail
  • 每次 handoff

因此 tracing 不是“后期锦上添花”，而是 SDK 的原生能力之一。

如果 agent 已经进入真实业务场景，tracing 通常应尽早接入，而不是等问题出现后再补。

5. Prompting 在 Agents SDK 里为什么重要​

虽然 Agents SDK 负责运行时组织，但 agent 的行为稳定性仍然高度依赖 prompt 设计。这里应直接参考 OpenAI 官方 prompting 文档。

至少有四条对 Agents SDK 很实用：

5.1 角色与总行为约束放在高优先级指令中​

OpenAI 官方 Prompting 文档建议：

  • 把整体语气、角色指导放在 system message
  • 把任务细节和例子放在 user messages

映射到 Agents SDK 里，最直接的做法就是：

  • 把 agent 的长期身份、职责边界、何时调用工具、何时交接 handoff，放进 instructions
  • 把本轮任务数据放到每次 run() 的输入

5.2 few-shot 示例要短而清晰​

官方文档建议 few-shot 示例用简洁、易扫描的块组织。

对 agent 来说，这尤其重要，因为：

  • tool use 规则太散会影响调用稳定性
  • handoff 条件太模糊会影响路由稳定性
  • 输出格式要求不集中会影响结果一致性

5.3 prompt 应版本化，而不是到处散落​

OpenAI 官方 Prompting 文档强调 prompt 对象支持：

  • versioning
  • templating
  • eval 对比

当 agent 已进入多人协作或持续迭代阶段，不宜把所有 instructions 都硬编码成一大段字符串并分散复制。

5.4 prompt 改动要配 eval​

官方 Prompting 文档明确建议：每次发布 prompt 都重新跑 eval。

这对 agent 系统尤其关键，因为你改的不只是文案，往往还会改变：

  • 是否调用工具
  • 调哪个工具
  • 是否触发 handoff
  • 是否更容易越权或漏答

6. 最小 TypeScript 结构​

下面这个例子刻意保持“最小可理解”，主要基于 OpenAI 官方 Quickstart 和 Tools 文档整理。

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const lookupPolicy = tool({
  name: 'lookup_policy',
  description: '根据主题返回内部政策摘要',
  parameters: z.object({
    topic: z.string(),
  }),
  execute: async ({ topic }) => {
    if (topic.includes('refund')) {
      return '退款政策：7 天内可申请，超过 7 天需人工审批。';
    }

    return '未命中政策，请转人工处理。';
  },
});

const supportAgent = new Agent({
  name: 'Support Policy Agent',
  instructions:
    '你是一个内部支持助手。优先使用工具查政策，再根据工具结果给出简洁结论。若证据不足，明确说明不确定。',
  tools: [lookupPolicy],
});

const result = await run(
  supportAgent,
  '用户想知道 refund 相关规则，请先查政策再总结。',
);

console.log(result.finalOutput);

这段代码可以拆成 4 个最小部件：

  • tool(...)：定义 agent 可调用的函数工具
  • new Agent(...)：定义 agent 的名称、职责和工具边界
  • run(agent, input)：启动一次 agent run
  • result.finalOutput：拿最终产出

从最小示例继续演进时，通常会进入下面几步：

  1. 把本地函数工具换成真实数据源
  2. 给 agent 增加更明确的 instructions
  3. 加一个 specialist agent，试一次 agent.asTool()
  4. 再决定是否需要 handoffs
  5. 接上 tracing 和 eval

7. 和本专题现有文档的对应关系​

如果已经在这个专题里按顺序看过现有文档，可以这样对齐。

7.1 对应 Minimal​

可对应：

关系可以理解为：

  • Minimal 更接近在讲 agent 闭环最小骨架
  • OpenAI Agents SDK 是把这个最小骨架落到 OpenAI 官方 SDK 原语上

也就是：

Minimal 回答“最少要有什么”，本篇回答“如果用 OpenAI 官方 SDK，这些东西分别落在哪些 API 上”。

7.2 对应 Tool​

可对应：

关系是：

  • 工具型 agent 的抽象设计，在现有文档里已经讲了“为什么要工具、循环怎么组织”
  • 本篇补的是“OpenAI 官方 SDK 里 tool / hosted tools / agent.asTool / MCP / guardrails 怎么对应”

7.3 对应 Research​

可对应：

关系是：

  • Research 文档强调研究循环、证据补全、来源组织
  • 本篇补的是用 OpenAI 官方 agent 原语来承载这套研究流程时，该优先理解哪些能力

例如 Research agent 很常会用到：

  • tools
  • agents as tools 或 handoffs
  • tracing
  • prompt + eval 持续迭代

7.4 对应 RAG​

可对应：

关系是：

  • RAG 文档更强调检索、grounding、信息充分性
  • 本篇补的是：如果用 OpenAI Agents SDK 做 RAG Agent，那么 retrieval/file search/tooling/orchestration/trace 分别怎么落位

8. 阅读顺序​

第一次接触这个主题时，可按下面顺序阅读。

8.1 第一步：先搞清 agent 最小闭环​

先看：

目标不是记框架，而是搞清：

  • 目标
  • 决策
  • 工具
  • 状态
  • 停止条件

8.2 第二步：再看这篇 OpenAI Agents SDK 指南​

这一步要建立的是“官方原语映射”：

  • 最小 agent 在 SDK 里怎么写
  • tool 在 SDK 里怎么定义
  • agent 协作时是 asTool 还是 handoff
  • guardrails 和 tracing 分别负责什么

8.3 第三步：进入 Tool Agent​

再看：

因为大多数真实 agent 项目，第一步通常都是从 tool use 长出来的。

8.4 第四步：按任务类型分流到 Research 或 RAG​

如果目标是：

  • 多来源调研、形成判断

优先看：

如果目标是：

  • 私有知识检索、grounded answer、检索不足时继续补查

优先看：

8.5 第五步：最后补 guardrails、tracing、eval​

很多人会先学“更复杂的多 agent 编排”，但其实更稳的顺序通常是：

  • 先让系统能跑
  • 再让系统会调工具
  • 再让系统会协作
  • 最后补可控性、观测性和评估

从 OpenAI 官方文档的结构看，这个顺序也更自然。

9. 一个实用判断：什么时候该用 handoff，什么时候该用 agent as tool​

如果在设计阶段只想快速判断，可以直接用这个经验法则。

用 agent.asTool() 当：​

  • 你希望 manager 一直掌控最终回答
  • specialist 只是完成一个边界明确的子任务
  • 需要统一 guardrails、统一输出风格、统一对用户说话的人设

用 handoff 当：​

  • routing 本身就是流程的一部分
  • specialist 应该接管后续对话
  • 你希望 specialist 使用完全不同的 instructions 或 model
  • 你希望每个 specialist 以更短、更聚焦的 prompt 工作

这正是 OpenAI 官方 Agents、Handoffs、Agent Orchestration 三份文档共同强调的分界线。

10. 小结​

OpenAI Agents SDK 适合把“模型 + 工具 + 协作 + guardrails + tracing”组织成真实可运行的 agent 系统；如果任务只是一次生成，就不必急着上这层框架。

11. 官方依据​

本文内容主要依据以下 OpenAI 官方文档：

12. 文内关键依据摘记​

为方便回查，这里把本文最关键的依据点再列一遍：

  • Agents SDK 概览说明 agent 应用会“plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work”。
  • Quickstart 说明 TS 安装方式为 npm install @openai/agents zod。
  • Agents 文档说明 agent 的核心是 instructions、model、tools。
  • Tools 文档说明 SDK 支持 hosted tools、built-in execution tools、function tools、agents as tools、MCP servers 等能力。
  • Handoffs 文档说明 handoff 是把对话委托给另一个 agent，并且对 LLM 来说 handoff 以 tool 的形式出现。
  • Guardrails 文档说明 input/output/tool guardrails 的边界不同，尤其是 tool guardrails 适合围绕每次 function-tool 调用做检查。
  • Tracing 文档说明 tracing 在服务端默认开启，并默认记录 agent run、tool call、guardrail、handoff 等事件。
  • Prompting 文档说明 prompt 应版本化、可评估，并建议把整体角色指导放在 system message，把任务细节和例子放在 user messages。