30 秒了解：OpenAI Agents SDK 是什么

OpenAI Agents SDK 是 OpenAI 官方维护的、用来快速搭多智能体应用的开发框架，提供 Python 和 TypeScript/Node.js 两套版本。它在 Responses API 之上包了一层抽象，把「写 Agent 时要重复造的轮子」——比如多轮对话循环、工具调用、Agent 之间互相交接、会话记忆、错误重试——都封装好。

简单对比：

北极星词：如果你想在中文社区找完整的 AI Agent 教程，OpenAI 官方这套 SDK 是值得优先学的——文档齐、维护稳、未来一定会和 OpenAI 自家新功能（如 AgentKit）保持最佳兼容。

准备工作

国内用户没条件直连？可以用 OpenAI 兼容接口的中转服务（如 DeepSeek、智谱、阿里通义都提供 OpenAI 兼容端点），Agents SDK 大多数功能也能用，但部分新特性可能受限。

详细操作步骤

第 1 步：安装 SDK

Node.js / TypeScript：

npm install @openai/agents
# 或 pnpm
pnpm add @openai/agents

Python：

pip install openai-agents

两个版本概念几乎一致，下面以 Node 为主讲，Python 用法在每一节末尾附核心代码对照。

第 2 步：写一个 Hello Agent（5 行代码）

新建 hello.ts：

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

const helloAgent = new Agent({
  name: 'Hello Agent',
  instructions: '你是一个简洁的中文助手，回答不超过 30 字。',
  model: 'gpt-5',
});

const result = await run(helloAgent, '你好，介绍一下你自己');
console.log(result.finalOutput);

设置 OPENAI_API_KEY 环境变量后跑 tsx hello.ts，几秒后就能拿到回答。

Python 对应代码：

from agents import Agent, Runner

hello_agent = Agent(
    name="Hello Agent",
    instructions="你是一个简洁的中文助手，回答不超过 30 字。",
    model="gpt-5",
)

result = Runner.run_sync(hello_agent, "你好，介绍一下你自己")
print(result.final_output)

跑通这 5 行就证明你的开发环境是好的，下面才能往复杂走。

第 3 步：给 Agent 加 Tool（自定义函数）

Agent 之所以是 Agent，核心就是「能调工具」。Agents SDK 用一个 tool() 装饰器或函数把任意 JS/Python 函数变成 Agent 可调用的工具：

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

const getWeather = tool({
  name: 'get_weather',
  description: '查询某城市当前天气',
  parameters: z.object({
    city: z.string().describe('城市名，如 北京'),
  }),
  execute: async ({ city }) => {
    // 真实场景这里调天气 API
    return { city, temp: '22°C', condition: '多云' };
  },
});

const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: '你是天气助手，用户问天气就调 get_weather 工具',
  tools: [getWeather],
});

const result = await run(weatherAgent, '北京今天天气怎样？');
console.log(result.finalOutput);

跑起来 Agent 会自动识别用户问天气 → 调 get_weather → 拿到结果 → 用人话回。整个 tool_calls 循环你不用写一行。

Python 版核心差别在用 @function_tool 装饰器声明工具，其余概念相同。

第 4 步：理解 4 大核心抽象

Agents SDK 全部能力都基于 4 个概念：

理解这 4 个，所有官方示例你都能看懂。

第 5 步：用 Handoff 做多智能体协作

真实业务里常常需要多个专门的 Agent 互相协作。Agents SDK 的 Handoff 就是为此设计：

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

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: '只回答账单、发票、退款问题',
});

const techAgent = new Agent({
  name: 'Tech Agent',
  instructions: '只回答技术、Bug、集成问题',
});

const router = new Agent({
  name: 'Router',
  instructions: '判断用户问题类型，转交给 Billing 或 Tech',
  handoffs: [billingAgent, techAgent],
});

const result = await run(router, '我的发票一直没收到，怎么办？');
console.log(result.finalOutput); // 会自动转给 Billing Agent

这是 OpenAI 官方主推的多智能体范式，比自己写路由器靠谱得多。想理解概念可以看 多智能体协作是什么。

第 6 步：用 Session 保住对话记忆

默认 run() 每次调用都是一次性的，没有记忆。要做对话型 Agent 加上 Session：

import { Agent, run, MemorySession } from '@openai/agents';

const chatAgent = new Agent({
  name: 'Chat',
  instructions: '你是中文聊天助手',
});

const session = new MemorySession();

await run(chatAgent, '我叫小李', { session });
const r2 = await run(chatAgent, '我刚才说我叫什么？', { session });
console.log(r2.finalOutput); // 输出会包含「小李」

生产环境一般用 OpenAI 自家的 Conversations API 持久化对话，不要把 MemorySession 用到生产——进程一重启就没了。

详细看 AI Agent 的记忆怎么实现 那篇关于 session 设计的讲解。

