OpenAI Agents SDK TypeScript

OpenAI Agents SDK

使用少量基本组件构建沙盒、文本和语音智能体。

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.5',
  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 { 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 和 tools 的 LLM
沙盒智能体，将智能体与隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态配对
Agents as tools / 交接，允许智能体将特定任务委派给其他智能体
护栏，用于对智能体的输入进行验证

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

选择 Agents SDK 的理由

SDK 有两条核心设计原则：

功能足够丰富，值得使用；基本组件又足够少，便于快速学习。
开箱即用效果很好，同时也允许您精确自定义实际发生的行为。

SDK 的主要功能包括：

智能体循环：内置的智能体循环会处理工具调用、将结果发回 LLM，并持续运行直到任务完成。
沙盒执行：当任务需要工作区时，使用隔离的文件系统工作区、shell 命令、文件编辑、快照和沙盒会话状态运行智能体。
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/sandbox` 下的沙盒智能体 API，以及 `@openai/agents/realtime` 下的语音 API。
`@openai/agents-realtime`	您只需要独立的 Realtime 包。	适用于纯浏览器语音应用，或当您希望包边界更窄时。
更底层的包（`@openai/agents-core`、`@openai/agents-openai`、`@openai/agents-extensions`）	您需要更底层的组合、自定义 provider 接入或特定集成。	大多数新用户可以先忽略这些，直到有明确需求。

Hello World 示例

当智能体需要在文件系统中工作时，请从沙盒智能体开始。如果您的工作流不需要沙盒工作区或沙盒生命周期，仍可使用普通的 Agent。

沙盒智能体
不使用沙盒

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.5',
  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 { 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 语音路径开始。

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

路径选择

当您知道想完成的任务，但不知道哪一页介绍它时，可以使用此表。

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