モデル

すべてのエージェントは、最終的に 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 の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは、効率的で大量のエージェントワークロード向けに reasoning.effort: "none" と text.verbosity: "low" を設定した gpt-5.6-luna です。

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

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

export OPENAI_DEFAULT_MODEL=gpt-5.6-sol
node my-awesome-agent.js

次に、Runner インスタンスのデフォルトモデルを設定できます。エージェントにモデルを設定しなかった場合は、この Runner のデフォルトモデルが使用されます。

Runner のデフォルトモデルの設定

import { Runner } from '@openai/agents';

const runner = new Runner({ model: 'gpt-4.1-mini' });

GPT-5.x モデル

この方法で 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" を使用し、タスクでより慎重な推論が必要な場合にのみ推論負荷を高めます。

GPT-5 以外のモデル

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

---

OpenAI プロバイダーの設定

OpenAI プロバイダー

デフォルトの 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 以降を使用する必要があります。

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

OpenAIProvider を直接インスタンス化する場合、次のオプションによってクライアントの構築、エンドポイントの選択、機能の検証を制御します。

オプション	目的
apiKey	プロバイダーが独自の OpenAI クライアントを作成するときに使用する API キー。デフォルトは SDK 全体の OpenAI キーです。
baseURL	OpenAI 互換エンドポイントの HTTP ベース URL。openAIClient と組み合わせることはできません。
websocketBaseURL	Responses WebSocket トランスポートの WebSocket ベース URL。openAIClient と組み合わせることはできません。
openAIClient	openai 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() を呼び出して、キャッシュされたラッパーを閉じます。
responsesWebSocketOptions	pingIntervalMs と pingTimeoutMs を使用してクライアントのキープアライブを設定します。
strictFeatureValidation	Chat 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 の終端状態

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

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

失敗したレスポンスが成功した ModelResponse になることはなく、rawResponses やセッション履歴にも追加されず、そのレスポンスの出力項目も実行されません。ストリーミングのコンシューマーは、result.completed が reject される前に、元のモデルイベントストリームを介して元の終端イベントを確認できます。部分的な終端出力を、再実行可能な履歴や最終出力として扱わないでください。

Chat Completions の切り詰め

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

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

Chat Completions の音声

音声対応の 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 を使用してください。

Responses WebSocket トランスポート

Responses API で OpenAI プロバイダーを使用する場合、デフォルトの 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 間隔を設定します。ping を無効にするには、省略するか null に設定します。pingTimeoutMs では、ソケットを終了または閉じる前に pong を待つ時間を設定します。ping を有効にしたままハートビートのタイムアウトを無効にするには、省略するか null に設定します。キープアライブには、ping と pong のサポートを公開する WebSocket 実装が必要です。

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

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

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

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

ツール検索は、Responses API でツール検索をサポートする GPT-5.6 Sol 以降のモデルリリースでのみサポートされています。

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

ホスト型マルチエージェント（実験的）

実験的ベータ版

ホスト型マルチエージェントはベータ版の Responses API 項目スキーマを使用し、 実験的な @openai/agents-openai/experimental/hosted-multi-agent エクスポートからのみ利用できます。API と SDK のインターフェースは変更される可能性があります。

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

npm install @openai/agents-openai openai

ホスト型マルチエージェントを使用すると、GPT-5.6 モデルは Responses API を介してサブエージェントのツリーを作成し、連携させることができます。これは、ハンドオフや 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 を省略します。値を指定する場合は、正の整数である必要があります。

ツールの実行と帰属

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

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

ツール引数は WebSocket 経由でサービスから届き、ツール出力はアクティブなホスト型レスポンスに挿入されます。機密データに関するポリシー、ツールの認可、承認チェックはアプリケーション内で維持してください。ツールに副作用がある場合は、中断された継続処理によってその効果が繰り返されないよう、呼び出し ID に基づいて冪等にします。

出力とストリーミングの動作

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

元のストリーミングイベントは、ホスト型レコードやサブエージェントメッセージを含め、raw_model_stream_event を介して引き続き利用できます。高レベルの項目ストリーミングは、ベータ版専用のコラボレーションレコードを除外しながら、安定版の Responses 項目を維持します。高レベルのテキストストリーミングには、ルートの最終回答のみが含まれます。これにより、完全なホスト型イベントストリームを可観測性のために保持しつつ、RunState とセッション履歴をプロバイダーに依存しない状態に保ちます。

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

現在の制限事項

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

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

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

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

---

モデルの動作とプロンプト

ModelSettings

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