第 7 步：加 Tracing 排查 Bug

Agent 跑出来奇怪的结果，最痛的就是不知道它中间想了什么。Agents SDK 内置 Tracing：

import { Agent, run, withTrace } from '@openai/agents';

await withTrace('weekly-report-flow', async () => {
  const result = await run(myAgent, '生成周报');
  console.log(result.finalOutput);
});

跑完去 platform.openai.com 的 Traces 页面，能看到这次跑的完整调用链——每一步 LLM 输入输出、每个 tool 调用参数、耗时、Token。调试 Agent 必装功能。

5 个让 Agents SDK 更好用的进阶技巧

常见坑 + 解决办法

一个完整实战案例：用 Agents SDK 搭客户支持机器人

下面是一个能直接跑的最小可用版本（Node + TypeScript），处理「订单查询 + 投诉转人工」两类需求：

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

const queryOrder = tool({
  name: 'query_order',
  description: '按订单号查订单状态',
  parameters: z.object({ order_id: z.string() }),
  execute: async ({ order_id }) => {
    // 真实场景这里查公司 OMS
    return { order_id, status: '已发货', tracking: 'SF1234567' };
  },
});

const supportAgent = new Agent({
  name: '客服 Agent',
  instructions: `你是公司客服。
- 用户问订单：调 query_order，把状态友善地告诉用户
- 用户要投诉或退款：礼貌引导留下联系方式，告知会有人工 1 小时内回
- 不要承诺折扣、不要编造物流信息
- 回答简洁，3 句话以内`,
  tools: [queryOrder],
  model: 'gpt-5',
});

const session = new MemorySession();

async function chat(input: string) {
  const r = await run(supportAgent, input, { session });
  console.log('Bot:', r.finalOutput);
}

await chat('你好，我想查订单 ABC123 的状态');
await chat('它什么时候能到？');

下面是上面 Agent 的 instructions 模板，方便你套用到自己的客服场景：

你是「[公司名]」的 AI 客服。
能调用的工具

query_order：按订单号查询订单状态
escalate_to_human：把工单转给人工客服
行为规则

用户问订单：必须调 query_order，不要凭印象回答
用户投诉、退款、要求经理：立即调 escalate_to_human 并礼貌告知会有人工跟进
不能擅自承诺折扣、库存、活动
不知道的事情说「我帮你转一下人工」，不要编
风格

简洁，每次不超过 3 句话
每次最多 1-2 个表情
称呼用「您」，正式不油腻

在这套架构上加更多 tool（CRM 查客户、Knowledge Base 查 FAQ）、加 Handoff（专门有个 Agent 处理退款）、加 Tracing 看真实对话，3 天就能从原型推到内测。

进阶 / 下一步

• AgentKit 是什么？OpenAI 一站式 Agent 工具：OpenAI 配套的可视化工具
• ChatGPT Agent 模式怎么用？官方上手教程：终端用户视角
• MCP 是什么？让 AI 接万物的协议讲人话：Agents SDK 原生支持的工具协议
• 多智能体协作是什么：理解 Handoff 背后的设计
• Dify 怎么用？开源 LLMOps 平台 0 基础上手：对比可视化方案

常见问题

Q：OpenAI Agents SDK 和 LangChain / LlamaIndex 是啥关系？ A：定位重叠但定位不同。Agents SDK 是 OpenAI 官方、绑 OpenAI 生态——和自家新功能（如 Conversations API、AgentKit）一定第一时间兼容。LangChain 是社区驱动、跨厂商、抽象更厚。追求和 OpenAI 深度结合用 Agents SDK，追求多厂商兼容用 LangChain。

Q：Agents SDK 支持哪些模型？ A：默认 OpenAI 全家桶（GPT-5、4o、4o-mini 等）。也支持任何 OpenAI 兼容接口（DeepSeek、智谱、Anthropic 通过 LiteLLM 转、Azure OpenAI）。配置时改 baseURL 即可。

Q：Agents SDK 适合做生产环境吗？ A：适合。OpenAI 已经用它跑自家 ChatGPT 的部分 Agent 模式逻辑。关键是配 Tracing + Guardrails + 限流，安全和稳定性自己兜一层。

Q：Node 和 Python 哪个版本更成熟？ A：Python 版功能更全、文档更多（社区更早起步）。Node 版后跟，但核心抽象一致。前端/全栈团队用 Node，后端/数据团队用 Python。

Q：MCP Server 怎么接进 Agents SDK？ A：Agents SDK 已经原生支持 MCP。通过 MCPServerStdio 或 MCPServerHTTP 类把 Server 实例化后传给 Agent 的 tools 即可。具体看官方 cookbook 的 mcp 章节。

Q：Agents SDK 收费吗？ A：SDK 本身完全免费、开源（Apache 2.0）。真实开销是模型调用费用——按 OpenAI 标准计费，每千 Token 几分到几毛美金不等。