コンテンツにスキップ

モデル

すべてのエージェントは、最終的に LLM を呼び出します。SDK は、2 つの軽量なインターフェイスでモデルを抽象化しています。

  • Model – 特定の API に対して 1 回 のリクエストを行う方法を定義します。
  • ModelProvider – 人間が読みやすいモデルの 名前 (例:'gpt-5.6-sol')を Model インスタンスに解決します。

通常の作業では、主にモデルの 名前 を扱い、必要に応じて ModelSettings を使用します。

エージェントごとのモデルの指定
import { Agent } from '@openai/agents';
const agent = new Agent({
name: 'Creative writer',
model: 'gpt-5.6-sol',
});

Agent の初期化時にモデルを指定しない場合は、デフォルトモデルが使用されます。現在のデフォルトは gpt-5.6-luna で、大量のエージェントワークロードを効率的に処理できるよう、reasoning.effort: "none" と text.verbosity: "low" が設定されています。

gpt-5.6-sol などの別のモデルに切り替える場合、エージェントを設定する方法は 2 つあります。

まず、カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使用するには、エージェントを実行する前に環境変数 OPENAI_DEFAULT_MODEL を設定します。

ターミナルウィンドウ
export OPENAI_DEFAULT_MODEL=gpt-5.6-sol
node my-awesome-agent.js

もう 1 つの方法は、Runner インスタンスにデフォルトモデルを設定することです。エージェントにモデルを設定しなければ、この Runner のデフォルトモデルが使用されます。

Runner のデフォルトモデルの設定
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt-4.1-mini' });

gpt-5.6-sol などの GPT-5.x モデルをこの方法で使用すると、SDK はデフォルトの modelSettings を適用します。ほとんどのユースケースに最適な設定が適用されます。デフォルトモデルの推論の労力を調整するには、独自の modelSettings を渡します。

GPT-5 のデフォルト設定のカスタマイズ
import { Agent } from '@openai/agents';
const myAgent = new Agent({
name: 'My Agent',
instructions: "You're a helpful agent.",
// If OPENAI_DEFAULT_MODEL=gpt-5.6-sol is set, passing only modelSettings works.
// It's also fine to pass a GPT-5.x model name explicitly:
model: 'gpt-5.6-sol',
modelSettings: {
reasoning: { effort: 'high' },
text: { verbosity: 'low' },
},
});

レイテンシーとコストを重視する場合は、デフォルトの gpt-5.6-luna の設定から始めるか、別の GPT-5.x モデルで reasoning.effort: "none" を使用し、タスクにより慎重な推論が必要な場合にのみ推論の労力を増やしてください。

カスタムの modelSettings を指定せずに GPT-5 以外のモデル名を渡すと、SDK はどのモデルとも互換性のある汎用的な modelSettings に戻ります。


デフォルトの ModelProvider は、OpenAI API を使用して名前を解決します。次の 2 つの異なるエンドポイントをサポートしています。

API用途setOpenAIAPI() の呼び出し
Chat Completions標準的なチャットと関数呼び出しsetOpenAIAPI('chat_completions')
Responsesストリーミングを重視した新しい生成 API(ツール呼び出し、柔軟な出力)setOpenAIAPI('responses') (デフォルト)
デフォルトの OpenAI キーの設定
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

カスタムのネットワーク設定が必要な場合は、setDefaultOpenAIClient(client) を使って独自の OpenAI クライアントを組み込むこともできます。直接渡すクライアントは、openai 7.2 以降を使用する必要があります。

プロバイダーオプションのリファレンス

Section titled “プロバイダーオプションのリファレンス”

OpenAIProvider を直接インスタンス化する場合、以下のオプションでクライアントの構築、エンドポイントの選択、機能の検証を制御できます。

オプション目的
apiKeyプロバイダーが独自の OpenAI クライアントを作成するときに使用する API キーです。デフォルトでは SDK 全体の OpenAI キーを使用します。
baseURLOpenAI 互換エンドポイントの HTTP ベース URL です。openAIClient とは併用できません。
websocketBaseURLResponses WebSocket トランスポートの WebSocket ベース URL です。openAIClient とは併用できません。
openAIClientopenai 7.2 以降の設定済みクライアントです。apiKey、baseURL、websocketBaseURL、organization、project とは併用できません。
organization / projectプロバイダーが独自の OpenAI クライアントを作成するときに渡す組織とプロジェクトの値です。openAIClient とは併用できません。
useResponsesこのプロバイダーが解決する文字列のモデル名に対して、Responses API(true)または Chat Completions API(false)を選択します。デフォルトではプロセス全体の setOpenAIAPI(...) の設定を使用します。
useResponsesWebSocketこのプロバイダーが解決する Responses モデルに WebSocket トランスポートを使用します。デフォルトではプロセス全体の setOpenAIResponsesTransport(...) の設定を使用します。
cacheResponsesWebSocketModels接続を再利用するために、WebSocket を使用する Responses モデルラッパーを再利用します。デフォルトは true です。シャットダウン時に provider.close() を呼び出して、キャッシュされたラッパーを閉じてください。
responsesWebSocketOptionspingIntervalMs と pingTimeoutMs でクライアントのキープアライブを設定します。
strictFeatureValidationChat Completions モデルで、previousResponseId、conversationId、prompt、アシスタントメッセージのフェーズなど、Responses 専用の機能に対して UserError を発生させます。デフォルトでは、これらの機能について警告を出し、無視します。

