OpenAI Agents SDK TypeScript

OpenAI Agents SDK

使用一小组基本组件构建文本和语音智能体。

Text Agent
Voice Agent

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);

console.log(result.finalOutput);

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';

const agent = new RealtimeAgent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});

// Automatically connects your microphone and audio output in the browser via WebRTC.
const session = new RealtimeSession(agent);
await session.connect({
  apiKey: '<client-api-key>',
});

概述

TypeScript 版 OpenAI Agents SDK 让您能够通过一个轻量、易用且几乎无需抽象层的包来构建智能体式 AI 应用。它是我们此前智能体实验项目 Swarm 的生产就绪升级版，同时也提供 Python 版本。Agents SDK 只包含一小组基本组件：

智能体，即配备了 instructions 和工具的 LLM
Agents as tools / 交接，允许智能体将特定任务委派给其他智能体
护栏，用于验证传入智能体的输入

结合 TypeScript，这些基本组件足以表达工具与智能体之间的复杂关系，并让您无需陡峭的学习曲线即可构建真实世界应用。此外，SDK 内置了追踪功能，可帮助您可视化和调试智能体流程，还能对其进行评估，甚至为您的应用微调模型。

使用 Agents SDK 的原因

SDK 有两个核心设计原则：

功能足够丰富，值得使用；但基本组件足够少，因此学习起来很快。
开箱即用，效果出色；同时您也可以精确自定义每一步的行为。

以下是 SDK 的主要特性：

智能体循环：内置智能体循环，可处理工具调用、将结果返回给 LLM，并持续执行直到任务完成。
TypeScript 优先：使用原生 TypeScript 语言特性来编排和串联智能体，无需学习新的抽象。
Agents as tools / 交接：一种强大的机制，用于在多个智能体之间协调与委派工作。
护栏：与智能体执行并行运行输入验证和安全检查，并在检查未通过时快速失败。
函数工具：将任何 TypeScript 函数转为工具，并自动生成 schema 以及基于 Zod 的验证。
MCP 服务器工具调用：内置 MCP 服务器工具集成，使用方式与函数工具相同。
会话：持久化记忆层，用于在智能体循环中维护工作上下文。
人机协作：内置机制，可在智能体运行过程中引入人工参与。
追踪：内置追踪能力，用于工作流的可视化、调试与监控，并支持 OpenAI 的评估、微调和蒸馏工具套件。
实时智能体：构建强大的语音智能体，支持自动打断检测、上下文管理、护栏等功能。

安装

npm install @openai/agents zod

SDK 需要 Zod v4；通过 npm 安装 zod 将会获取最新的 v4 版本。

起点选择

大多数首次使用的用户只需要以下入口之一：

起点	适用场景	说明
`@openai/agents`	您正在构建大多数文本或语音应用。	推荐默认选择。它包含 OpenAI provider 配置，并通过 `@openai/agents/realtime` 暴露语音 API。
`@openai/agents-realtime`	您只需要独立的 Realtime 包。	适用于纯浏览器语音应用，或您希望包边界更小的情况。
底层包（`@openai/agents-core`、`@openai/agents-openai`、`@openai/agents-extensions`）	您需要更底层的组合、自定义 provider 接线或特定集成。	大多数新用户在有明确需求之前都可以忽略这些包。

Hello World 示例

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

（如果要运行此示例，请确保已设置 OPENAI_API_KEY 环境变量）

export OPENAI_API_KEY=sk-...

从这里开始

先选择一条路径，把它完整跑通，再回来阅读更深入的指南。

快速开始几分钟内构建您的第一个智能体，并了解 SDK 的核心工作流。

快速开始如果您要构建语音交互，请从 Realtime 语音路径开始。

路径选择

当您清楚自己要完成什么工作，但不确定该看哪一页说明时，请使用下表。

目标	从这里开始
构建第一个文本智能体并查看一次完整运行	快速开始
添加函数工具、托管工具或 Agents as tools	工具
在交接与管理者式编排之间做出选择	智能体编排
在多轮之间保留记忆	运行智能体和会话
使用 OpenAI 模型、websocket 传输或非 OpenAI provider	模型
查看输出、运行项、中断和恢复状态	执行结果
构建低延迟语音智能体	快速开始