フィールド	型	注記
temperature	number	創造性と決定性のバランス
topP	number	Nucleus sampling
frequencyPenalty	number	繰り返されるトークンへのペナルティ
presencePenalty	number	新しいトークンの生成を促進
toolChoice	'auto' | 'required' | 'none' | string	ツール使用の強制を参照してください。OpenAI Responses では、toolChoice: 'computer' により、利用可能な場合は GA 版の組み込みコンピューターツールを強制的に使用します。
parallelToolCalls	boolean	サポートされている場合に並列関数呼び出しを許可
truncation	'auto' | 'disabled'	トークンの切り詰め戦略
maxTokens	number	レスポンス内の最大トークン数
timeoutMs	number	モデルリクエストの各試行に対する、ミリ秒単位の協調的タイムアウト。有限で 0 より大きく、2147483647 以下である必要があります。
store	boolean	取得または RAG ワークフロー用にレスポンスを永続化
promptCacheRetention	'in-memory' | '24h' | null	サポートされている場合に、従来のプロンプトキャッシュの最大保持ポリシーを制御します。これは promptCacheOptions.ttl とは独立しています。
promptCacheOptions	{ mode?: 'implicit' | 'explicit'; ttl?: '30m' }	GPT-5.6 以降のモデルで、暗黙的または明示的なプロンプトキャッシュのブレークポイントを制御します。
contextManagement	ModelSettingsContextManagement	サーバー側のコンパクションなど、プロバイダーのコンテキスト管理を制御します。
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 などのテキスト詳細度
providerData	Record<string, any>	基盤モデルへ転送される、プロバイダー固有のパススルーオプション
preserveRawUsage	boolean	完了した各モデルレスポンスについて、SDK による正規化前のプロバイダー使用量を、切り離された JSON 互換のスナップショットとして保持します。デフォルトでは無効です。
retry	ModelRetrySettings	実行時のみ使用されるオプトインの再試行設定。モデルの再試行を参照してください。

いずれかのレベルで設定を追加します。

モデル設定

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 で明示的に消去しない限り、Runner とエージェントの設定間でマージされます。

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

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

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

GPT-5.6 では、リクエストレベルの推論モードと明示的なプロンプトキャッシュのブレークポイントが追加されます。reasoning.mode と reasoning.context は Responses 専用の設定です。OpenAIChatCompletionsModel は一度だけ警告してこれらを無視するか、厳格な機能検証が有効な場合はリクエスト前に 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 つのフィールドがあります。

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

再試行ポリシーは、次の情報を含む RetryPolicyContext を受け取ります。

• 試行回数を考慮して判断するための attempt と maxRetries
• ストリーミング動作と非ストリーミング動作を分岐するための stream
• 元の情報を確認するための error
• statusCode、retryAfterMs、errorCode、isNetworkError、isAbort などの正規化された情報
• 基盤となるモデルまたはプロバイダーが再試行の指針を提供できる場合の providerAdvice
• アプリケーションのポリシーがプロバイダー固有のエラーを再解釈せず、Runner の安定した再実行分類を確認するための 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 が明示的に設定されている場合にのみ、この承認が保持されます。

Runner とエージェントのマージ動作

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

• エージェントは retry.maxRetries のみを上書きし、Runner の policy を継承できます
• エージェントは retry.backoff の一部のみを上書きし、Runner の他のバックオフフィールドを維持できます
• 継承した policy または backoff を削除する必要がある場合は、そのフィールドを明示的に undefined に設定します

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

---

プロンプト

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

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

フィールド	型	注記
promptId	string	プロンプトの一意な識別子
version	string	使用するプロンプトのバージョン
variables	object	プロンプトに代入する変数のキーと値のペア。値には文字列、またはテキスト、画像、ファイルなどのコンテンツ入力型を指定できます。

prompt を使用するエージェント

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);
});

ツールや instructions など、追加のエージェント設定は、保存済みプロンプトで設定した値を上書きします。

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

---

高度なプロバイダーと可観測性

カスタムモデルプロバイダー

独自のプロバイダーは簡単に実装できます。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 で、デフォルトとして同じプロバイダーを使用するには、アプリケーションの起動時に一度設定します。

デフォルトモデルプロバイダーの設定

import { setDefaultModelProvider } from '@openai/agents';

setDefaultModelProvider({
  async getModel() {
    // Return any Model implementation here.
    throw new Error('Provide your own model implementation.');
  },
});

これは、アプリケーションで OpenAI 以外のプロバイダーを標準化し、すべての場所でカスタム Runner を渡したくない場合に便利です。

AI SDK 連携

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

---

トレーシングの認証情報

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

トレーシングのエクスポート用 API キーの設定

import { setTracingExportApiKey } from '@openai/agents';

setTracingExportApiKey('sk-...');

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

---

次のステップ

• エージェントの実行を確認します
• ツールでモデルの能力を強化します
• 必要に応じてガードレールまたはトレーシングを追加します