apiKey、baseURL、organization、project のいずれかが指定されている場合、その OpenAIProvider は setDefaultOpenAIClient(...) で設定されたクライアントを再利用せず、プロバイダー固有の値を使って独自の OpenAI クライアントを構築します。これらのオプションも openAIClient も指定されていない場合、プロバイダーは SDK 全体のデフォルトクライアントを再利用できます。websocketBaseURL は Responses WebSocket の接続先を変更しますが、それだけで HTTP クライアントを置き換えることはありません。

Responses のアシスタントメッセージに commentary または final_answer の phase が含まれている場合、SDK はそれを履歴項目のトップレベルフィールドとして保持します。このフェーズは、OpenAIConversationsSession やシリアライズされた RunState を通じてセッションを再現するときも保持されます。Chat Completions には同等のフィールドがないため、デフォルトでは警告を出してフェーズを削除します。この変換を拒否するには、strictFeatureValidation: true を設定してください。

Responses のストリーミングプロトコル は、型付きの終了イベントを使用します。SDK は、レスポンスペイロードを持つ response.completed イベントを、成功したモデル実行結果として受け入れます。failed または incomplete のレスポンス、response.failed、response.incomplete、response.error のいずれかのイベント、error イベント、または必須のレスポンスペイロードを持たない response.completed イベントは、ストリーミング実行でも非ストリーミング実行でも ModelBehaviorError を発生させます。

SDK は、成功しなかった終了状態を、すでに開始されている可能性があり、安全に再実行できないレスポンスとして扱います。非ストリーミング実行では、デフォルトの再試行に関する助言に従ってリクエストが自動的に繰り返されることはありません。ランナーが再試行するには、カスタムの再試行ポリシーが安全でない再実行を明示的に承認する必要があります。ストリーミング実行では、カスタムの再試行ポリシーが安全でない再実行を承認していても、元の終了イベントを出力した後にランナーが再試行することはありません。成功しなかったレスポンスが使用量を報告している場合、ランナーはその使用量をトレーシングと実行時の使用量集計に含めます。ストリーミングの実行結果では、result.completed が拒否されても、result.state.usage に使用量が保持されます。

成功しなかったレスポンスが成功した ModelResponse になることはなく、rawResponses やセッション履歴に追加されることも、そのレスポンスの出力項目が実行されることもありません。ストリーミングを受け取る側は、result.completed が拒否される前に、元のモデルイベントストリームを通じて元の終了イベントを確認できます。終了時の部分的な出力を、再利用可能な履歴や最終出力として扱わないでください。

Chat Completions では、finish_reason: 'length' は、トークン数またはコンテキストの上限に達したためにプロバイダーが生成を停止したことを意味します。候補に有用なテキスト、拒否、音声、推論、または関数呼び出しが含まれている場合、SDK はその部分的なアシスタントペイロードを保持します。切り詰められた候補にこれらのペイロードがまったく含まれていない場合、SDK は空の候補を成功したレスポンスとして扱わず、ストリーミング実行でも非ストリーミング実行でも ModelBehaviorError を発生させます。

SDK は、この出力のない切り詰めを、すでに開始されている可能性があり、安全に再実行できないレスポンスとして扱います。ストリーミングを受け取る側は、result.completed が拒否される前に、元のチャンクをすでに受信している可能性があります。失敗した試行が使用量を報告している場合、ランナーはその使用量をトレーシングと実行時の使用量集計に含めます。

音声対応の Chat Completions モデルは、modelSettings.providerData を通じて、エンドポイント固有のリクエストフィールド modalities と audio を受け取ります。音声対応モデルを使用し、サポートされているリクエスト値については公式の音声とスピーチのガイドに従ってください。

非ストリーミング呼び出しでもストリーミング呼び出しでも、音声のみのアシスタント出力が保持されます。正規化された ModelResponse.output には audio コンテンツパートが含まれます。そのメッセージが実行項目になると、RunMessageOutputItem.rawItem に同じパートが含まれます。その audio フィールドには base64 データが含まれ、providerData には id、transcript、format、expires_at などのプロバイダーメタデータが保持されます。同じ候補にテキストや拒否も含まれる場合、正規化されたアシスタントメッセージにはそのテキストや拒否も保持されます。非ストリーミング呼び出しでは、音声を含む完全なプロバイダーレスポンスを result.rawResponses[].providerData で引き続き利用できます。ストリーミング呼び出しでは、元のモデルストリームイベントから、元の Chat Completions チャンクを到着するたびに受け取ってください。再構築された音声はトレーシング用に保持されますが、result.rawResponses には保持されません。null の音声フラグメントは無視されます。不正な形式または複製できない音声デルタや、音声データなしで終了するストリームは、ModelBehaviorError で失敗します。toTextStream() はアシスタントのテキストのみを出力します。低レイテンシーの双方向音声が必要なアプリケーションでは、代わりに Realtime API を使用してください。詳しくは音声エージェントの概要を参照してください。

