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

概要

OpenAI Agents SDK for TypeScript は、ごく少ない抽象化で、軽量かつ使いやすいパッケージとしてエージェント型 AI アプリを構築できるようにします。これは、以前のエージェント実験である Swarm を本番利用可能な形にアップグレードしたもので、Python 版も利用できます。Agents SDK は、ごく少数の基本コンポーネントで構成されています。

エージェント: instructions と tools を備えた LLM
サンドボックスエージェント: エージェントに、分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスセッション状態を組み合わせたもの
Agents as tools / ハンドオフ: エージェントが特定のタスクを他のエージェントに委任できる仕組み
ガードレール: エージェントへの入力を検証できる仕組み

TypeScript と組み合わせることで、これらの基本コンポーネントは、ツールとエージェントの複雑な関係を表現し、必要なときにエージェントへ実際のワークスペースを提供し、急な学習曲線なしに実用的なアプリケーションを構築できるほど強力です。さらに SDK には、エージェント型フローを可視化してデバッグできる組み込みの トレーシング が含まれており、評価や、アプリケーション向けのモデルのファインチューニングにも対応しています。

Agents SDK を使う理由

SDK には、設計を支える 2 つの原則があります。

使う価値のある十分な機能を備えつつ、すばやく学べる程度に基本コンポーネントを少なくすること。
標準設定ですぐに優れた動作をしながら、何が起きるかを正確にカスタマイズできること。

SDK の主な機能は次のとおりです。

エージェントループ: ツール呼び出しを処理し、結果を LLM に返し、タスクが完了するまで継続する組み込みのエージェントループ
サンドボックス実行: 作業にワークスペースが必要な場合に、分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスセッション状態を使ってエージェントを実行
TypeScript ファースト: 新しい抽象化を学ぶ必要なく、ネイティブの TypeScript 言語機能を使ってエージェントをオーケストレーションし、連鎖させることができます
Agents as tools / ハンドオフ: 複数のエージェント間で作業を調整し、委任するための強力な仕組み
ガードレール: 入力検証と安全性チェックをエージェント実行と並行して実行し、チェックに通らない場合は早期に失敗させます
関数ツール: 任意の TypeScript 関数を、自動スキーマ生成と Zod による検証を備えたツールに変換
MCP サーバーツール呼び出し: 関数ツールと同じ方法で動作する、組み込みの MCP サーバーツール連携
セッション: エージェントループ内で作業コンテキストを維持するための永続メモリレイヤー
Human in the loop (人間の介入): エージェント実行全体で人間を関与させるための組み込みメカニズム
トレーシング: ワークフローの可視化、デバッグ、監視のための組み込みトレーシング。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 { 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-...

最初のステップ

まず 1 つの道筋を選び、エンドツーエンドで動かしてから、より詳しいガイドに戻ってください。

クイックスタート最初のテキストベースのエージェントを構築し、SDK の基本ワークフローを学びます。

音声エージェントのクイックスタート音声でのやり取りを構築する場合は、Realtime 音声パスから始めます。

サンドボックスエージェントエージェントにファイル、シェルコマンド、パッチ、または再開可能なサンドボックス状態が必要な場合は、サンドボックスエージェントから始めます。

進め方の選択

やりたい作業は分かっているが、どのページに説明があるか分からない場合は、この表を使ってください。

目的	最初に読むページ
最初のテキストエージェントを構築し、1 回の完全な実行を確認する	クイックスタート
関数ツール、組み込みツール（Hosted）、または Agents as tools を追加する	ツール
エージェントに分離されたファイルシステムとシェルワークスペースを与える	サンドボックスエージェント
ハンドオフとマネージャースタイルのオーケストレーションのどちらを使うか判断する	エージェントオーケストレーション
ターンをまたいでメモリを保持する	エージェントの実行とセッション
OpenAI モデル、WebSocket トランスポート、または OpenAI 以外のプロバイダーを使う	モデル
出力、run item、中断、再開状態を確認する	エージェントの実行結果
低レイテンシの音声エージェントを構築する	音声エージェントのクイックスタート