OpenAI Agents SDK TypeScript

OpenAI Agents SDK

少数の基本コンポーネントで、テキストおよび音声エージェントを構築します。

Text Agent
Voice 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);

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 の基本コンポーネントはごく少数です。

Agents : instructions と tools を備えた 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 provider の設定を含み、音声 API は `@openai/agents/realtime` で公開されます
`@openai/agents-realtime`	スタンドアロンの Realtime パッケージだけが必要な場合	ブラウザー専用の音声アプリや、より小さいパッケージ境界にしたい場合に有用です
下位レベルのパッケージ (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`)	下位レベルの構成、カスタム provider 配線、または特定の統合が必要な場合	多くの新規ユーザーは、具体的な必要性が出るまでこれらを気にする必要はありません

Hello World の例

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 トランスポート、または non-OpenAI provider を使う	モデル
出力、実行項目、割り込み、再開状態を確認する	エージェントの実行結果
低遅延の音声エージェントを構築する	クイックスタート