OpenAI プロバイダーで Responses API を使用する場合、デフォルトの HTTP トランスポートの代わりに WebSocket トランスポートでリクエストを送信できます。

setOpenAIResponsesTransport('websocket') でグローバルに有効にするか、new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true }) でプロバイダーごとに有効にします。

WebSocket トランスポートを使用するだけなら、withResponsesWebSocketSession(...) やカスタムの OpenAIProvider は必要ありません。実行またはリクエストごとに再接続しても問題なければ、setOpenAIResponsesTransport('websocket') を有効にした後も、既存の run() / Runner.run() の使い方をそのまま継続できます。

トランスポートの選択はモデルの解決方法に従います。

  • setOpenAIResponsesTransport('websocket') は、Responses API の使用時に、その後 OpenAI プロバイダーを通じて解決される文字列のモデル名にのみ影響します。
  • 具体的な Model インスタンスを Agent または Runner に渡すと、そのインスタンスがそのまま使用されます。OpenAIResponsesWSModel は WebSocket、OpenAIResponsesModel は HTTP、OpenAIChatCompletionsModel は Chat Completions を使い続けます。
  • 独自の modelProvider を指定した場合は、そのプロバイダーがモデルの解決を制御します。グローバルな設定関数に頼らず、そのプロバイダーで WebSocket を有効にしてください。
  • プロキシ、ゲートウェイ、その他の OpenAI 互換エンドポイントを経由する場合、接続先が WebSocket の /responses エンドポイントをサポートしている必要があります。また、websocketBaseURL を明示的に設定する必要がある場合もあります。

接続の再利用を最適化し、WebSocket プロバイダーのライフサイクルをより明示的に管理する場合にのみ、withResponsesWebSocketSession(...) またはカスタムの OpenAIProvider / Runner を使用してください。

  • withResponsesWebSocketSession(...):コールバックの終了後に自動でクリーンアップする、便利なスコープ付きライフサイクル
  • カスタムの OpenAIProvider / Runner:独自のアプリケーションアーキテクチャでの明示的なライフサイクル制御(シャットダウン時のクリーンアップを含む)

その名前にかかわらず、withResponsesWebSocketSession(...) はトランスポートのライフサイクルヘルパーであり、セッションで説明しているメモリ用の Session インターフェイスとは無関係です。

WebSocket プロキシまたはゲートウェイを使用する場合は、OpenAIProvider の websocketBaseURL を設定するか、OPENAI_WEBSOCKET_BASE_URL を設定してください。

responsesWebSocketOptions では、pingIntervalMs がクライアントの ping 送信間隔を設定します。省略するか null に設定すると、ping が無効になります。pingTimeoutMs は、ソケットを強制終了またはクローズする前に pong を待つ時間を設定します。省略するか null に設定すると、ping を有効にしたままハートビートのタイムアウトを無効にできます。キープアライブには、ping と pong をサポートする WebSocket 実装が必要です。

OpenAIProvider を自分でインスタンス化する場合、接続を再利用するために、WebSocket を使用する Responses モデルラッパーがデフォルトでキャッシュされることに注意してください。シャットダウン時に await provider.close() を呼び出して、キャッシュされた接続を解放してください。withResponsesWebSocketSession(...) は、主にこのライフサイクルを代わりに管理するためのものです。WebSocket が有効なプロバイダーとランナーを作成してコールバックに渡し、終了後は必ずプロバイダーを閉じます。一時的なプロバイダーには providerOptions を、コールバックのスコープ内で使うランナーのデフォルト設定には runnerConfig を使用してください。

Responses WebSocket トランスポートを使ったストリーミングと HITL の完全なコード例については、examples/basic/stream-ws.ts を参照してください。

Responses 専用のツール遅延読み込み

Section titled “Responses 専用のツール遅延読み込み”

toolSearchTool()、toolNamespace()、および deferLoading: true を設定した関数ツールやリモート MCP ツールには、OpenAI Responses API が必要です。Chat Completions プロバイダーは、名前空間付きまたは遅延読み込みの関数ツールを拒否します。また、AI SDK アダプターは、Responses のツール遅延読み込みフローをサポートしていません。ツール検索が必要な場合は、Responses モデルを直接使用してください。

ツール検索は、GPT-5.6 Sol と、それ以降にリリースされた、Responses API でツール検索をサポートするモデルでのみ利用できます。

実行に遅延読み込みツールが含まれる場合は、同じエージェントに toolSearchTool() を追加し、modelSettings.toolChoice を 'auto' にしておいてください。これらの定義をいつ読み込むかはモデルが判断する必要があるため、SDK では組み込みの tool_search ツールや遅延読み込みの関数ツールを名前で指定して強制的に使用させることはできません。設定の詳細については、ツールと公式の OpenAI ツール検索ガイドを参照してください。

ホスト型マルチエージェント(実験的機能)

