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 には、ごく少数の基本コンポーネントがあります。

エージェント: 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 リリースが取得されます。

開始ポイントの選択

初めて使うほとんどのユーザーは、次のいずれか 1 つのエントリーポイントだけで十分です。

Start with	Use it when	Notes
`@openai/agents`	ほとんどのテキストまたは音声アプリケーションを構築する場合	推奨のデフォルトです。OpenAI provider のセットアップが含まれており、音声 API は `@openai/agents/realtime` で利用できます
`@openai/agents-realtime`	スタンドアロンの Realtime パッケージだけが必要な場合	ブラウザ専用の音声アプリや、より狭いパッケージ境界にしたい場合に便利です
Lower-level packages (`@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 つの進め方を選んで、最初から最後まで動かしてみてください。その後で、より詳しいガイドに戻るのがおすすめです。

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

Voice Agents Quickstart 音声によるやり取りを構築する場合は、Realtime の音声パスから始めます。

パスの選択

やりたい作業は分かっているものの、どのページを見ればよいか分からないときは、この表を使ってください。

Goal	Start here
最初のテキストエージェントを構築し、1 回の完全な実行を確認する	クイックスタート
関数ツール、組み込みツール（Hosted）、または Agents as tools を追加する	ツール
ハンドオフとマネージャー型オーケストレーションのどちらにするか判断する	エージェントオーケストレーション
ターンをまたいでメモリを保持する	エージェントの実行とセッション
OpenAI モデル、websocket トランスポート、または非 OpenAI provider を使う	モデル
outputs、run items、割り込み、再開状態を確認する	エージェントの実行結果
低遅延の音声エージェントを構築する	Voice Agents Quickstart