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
サンドボックスエージェント ：エージェントに、分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスセッション状態を組み合わせたもの
リアルタイムエージェント ：ツール、ガードレール、ハンドオフ、会話履歴を備えた低レイテンシーの音声インタラクションをサポート
Agents as tools / ハンドオフ ：特定のタスクをほかのエージェントに委任可能
ガードレール ：エージェントへの入力を検証可能

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

Agents SDK を使用する理由

SDK は、次の 2 つの設計原則に基づいています。

使用する価値がある十分な機能を備えつつ、短時間で習得できるよう基本コンポーネントを最小限に抑えること。
そのままでも優れた動作を提供しながら、処理内容を詳細にカスタマイズできること。

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

エージェントループ ：ツールの呼び出し、結果の LLM への返送、タスクが完了するまでの継続処理を担う組み込みのエージェントループ
サンドボックス実行 ：ワークスペースが必要な作業で、分離されたファイルシステムワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスセッション状態を使用してエージェントを実行
リアルタイムエージェント ：自動割り込み検出、コンテキスト管理、ガードレールなどの機能を備えた、低レイテンシーの音声インタラクションを構築
TypeScript ファースト ：新しい抽象化を学ぶことなく、TypeScript ネイティブの言語機能を使用してエージェントをオーケストレーションし、連携
Agents as tools / ハンドオフ ：複数のエージェント間で作業を調整し、委任するための強力な仕組み
ガードレール ：エージェントの実行と並行して入力検証と安全性チェックを実行し、チェックに合格しなければ即座に失敗
関数ツール ：スキーマの自動生成と Zod による検証を使用して、任意の TypeScript 関数をツールに変換
MCP サーバーツール呼び出し ：関数ツールと同じ方法で動作する組み込みの MCP サーバーツール連携
セッション ：エージェントループ内で作業コンテキストを維持するための永続的なメモリレイヤー
Human in the loop (人間の介入) ：複数のエージェント実行を通じて人間を関与させるための組み込みの仕組み
トレーシング ：ワークフローの可視化、デバッグ、監視のための組み込みのトレーシング。OpenAI の評価、ファインチューニング、蒸留ツール群にも対応

インストール

npm install @openai/agents zod

SDK には Zod v4 が必要です。npm で zod をインストールすると、最新の v4 リリースが取得されます。

開始点の選択

初めて利用するほとんどのユーザーには、次のいずれか 1 つのエントリーポイントで十分です。

最初に選ぶもの	利用する場面	備考
`@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-...

最初のステップ

まず 1 つのパスを選び、エンドツーエンドで動作させてから、より詳細なガイドに戻ってください。

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

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

クイックスタート音声インタラクションを構築する場合は、リアルタイムエージェントから始めます。

パスの選択

実行したい作業は決まっているものの、どのページに説明があるか分からない場合は、次の表を使用してください。

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