Section titled “ホスト型マルチエージェント(実験的機能)”

このコード例では両方のパッケージを直接インポートするため、プロバイダーパッケージと OpenAI クライアントを直接の依存関係としてインストールしてください。

ターミナルウィンドウ
npm install @openai/agents-openai openai

ホスト型マルチエージェントでは、GPT-5.6 モデルが Responses API を通じてサブエージェントのツリーを作成し、連携を調整できます。これは SDK のハンドオフや agents-as-tools とは異なり、アプリケーションがホスト型サブエージェントのためにローカルの Agent オブジェクトを作成したり、作業をスケジュールしたりすることはありません。ホスト型のルートエージェントが作業を委任し、サービスがサブエージェント間の連携を調整し、/root が最終回答をまとめます。ベータ版 API の動作とサポート対象モデルについては、公式のマルチエージェントガイドを参照してください。

OpenAIHostedMultiAgentModel を明示的に構築し、SDK の Agent に渡します。モデルを構築することで利用が有効になるため、別途有効化フラグを設定する必要はありません。

この実験的モデルは、永続的な Responses WebSocket 接続を使用します。ローカル関数の出力は response.inject によってアクティブなホスト型レスポンスに注入されるため、実行全体で同じモデルインスタンスを維持し、不要になったら閉じてください。

ホスト型マルチエージェントワークフローの実行
import OpenAI from 'openai';
import { Agent, run, tool } from '@openai/agents';
import {
OpenAIHostedMultiAgentModel,
getHostedAgentMetadata,
} from '@openai/agents-openai/experimental/hosted-multi-agent';
import { z } from 'zod';
const lookupProject = tool({
name: 'lookup_project',
description: 'Return details about a project.',
parameters: z.object({ project: z.string() }),
execute: async ({ project }, _context, details) => {
const caller = getHostedAgentMetadata(details);
console.log(`Tool called by ${caller?.agentName ?? 'unknown'}`);
return { project, status: 'on track' };
},
});
const model = new OpenAIHostedMultiAgentModel(new OpenAI(), 'gpt-5.6-sol', {
maxConcurrentSubagents: 3,
});
try {
const agent = new Agent({
name: 'Hosted coordinator',
model,
tools: [lookupProject],
instructions:
'Delegate project research to hosted subagents, wait for them, and synthesize the result.',
});
const result = await run(agent, 'Compare projects alpha and beta.');
console.log(result.finalOutput);
} finally {
await model.close();
}

ホスト側の連携レコードやサブエージェントのメッセージを含む、ストリーミングのオブザーバビリティについては、完全なコード例を参照してください。

サービスのデフォルト値(現在は 3)を維持するには、maxConcurrentSubagents を省略してください。値を指定する場合は、正の整数でなければなりません。

ツール実行と呼び出し元の識別

Section titled “ツール実行と呼び出し元の識別”

すべてのホスト型エージェントは、リクエストのモデルを使用し、同じローカルツール定義を参照します。いずれかのホスト型エージェントが通常の function_call を出力すると、既存の Agents SDK ランナーがアプリケーションのツールを実行します。Responses API の呼び出し ID がルーティング用のトークンとなり、SDK は、それを要求した呼び出し元に向けて、対応する function_call_output をアクティブなホスト型レスポンスに注入します。

getHostedAgentMetadata(details) は、ツールコールバックの第 3 引数からホスト型エージェントの名前を読み取ります。このメタデータはログやアプリケーションの認可に役立ちますが、ルーティングを制御するものではありません。関数の実行結果をエージェント名で振り分けないでください。呼び出し ID を保持し、使用してください。

ツール引数は WebSocket を通じてサービスから届き、ツール出力はアクティブなホスト型レスポンスに注入されます。機密データに関するポリシー、ツールの認可、承認チェックは、アプリケーション側で管理してください。ツールに副作用がある場合は、呼び出し ID に基づいて冪等にし、中断された処理の再開時に同じ副作用が繰り返されないようにしてください。

フェーズが final_answer である /root メッセージだけが通常のアシスタント出力となり、finalOutput に含まれます。関数呼び出しは、ランナーが実行できるよう通常の SDK ツール呼び出しのまま維持され、推論やホスト型ツール呼び出しなどの安定版 Responses 項目も、既存の SDK 表現を維持します。サブエージェントのメッセージ、ルートのコメント、ホスト側の連携レコードはアクティブな WebSocket レスポンス内にとどまり、SDK の履歴には追加されません。

ホスト側のレコードやサブエージェントのメッセージを含む元のストリーミングイベントは、引き続き raw_model_stream_event を通じて利用できます。上位レベルの項目ストリーミングでは、ベータ版専用の連携レコードを除外しつつ、安定版 Responses 項目を保持します。また、上位レベルのテキストストリーミングには、ルートの最終回答だけが含まれます。これにより、オブザーバビリティのためにホスト側の完全なイベントストリームを保持しつつ、RunState とセッション履歴をプロバイダーに依存しない状態に保ちます。

