OpenAI Agents SDK TypeScript

OpenAI Agents SDK

借助少量基础组件构建文本、沙盒和实时智能体。

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 { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

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 仅包含少量基础组件：

智能体，即配备指令和工具的 LLM
沙盒智能体，将智能体与隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态相结合
实时智能体，支持使用工具、护栏、交接和对话历史记录进行低延迟语音交互
Agents as tools / 交接，允许智能体将特定任务委派给其他智能体
护栏，用于验证智能体的输入

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

使用 Agents SDK 的理由

SDK 遵循两项核心设计原则：

功能足以体现使用价值，同时基础组件数量足够少，便于快速学习。
开箱即用，同时允许您精确自定义具体行为。

SDK 的主要功能如下：

智能体循环：内置智能体循环，可处理工具调用、将结果发回 LLM，并持续运行直至任务完成。
沙盒执行：当工作需要工作区时，可在隔离的文件系统工作区中运行智能体，并使用 shell 命令、文件编辑、快照和沙盒会话状态。
实时智能体：构建低延迟语音交互，支持自动中断检测、上下文管理、护栏等功能。
TypeScript 优先：使用原生 TypeScript 语言功能编排和串联智能体，无需学习新的抽象概念。
Agents as tools / 交接：一种功能强大的机制，用于协调多个智能体并在它们之间委派工作。
护栏：在智能体执行期间并行运行输入验证和安全检查，并在检查未通过时快速失败。
函数工具：将任意 TypeScript 函数转换为工具，并自动生成模式以及执行由 Zod 驱动的验证。
MCP 服务器工具调用：内置 MCP 服务器工具集成，其工作方式与函数工具相同。
会话：用于在智能体循环中维护工作上下文的持久化记忆层。
人工干预：内置在智能体运行过程中引入人工参与的机制。
追踪：内置工作流追踪功能，用于可视化、调试和监控工作流，并支持 OpenAI 的整套评估、微调和蒸馏工具。

安装

npm install @openai/agents zod

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

起点选择

大多数初次使用的用户只需选择以下入口之一：

从这里开始	适用场景	说明
`@openai/agents`	构建大多数文本、沙盒或实时应用。	推荐作为默认选择。它包含 OpenAI 提供商配置、位于 `@openai/agents/sandbox` 下的沙盒智能体 API，以及位于 `@openai/agents/realtime` 下的实时 API。
`@openai/agents-realtime`	仅需要独立的 Realtime 软件包。	适用于仅在浏览器中运行的实时应用，或需要更精简的软件包边界时。
底层软件包（`@openai/agents-core`、`@openai/agents-openai`、`@openai/agents-extensions`）	需要底层组合、自定义提供商接入或特定集成。	大多数新用户在有明确需求之前可以忽略这些软件包。

Hello World 示例

文本工作流可从普通的 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);

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

import { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

console.log(result.finalOutput);

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

export OPENAI_API_KEY=sk-...

入门路径

请先选择一条路径，确保端到端运行成功，然后再回来阅读更深入的指南。

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

快速入门当智能体需要文件、shell 命令、补丁或可恢复的沙盒状态时，启动沙盒智能体。

快速开始构建语音交互时，从实时智能体开始。

路径选择

如果您知道要完成什么任务，但不确定应查看哪个页面，请使用下表。

目标	入门页面
构建第一个文本智能体并查看一次完整运行	快速开始
添加函数工具、托管工具或 Agents as tools	工具
为智能体提供隔离的文件系统和 shell 工作区	快速入门
在交接和管理器式编排之间进行选择	智能体编排
跨轮次保留记忆	运行智能体和会话
使用 OpenAI 模型、WebSocket 传输机制或非 OpenAI 提供商	模型
检查输出、运行项、中断和恢复状态	执行结果
构建低延迟实时智能体	快速开始