OpenAI Agents SDK の TypeScript
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>',});OpenAI Agents SDK for TypeScript は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型 AI アプリを構築できます。以前のエージェント向け実験的プロジェクトである Swarm を本番環境向けに発展させたもので、Python 版も利用できます。Agents SDK は、ごく少数の基本コンポーネントで構成されています。
- エージェント は、指示とツールを備えた LLM です
- サンドボックスエージェント は、エージェントに、分離されたファイルシステムのワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスのセッション状態を組み合わせたものです
- 音声エージェント は、ツール、ガードレール、ハンドオフ、会話履歴を活用した低レイテンシーの音声対話をサポートします
- Agents as tools とハンドオフ は、エージェントが特定のタスクをほかのエージェントに委任できる仕組みです
- ガードレール は、エージェントへの入力を検証する仕組みです
これらの基本コンポーネントは TypeScript と組み合わせることで、ツールとエージェントの間の複雑な関係を表現し、必要に応じてエージェントに実際のワークスペースを提供できます。また、学習に多くの時間をかけずに、実用的なアプリケーションを構築できます。さらに、SDK には トレーシング が組み込まれており、エージェントのフローを可視化、デバッグ、評価できるだけでなく、アプリケーションに合わせてモデルをファインチューニングすることもできます。
Agents SDK を使う理由
Section titled “Agents SDK を使う理由”SDK の設計には、次の 2 つの基本原則があります。
- 利用する価値のある十分な機能を備えつつ、すぐに学べるように基本コンポーネントの数を抑えること。
- そのままでも十分に機能し、必要に応じて動作を細かくカスタマイズできること。
SDK の主な機能は次のとおりです。
- エージェントループ : ツールを呼び出し、その結果を LLM に返して、タスクが完了するまで処理を続ける組み込みのエージェントループです。
- サンドボックス実行 : 作業にワークスペースが必要な場合に、分離されたファイルシステムのワークスペース、シェルコマンド、ファイル編集、スナップショット、サンドボックスのセッション状態を利用してエージェントを実行できます。
- 音声エージェント : 自動割り込み検出、コンテキスト管理、ガードレールなどの機能を使って、低レイテンシーの音声対話を構築できます。
- TypeScript ファースト : 新しい抽象化を学ぶことなく、TypeScript 標準の言語機能を使ってエージェントをオーケストレーションし、連鎖させることができます。
- Agents as tools とハンドオフ : 複数のエージェント間で作業を調整し、委任するための強力な仕組みです。
- ガードレール : エージェントの実行と並行して入力検証と安全性チェックを行い、チェックに合格しない場合は速やかに処理を失敗として終了します。
- 関数ツール : スキーマの自動生成とスキーマに基づく検証により、任意の TypeScript 関数をツールに変換できます。
- MCP サーバーのツール呼び出し : MCP サーバーのツールを、関数ツールとともにエージェントに公開する組み込みの連携機能です。
- セッション : エージェントループ内で作業用コンテキストを維持するための永続的なメモリレイヤーです。
- Human in the loop (人間の介入) : エージェントの実行全体を通じて人間が介入するための組み込みの仕組みです。
- トレーシング : ワークフローの可視化、デバッグ、監視のための組み込みのトレーシング機能で、OpenAI の評価、ファインチューニング、蒸留ツール群をサポートします。
インストール
Section titled “インストール”npm install @openai/agents zodSDK には Zod v4 が必要です。npm 経由で zod をインストールすると、最新の v4 リリースが取得されます。
最初に使うパッケージの選択
Section titled “最初に使うパッケージの選択”初めて利用するほとんどのユーザーは、次のいずれか 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 のコード例
Section titled “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-...はじめの一歩
Section titled “はじめの一歩”まずは 1 つの進め方を選び、最初から最後まで動作させてから、より詳しいガイドに進んでください。
目的に応じたガイドの選択
Section titled “目的に応じたガイドの選択”実現したいことは決まっているものの、どのページに説明があるかわからない場合は、この表を参照してください。
| 目的 | 最初に読むガイド |
|---|---|
| はじめてのテキストエージェントを構築し、1 回の実行を最後まで確認する | クイックスタート |
| 関数ツール、組み込みツール(Hosted)、agents as tools を追加する | ツール |
| エージェントに分離されたファイルシステムとシェルのワークスペースを提供する | クイックスタート |
| ハンドオフとマネージャー型オーケストレーションのどちらを使うか決める | エージェントオーケストレーション |
| ターンをまたいでメモリを保持する | エージェントの実行とセッション |
| OpenAI モデル、WebSocket トランスポート、OpenAI 以外のプロバイダーを使用する | モデル |
| 出力、実行アイテム、中断、再開用の状態を確認する | エージェントの実行結果 |
| 低レイテンシーの音声エージェントを構築する | クイックスタート |