ストリーミング実行は、終了イベントまで受け取ってください。ストリームを受け取る側が途中で処理を停止すると、SDK は WebSocket を閉じ、アクティブなホスト型レスポンスを破棄します。後続の実行では、破棄したレスポンスを再開せず、新しいホスト型レスポンスを開始します。

この実験的な SDK モデルは、Responses WebSocket トランスポートのみをサポートします。ベータ版 Responses API は HTTP 経由のホスト型マルチエージェントもサポートしていますが、OpenAIHostedMultiAgentModel は 1 つの WebSocket を開いたままにし、SDK ランナーが処理を続ける前に各ローカル関数の出力をアクティブなレスポンスに注入できるようにしています。

進行中のホスト型レスポンスの継続状態は、OpenAIHostedMultiAgentModel インスタンスが保持します。モデルは、保留中の関数出力を注入する前に、閉じられた WebSocket を再接続できます。ただし、承認や中断されたツールを再開する際は、同じモデルインスタンスと、同じ WebSocket トランスポートのヘッダーおよびクエリを使用する必要があります。モデルを再作成すると、継続状態が失われます。また、1 つのモデルインスタンスで同時にアクティブにできる実行は 1 つだけです。

トランスポート障害後に安全に再実行できるのは、リクエストフレームが送信されていないことを SDK が把握している場合だけです。サーバーがフレームを受信した可能性がある場合、SDK はそのエラーを安全に再実行できないものとしてマークし、ホスト側のターンを自動的に繰り返しません。一般的な再試行ポリシーについては、モデルの再試行を参照してください。

このモデルを SDK のハンドオフ、reasoning.summary、max_tool_calls と組み合わせないでください。これらの組み合わせは、リクエストが送信される前に失敗します。modelSettings.contextManagement で設定するサーバー側のコンパクションしきい値は引き続きサポートされますが、Responses のコンパクションエンドポイントへの明示的な呼び出しは、このモデルのライフサイクルの対象外です。安定版の OpenAIResponsesModel では、SDK のハンドオフと agents-as-tools を引き続き使用できます。


ModelSettings は OpenAI のパラメーターに対応していますが、プロバイダーには依存しません。

フィールド型備考
temperaturenumber創造性と決定性のバランスです。
topPnumberNucleus sampling です。
frequencyPenaltynumber繰り返されるトークンにペナルティを与えます。
presencePenaltynumber新しいトークンを促します。
toolChoice'auto' | 'required' | 'none' | stringエージェントのツール使用の強制に関する説明を参照してください。OpenAI Responses では、利用可能な場合に toolChoice: 'computer' が一般提供(GA)版の組み込みコンピュータツールの使用を強制します。
parallelToolCallsbooleanサポートされている場合に、並列の関数呼び出しを許可します。
truncation'auto' | 'disabled'トークンの切り詰め戦略です。
maxTokensnumberレスポンスの最大トークン数です。
timeoutMsnumberモデルリクエストの各試行に適用する協調的タイムアウト(ミリ秒)です。有限値で、0 より大きく、2147483647 以下でなければなりません。
storeboolean検索 / RAG ワークフローのためにレスポンスを永続化します。
promptCacheRetention'in-memory' | '24h' | nullサポートされている場合に、従来のプロンプトキャッシュの最大保持ポリシーを制御します。これは promptCacheOptions.ttl とは独立しています。
promptCacheOptions{ mode?: 'implicit' | 'explicit'; ttl?: '30m' }GPT-5.6 以降のモデルで、暗黙的または明示的なプロンプトキャッシュのブレークポイントを制御します。
contextManagementModelSettingsContextManagementサーバー側のコンパクションなど、プロバイダーのコンテキスト管理を制御します。
reasoning.effort'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'対応する gpt-5.x モデルの推論の労力です。max は GPT-5.6 でサポートされています。
reasoning.mode'standard' | 'pro' | string推論の実行モードを選択します。この設定には Responses API が必要です。
reasoning.context'auto' | 'current_turn' | 'all_turns' | null後続のターンで、どの推論項目をモデルに再提示するかを制御します。この設定には Responses API が必要です。
reasoning.summary'auto' | 'concise' | 'detailed'モデルが返す推論の要約の量を制御します。
text.verbosity'low' | 'medium' | 'high'gpt-5.x などのテキストの詳細度です。
providerDataRecord<string, any>基盤となるモデルにそのまま転送される、プロバイダー固有のオプションです。
preserveRawUsageboolean完了した各モデルレスポンスについて、SDK による正規化前のプロバイダー使用量を、元のデータから切り離した JSON 互換のスナップショットとして保持します。デフォルトでは無効です。
retryModelRetrySettings実行時のみ使用される、オプトイン方式の再試行設定です。モデルの再試行を参照してください。

設定はどちらのレベルにも適用できます。

モデル設定
import { Runner, Agent } from '@openai/agents';
const agent = new Agent({
name: 'Creative writer',
// ...
modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});
// or globally
new Runner({ modelSettings: { temperature: 0.3 } });

Runner レベルの設定は、競合するエージェントごとの設定を上書きします。reasoning、text、promptCacheOptions、retry のネストされたフィールドは、継承した値を undefined で明示的にクリアしない限り、ランナーとエージェントの設定間でマージされます。

