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 とハンドオフ：複数のエージェント間で作業を調整し、委任するための強力な仕組みです。
ガードレール：入力検証と安全性チェックをエージェントの実行と並行して行い、チェックに合格しなかった場合は即座に停止できます。
関数ツール：任意の TypeScript 関数を、自動スキーマ生成とスキーマベースの検証を備えたツールに変換できます。
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 { 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 以外のプロバイダーを使用	モデル
出力、実行アイテム、割り込み、再開状態を確認	エージェントの実行結果
低遅延のリアルタイムエージェントを構築	クイックスタート