OpenAI Agents SDK JS/TS 快速入门

来源：OpenAI Agents SDK JS/TS 文档 · openai/openai-agents-js · Quickstart · Tools | 整理时间：2026-05-15 类型：原创整合 | 标签：openai-agents-sdk, typescript, tutorial, tools

OpenAI Agents SDK 的 JavaScript/TypeScript 版适合把 Agent 嵌进 Node.js 应用、后台任务和 Web 产品后端。它不是 Claude Code 这类交互式编程工具，而是一个可编程运行时：你定义 Agent、工具、运行方式和错误处理，再把它接到自己的业务系统里。

如果你已经看过 Python 版，可先读 OpenAI Agents SDK 实战指南。本文只处理 JS/TS 开发者最关心的最小闭环：安装、运行第一个 Agent、加一个函数工具、处理常见错误。

适合谁

推荐路线：先做一个单 Agent + 一个工具的闭环，不要一上来做多 Agent。等你能稳定观测输入、工具调用、最终输出后，再考虑 handoffs、sessions 和 tracing。

环境要求

官方 README 标注支持 Node.js 22 或更高版本，也支持 Deno、Bun；Cloudflare Workers 属于实验支持，需要启用 nodejs_compat。本篇示例用 Node.js 22。

mkdir openai-agents-js-demo
cd openai-agents-js-demo
npm init -y
npm install @openai/agents zod

把项目切到 ESM：

npm pkg set type=module

配置 API Key：

export OPENAI_API_KEY="sk-..."

不要把 Key 写进代码或提交到仓库。生产环境应通过平台密钥管理注入环境变量。

第一个 Agent

创建 index.mjs：

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

const agent = new Agent({
  name: 'ReleaseAssistant',
  instructions: 'You explain technical release notes as concrete engineering actions.',
});

const result = await run(
  agent,
  'Summarize how a backend team should evaluate a new SDK release.'
);

console.log(result.finalOutput);

运行：

node index.mjs

这个例子只有一个 Agent，没有工具。它适合验证三件事：包能正常加载、认证能通过、你能拿到 finalOutput。如果这一步不稳定，不要继续加工具或多 Agent。

加一个函数工具

真实 Agent 的价值来自工具。下面的例子模拟一个内部文档查询工具，让 Agent 先查资料再回答。

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

const docs = {
  mcp: 'MCP connects models to external tools and resources through a standard protocol.',
  tracing: 'Tracing records agent runs, tool calls, and model usage for debugging.',
  guardrails: 'Guardrails validate inputs or outputs before the workflow proceeds.',
};

const searchDocs = tool({
  name: 'search_docs',
  description: 'Search the internal agent glossary by keyword.',
  parameters: z.object({
    keyword: z.string().describe('One lowercase keyword, such as mcp or tracing'),
  }),
  execute: async ({ keyword }) => {
    return docs[keyword.toLowerCase()] ?? 'No matching entry found.';
  },
});

const agent = new Agent({
  name: 'DocsAssistant',
  instructions: [
    'Answer in three short bullets.',
    'Use search_docs before explaining glossary terms.',
    'If the tool returns no match, say what is missing instead of guessing.',
  ].join('\n'),
  tools: [searchDocs],
});

const result = await run(agent, 'Explain tracing for an agent product team.');
console.log(result.finalOutput);

工具设计要保守：参数越窄，Agent 越容易稳定调用。不要把一个 execute_sql(query: string) 这种高权限工具直接暴露给模型；先封装成 get_user_order_summary(userId) 这类业务动作。

最小项目结构

小项目不需要复杂目录。先用这套结构：

openai-agents-js-demo/
  package.json
  src/
    agents/
      docs-agent.mjs
    tools/
      search-docs.mjs
    index.mjs

拆分规则很简单：

这样拆不是为了“架构优雅”，而是方便后续测试：工具可以单测，Agent instructions 可以单独评审，入口只负责把它们串起来。

什么时候加多 Agent

不要因为 SDK 支持 handoffs 就马上拆多 Agent。满足下面任一条件再拆：

最常见的第一种拆法是 Router 模式：入口 Agent 只判断任务类型，把问题交给“文档检索”“数据分析”“写作整理”等专门 Agent。不要让 Router 自己完成所有工作。

错误处理基线

上线前至少处理四类错误：

工具内部不要直接抛业务细节给模型：

const safeTool = tool({
  name: 'get_order_status',
  description: 'Get order status by order ID.',
  parameters: z.object({ orderId: z.string().min(6) }),
  execute: async ({ orderId }) => {
    try {
      return await getOrderStatus(orderId);
    } catch {
      return 'ORDER_LOOKUP_FAILED: ask the user to verify the order ID.';
    }
  },
});

Agent 看到稳定的错误码，才有机会做合理降级。随机堆栈只会污染上下文。

生产化检查表

JS/TS SDK 的优势是容易嵌进现有产品；风险也是太容易把现有产品的高权限 API 暴露给模型。先把工具边界做窄，再谈复杂编排。

和 Python 版怎么选

选择标准不是“哪个 SDK 更强”，而是哪个能更快接入你已有的鉴权、日志、数据库和部署链路。Agent 框架本身只是运行时，真正的工程成本在工具边界和观测系统。