timeoutMs が経過すると、SDK は現在のモデルリクエストの試行を中止します。再試行処理が別の試行を開始せず、別の失敗も通知しない場合、SDK は ModelTimeoutError を発生させます。実行レベルの中止シグナルは、引き続き実行全体をキャンセルします。モデルの再試行が有効な場合、再試行ポリシーはタイムアウトを他の失敗した試行と同様に評価します。SDK が再試行するのは、そのポリシーが再試行を選択し、かつリクエストを安全に再実行できるか、アプリケーションが安全でない再実行を明示的に承認した場合だけです。

プロバイダー固有の使用量フィールドが必要な場合や、省略されたフィールドと正規化されたゼロを区別する必要がある場合は、preserveRawUsage: true を設定してください。OpenAI Responses、OpenAI Chat Completions、AI SDK ベースのモデルは、ストリーミング実行と非ストリーミング実行の両方でこれをサポートしています。保持はベストエフォートです。プロバイダーが使用量を返さない場合や、単純な JSON 互換データとして安全にコピーできない値を返す場合、rawUsage は undefined のままです。保持されたペイロードへのアクセス方法については、エージェントの実行結果の元のレスポンスに関する説明を参照してください。

GPT-5.6 の推論とプロンプトキャッシュの制御

Section titled “GPT-5.6 の推論とプロンプトキャッシュの制御”

GPT-5.6 では、リクエストレベルの推論モードと、明示的なプロンプトキャッシュのブレークポイントが追加されています。reasoning.mode と reasoning.context は Responses 専用の設定です。OpenAIChatCompletionsModel は 1 度だけ警告を出してこれらを無視しますが、厳密な機能検証が有効な場合はリクエスト前に UserError を発生させます。reasoning.effort は、対応する Chat Completions モデルで引き続き利用できます。

promptCacheOptions は、Responses と Chat Completions のどちらのモデル経路でも転送されます。デフォルトの implicit モードでは、明示的なブレークポイントに加えて、OpenAI が自動的なブレークポイントを選択できます。promptCacheBreakpoint: { mode: 'explicit' } でマークされたコンテンツパートだけを使用するには、mode: 'explicit' を設定してください。現在サポートされている最小キャッシュ有効期間は 30m です。

GPT-5.6 のリクエスト制御の設定
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Research assistant',
model: 'gpt-5.6',
modelSettings: {
reasoning: {
mode: 'pro',
effort: 'max',
context: 'all_turns',
},
promptCacheOptions: {
mode: 'explicit',
ttl: '30m',
},
},
});
await run(agent, [
{
role: 'user',
content: [
{
type: 'input_text',
text: 'Treat this research brief as a reusable prompt prefix.',
promptCacheBreakpoint: { mode: 'explicit' },
},
{
type: 'input_text',
text: 'Summarize the brief and identify its main risks.',
},
],
},
]);

明示的なブレークポイントは、GPT-5.6 以降のモデルでサポートされています。サポートされるコンテンツパートの型やブレークポイントの上限は API によって異なります。最新の詳細については、公式のプロンプトキャッシュのブレークポイントガイドを参照してください。

再試行は実行時のみ使用され、オプトイン方式です。modelSettings.retry を設定し、ポリシーが再試行の判断を返さない限り、SDK はモデルリクエストを再試行しません。

モデルの再試行の有効化
import { Agent, Runner, retryPolicies } from '@openai/agents';
const sharedRetry = {
maxRetries: 4,
backoff: {
initialDelayMs: 500,
maxDelayMs: 5_000,
multiplier: 2,
jitter: true,
},
policy: retryPolicies.any(
retryPolicies.providerSuggested(),
retryPolicies.retryAfter(),
retryPolicies.networkError(),
retryPolicies.httpStatus([408, 409, 429, 500, 502, 503, 504]),
),
};
const runner = new Runner({
modelSettings: {
retry: sharedRetry,
},
});
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a concise assistant.',
modelSettings: {
retry: {
maxRetries: 2,
backoff: {
maxDelayMs: 2_000,
},
},
},
});
await runner.run(agent, 'Summarize exponential backoff in plain English.');

ModelRetrySettings には 3 つのフィールドがあります。

フィールド型備考
maxRetriesnumber初回リクエストの後に許可される再試行回数です。
backoff{ initialDelayMs?, maxDelayMs?, multiplier?, jitter? }ポリシーが delayMs を返さずに再試行する場合の、デフォルトの遅延戦略です。backoff.maxDelayMs が上限を設定するのは、この計算されたバックオフ遅延だけです。ポリシーが返す明示的な delayMs の値や、retry-after ヒントには上限を設定しません。
policyRetryPolicy再試行するかどうかを決定するコールバックです。この関数は実行時のみ使用され、永続化された実行状態にはシリアライズされません。

