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>',
});

概述

OpenAI Agents SDK for TypeScript 让你能够以轻量、易用且仅含极少抽象的方式构建智能体 AI 应用。它是我们此前智能体实验项目 Swarm 的生产级升级版本，并且也提供 Python 版本。Agents SDK 提供了一组非常精简的基本组件：

智能体，即配备了 instructions 和 tools 的 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	模型
查看输出、运行项、中断与恢复状态	执行结果
构建低延迟语音智能体	快速开始