再試行ポリシーは、以下を含む RetryPolicyContext を受け取ります。

  • 試行回数を考慮した判断を行うための attempt と maxRetries
  • ストリーミングと非ストリーミングの動作を分岐させるための stream
  • 元のエラーを確認するための error
  • statusCode、retryAfterMs、errorCode、isNetworkError、isAbort などの normalized 情報
  • 基盤となるモデルまたはプロバイダーが再試行の指針を提供できる場合の providerAdvice
  • プロバイダー固有のエラーを再解釈することなく、アプリケーションのポリシーがランナーの安定した再実行分類を確認できるようにする replaySafety、responseStarted、statefulRequest

ポリシーは、次のいずれかを返せます。

  • 単純な再試行の判断を示す true / false
  • 遅延を上書きしたり、ログ用の診断理由を付加したり、プロバイダーが安全でないと判断した非ストリーミングの再実行を明示的に許可したりする場合の { retry, delayMs?, reason?, approveUnsafeReplay? }

SDK は、すぐに使えるヘルパーを retryPolicies でエクスポートしています。

ヘルパー動作
retryPolicies.never()常に再試行しません。
retryPolicies.providerSuggested()プロバイダーの再試行に関する助言がある場合は、それに従います。
retryPolicies.networkError()一時的なトランスポート障害や接続障害に一致します。
retryPolicies.httpStatus([..])指定した HTTP ステータスコードに一致します。
retryPolicies.retryAfter()retry-after ヒントがある場合にのみ再試行し、そのヒントを、backoff.maxDelayMs による上限が適用されない明示的な遅延として使用します。
retryPolicies.any(...)ネストされたポリシーのいずれかが再試行を選択した場合に再試行します。
retryPolicies.all(...)ネストされたすべてのポリシーが再試行を選択した場合にのみ再試行します。

ポリシーを組み合わせる場合、最初の基本コンポーネントとして最も安全なのは providerSuggested() です。プロバイダーが判断できる場合に、プロバイダーによる拒否や再実行の安全性に関する承認を保持するためです。

次のような失敗は、自動的には再試行されません。

  • 中止エラー
  • 可視イベントまたは元のモデルイベントがすでに出力された後のストリーミング実行
  • 再実行を安全でないとするプロバイダーの助言

previousResponseId または conversationId を使用するステートフルな後続リクエストも、より慎重に扱われます。これらのリクエストでは、networkError() や httpStatus([500]) などの、プロバイダーに基づかない判定だけでは不十分です。再試行ポリシーには、通常は retryPolicies.providerSuggested() を通じて、プロバイダーによる安全な再実行の承認を含める必要があります。

アプリケーションは、{ retry: true, approveUnsafeReplay: true } を返すことで、非ストリーミングリクエストに対するプロバイダーの「安全でない」という分類を上書きできます。これは、先のリクエストがすでに受け付けられている可能性があり、再試行によってレスポンスやその他のプロバイダー側の処理が重複する可能性を明示的に認めるものです。アプリケーションがその結果を許容できる場合にのみ使用してください。これは、中止処理、イベントを出力済みのストリーミングリクエスト、安全でないストリーミングの再実行を上書きしません。retryPolicies.any(...) または retryPolicies.all(...) でポリシーを組み合わせる場合、返される判断が approveUnsafeReplay: true を明示的に設定している場合にのみ、承認が保持されます。

ランナーとエージェントのマージ動作

Section titled “ランナーとエージェントのマージ動作”

retry は、ランナーレベルとエージェントレベルの modelSettings の間でディープマージされます。

  • エージェントは retry.maxRetries だけを上書きし、ランナーの policy を引き続き継承できます。
  • エージェントは retry.backoff の一部だけを上書きし、同じ階層の他のバックオフフィールドをランナーから維持できます。
  • 継承された policy または backoff を削除する必要がある場合は、そのフィールドを明示的に undefined に設定してください。

ログ出力を含む、より詳しいコード例については、examples/basic/retry.ts と examples/ai-sdk/retry.ts を参照してください。


エージェントには prompt パラメーターを設定できます。これは、エージェントの動作を制御するために使用する、サーバーに保存されたプロンプト設定を指定するものです。現在、このオプションは OpenAI の Responses API を使用する場合にのみサポートされています。

prompt には、静的なオブジェクト、または実行時にオブジェクトを返す関数を指定できます。コールバックの形式については、エージェントの動的プロンプトに関する説明を参照してください。

フィールド型備考
promptIdstringプロンプトの一意の識別子です。
versionstring使用するプロンプトのバージョンです。
variablesobjectプロンプトに代入する変数のキーと値のペアです。値には、文字列や、テキスト、画像、ファイルなどのコンテンツ入力型を指定できます。
プロンプトを使用するエージェント
import { parseArgs } from 'node:util';
import { Agent, run } from '@openai/agents';
/*
NOTE: This example will not work out of the box, because the default prompt ID will not
be available in your project.
To use it, please:
1. Go to https://platform.openai.com/chat/edit
2. Create a new prompt variable, `poem_style`.
3. Create a system prompt with the content:
Write a poem in {{poem_style}}
4. Run the example with the `--prompt-id` flag.
*/
const DEFAULT_PROMPT_ID =
'pmpt_6965a984c7ac8194a8f4e79b00f838840118c1e58beb3332';
const POEM_STYLES = ['limerick', 'haiku', 'ballad'];
function pickPoemStyle(): string {
return POEM_STYLES[Math.floor(Math.random() * POEM_STYLES.length)];
}
async function runDynamic(promptId: string) {
const poemStyle = pickPoemStyle();
console.log(`[debug] Dynamic poem_style: ${poemStyle}`);
const agent = new Agent({
name: 'Assistant',
prompt: {
promptId,
version: '1',
variables: { poem_style: poemStyle },
},
});
const result = await run(agent, 'Tell me about recursion in programming.');
console.log(result.finalOutput);
}
async function runStatic(promptId: string) {
const agent = new Agent({
name: 'Assistant',
prompt: {
promptId,
version: '1',
variables: { poem_style: 'limerick' },
},
});
const result = await run(agent, 'Tell me about recursion in programming.');
console.log(result.finalOutput);
}
async function main() {
const args = parseArgs({
options: {
dynamic: { type: 'boolean', default: false },
'prompt-id': { type: 'string', default: DEFAULT_PROMPT_ID },
},
});
const promptId = args.values['prompt-id'];
if (!promptId) {
console.error('Please provide a prompt ID via --prompt-id.');
process.exit(1);
}
if (args.values.dynamic) {
await runDynamic(promptId);
} else {
await runStatic(promptId);
}
}
main().catch((error) => {
console.error(error);
process.exit(1);
});

tools や instructions など、エージェントに追加した設定は、保存済みプロンプトで設定されている値を上書きします。

保存済みプロンプトですでにモデルが定義されている場合、明示的に上書きしない限り、SDK はエージェントのデフォルトモデルを送信しません。これは computerTool() で重要です。プロンプトで管理される実行は、互換性のため、デフォルトで従来のプレビュー版の通信形式を維持します。プロンプトで管理される実行で一般提供(GA)版の Responses コンピュータツールを使用するには、modelSettings.toolChoice: 'computer' を明示的に設定するか、gpt-5.6-sol などのモデルを明示的に送信してください。関連するコンピュータ操作の詳細については、ツールを参照してください。


高度なプロバイダーとオブザーバビリティ

Section titled “高度なプロバイダーとオブザーバビリティ”

独自のプロバイダーを実装する方法はシンプルです。ModelProvider と Model を実装し、そのプロバイダーを Runner コンストラクターに渡します。

最小限のカスタムプロバイダー
import {
ModelProvider,
Model,
ModelRequest,
ModelResponse,
ResponseStreamEvent,
} from '@openai/agents-core';
import { Agent, Runner } from '@openai/agents';
class EchoModel implements Model {
name: string;
constructor() {
this.name = 'Echo';
}
async getResponse(request: ModelRequest): Promise<ModelResponse> {
return {
usage: {},
output: [{ role: 'assistant', content: request.input as string }],
} as any;
}
async *getStreamedResponse(
_request: ModelRequest,
): AsyncIterable<ResponseStreamEvent> {
yield {
type: 'response.completed',
response: { output: [], usage: {} },
} as any;
}
}
class EchoProvider implements ModelProvider {
getModel(_modelName?: string): Promise<Model> | Model {
return new EchoModel();
}
}
const runner = new Runner({ modelProvider: new EchoProvider() });
console.log(runner.config.modelProvider.getModel());
const agent = new Agent({
name: 'Test Agent',
instructions: 'You are a helpful assistant.',
model: new EchoModel(),
modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});
console.log(agent.model);

すべての run() 呼び出しと新しく構築されるすべての Runner で、同じプロバイダーをデフォルトとして使用するには、アプリの起動時に 1 度設定します。

デフォルトモデルプロバイダーの設定
import { setDefaultModelProvider } from '@openai/agents';
setDefaultModelProvider({
async getModel() {
// Return any Model implementation here.
throw new Error('Provide your own model implementation.');
},
});

これは、アプリで OpenAI 以外のプロバイダーを標準として採用しており、すべての箇所でカスタムの Runner を渡したくない場合に便利です。

ModelProvider を自分で実装せずに OpenAI 以外のモデルを使用するには、AI SDK 連携を参照してください。このアダプターを使うと、AI SDK モデルをエージェントのランタイムに直接組み込めます。アプリですでに AI SDK プロバイダーを標準として採用している場合や、より幅広いプロバイダーエコシステムを利用したい場合に便利です。また、Agents SDK の providerData が AI SDK の providerMetadata にどのように対応するかや、AI SDK UI ルートで利用できるストリームヘルパーについても説明しています。


対応するサーバーランタイムでは、トレーシングはデフォルトで有効になっています。トレースのエクスポートにデフォルトの OpenAI API キーとは異なる認証情報を使用する場合にのみ、setTracingExportApiKey() を使用してください。

トレーシングのエクスポート用 API キーの設定
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

これにより、その認証情報を使って OpenAI ダッシュボードにトレースが送信されます。カスタムの取り込みエンドポイントや再試行の調整など、エクスポーターのカスタマイズについては、トレーシングを参照してください。