モデル

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

• Model – 特定の API に対して 1 回 のリクエストを行う方法を理解しています
• ModelProvider – 人間が読みやすいモデル 名（例: 'gpt‑5.4'）を Model インスタンスに解決します

日常的な利用では、通常はモデル 名 と、必要に応じて ModelSettings のみを扱います。

エージェントごとのモデル指定

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

const agent = new Agent({
  name: 'Creative writer',
  model: 'gpt-5.4',
});

モデルの選択

デフォルトモデル

Agent の初期化時にモデルを指定しない場合は、デフォルトモデルが使われます。互換性と低レイテンシのため、現在のデフォルトは gpt-4.1 です。アクセス可能であれば、modelSettings を明示したうえで、より高品質な gpt-5.4 をエージェントに設定することを推奨します。

gpt-5.4 のような他モデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。

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

export OPENAI_DEFAULT_MODEL=gpt-5.4
node my-awesome-agent.js

2 つ目は、Runner インスタンスにデフォルトモデルを設定する方法です。エージェント側でモデルを設定しなければ、この Runner のデフォルトモデルが使われます。

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

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

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

GPT-5.x モデル

この方法で gpt-5.4 などの 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.4 is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.4',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

レイテンシが重要な場合は、gpt-5.4 でまず reasoning.effort: "none" から始め、より慎重な推論が必要なタスクの場合のみ増やしてください。gpt-4.1 ファミリー（ mini / nano を含む）も、対話型エージェントアプリ構築の堅実な選択肢です。

非 GPT-5 モデル

カスタム modelSettings なしで非 GPT-5 モデル名を渡した場合、SDK は任意モデルと互換性のある汎用 modelSettings に戻します。

---

OpenAI プロバイダー設定

OpenAI プロバイダー

デフォルトの ModelProvider は OpenAI API を使って名前解決します。次の 2 種類のエンドポイントをサポートします:

API	用途	setOpenAIAPI() 呼び出し
Chat Completions	標準チャットと function calls	setOpenAIAPI('chat_completions')
Responses	新しいストリーミング優先の生成 API（ tool calls、柔軟な出力）	setOpenAIAPI('responses') (デフォルト)

認証

デフォルト OpenAI キーの設定

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

setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

カスタムネットワーク設定が必要な場合は、setDefaultOpenAIClient(client) を使って独自の OpenAI クライアントを接続することもできます。

Responses WebSocket トランスポート

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

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

WebSocket トランスポートを使うだけなら、withResponsesWebSocketSession(...) やカスタム OpenAIProvider は不要です。各 run / request ごとの再接続を許容できるなら、setOpenAIResponsesTransport('websocket') を有効化した後も既存の run() / Runner.run() はそのまま動作します。

トランスポート選択はモデル解決に従います:

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

withResponsesWebSocketSession(...) やカスタム OpenAIProvider / Runner は、接続再利用の最適化や websocket provider ライフサイクルをより明示的に管理したい場合にのみ使います:

• withResponsesWebSocketSession(...): コールバック後に自動クリーンアップされる便利なスコープ付きライフサイクル
• カスタム OpenAIProvider / Runner: 独自アプリ構成内での明示的ライフサイクル制御（シャットダウン時クリーンアップを含む）

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

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

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

Responses WebSocket トランスポートを使った完全な streaming + HITL の例は examples/basic/stream-ws.ts を参照してください。

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

toolSearchTool(), toolNamespace(), および deferLoading: true を設定した関数ツールや hosted MCP tools は OpenAI Responses API が必要です。Chat Completions プロバイダーは namespaced または遅延関数ツールを拒否し、AI SDK アダプターは遅延 Responses tool-loading フローをサポートしません。ツール検索が必要な場合は Responses モデルを直接使用してください。

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

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

---

モデル動作とプロンプト

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	サポートされる場合に並列 function calls を許可
truncation	'auto' | 'disabled'	トークン切り捨て戦略
maxTokens	number	レスポンス内の最大トークン数
store	boolean	取得 / RAG ワークフロー向けにレスポンスを永続化
promptCacheRetention	'in-memory' | '24h' | null	サポート時のプロバイダープロンプトキャッシュ保持を制御
reasoning.effort	'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'	gpt-5.x モデルの推論努力
reasoning.summary	'auto' | 'concise' | 'detailed'	モデルが返す推論サマリー量を制御
text.verbosity	'low' | 'medium' | 'high'	gpt-5.x などのテキスト冗長度
providerData	Record<string, any>	基盤モデルに転送されるプロバイダー固有のパススルーオプション
retry	ModelRetrySettings	実行時専用のオプトイン再試行設定。Model retries を参照

設定はどちらのレベルにも付与できます:

モデル設定

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 レベルの設定は、競合するエージェント単位設定を上書きします。例外は retry で、undefined で継承値を明示的にクリアしない限り、runner と agent の設定間でネストフィールドがマージされます。

Model retries

再試行は実行時専用でオプトインです。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 を返さずに再試行した場合のデフォルト遅延戦略
policy	RetryPolicy	再試行可否を判断するコールバック。この関数は実行時専用で、永続化された run 状態にはシリアライズされません

再試行ポリシーは RetryPolicyContext を受け取ります。内容は次のとおりです:

• attempt と maxRetries（試行回数に応じた判断が可能）
• stream（ストリーミング / 非ストリーミングで分岐可能）
• error（生エラーの検査用）
• normalized 情報（statusCode, retryAfterMs, errorCode, isNetworkError, isAbort）
• 基盤モデル / プロバイダーが再試行指針を提供できる場合の providerAdvice

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

• 単純な再試行判定として true / false
• 遅延上書きやログ用診断理由を付けたい場合の { retry, delayMs?, reason? }

SDK は retryPolicies に既成ヘルパーを提供しています:

ヘルパー	挙動
retryPolicies.never()	常に再試行しない
retryPolicies.providerSuggested()	可能な場合はプロバイダーの再試行助言に従う
retryPolicies.networkError()	一時的なトランスポート / 接続障害に一致
retryPolicies.httpStatus([..])	指定した HTTP ステータスコードに一致
retryPolicies.retryAfter()	retry-after ヒントがある場合のみ、その遅延で再試行
retryPolicies.any(...)	ネストされたいずれかのポリシーがオプトインしたら再試行
retryPolicies.all(...)	ネストされたすべてのポリシーがオプトインした場合のみ再試行

ポリシーを組み合わせる場合、providerSuggested() は最初の構成要素として最も安全です。プロバイダーが区別可能な場合、プロバイダー拒否や replay 安全性承認を保持できるためです。

安全境界

次の障害は自動再試行されません:

• Abort エラー
• 可視イベントまたは生モデルイベントがすでに 1 つでも送出された後のストリーミング run
• replay が unsafe と示すプロバイダー助言

previousResponseId や conversationId を使う状態保持フォローアップリクエストも、より保守的に扱われます。これらでは networkError() や httpStatus([500]) などの非プロバイダー述語だけでは不十分です。再試行ポリシーには、通常 retryPolicies.providerSuggested() によるプロバイダーの replay-safe 承認を含める必要があります。

Runner と agent のマージ挙動

retry は runner レベルと agent レベルの modelSettings 間でディープマージされます:

• agent は retry.maxRetries のみを上書きし、runner の policy を継承可能
• agent は retry.backoff の一部のみを上書きし、他の 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	プロンプトに差し込む変数の key/value ペア。値は文字列またはテキスト・画像・ファイルなどの content input type を指定可能

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

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

保存済みプロンプトですでにモデルが定義されている場合、明示的に上書きしない限り SDK はエージェントのデフォルトモデルを送信しません。これは computerTool() で重要で、プロンプト管理 run は互換性のため既定で legacy preview wire 形状を維持します。プロンプト管理 run で GA Responses コンピュータツールを有効化するには、modelSettings.toolChoice: 'computer' を明示設定するか、gpt-5.4 のような明示モデルを送信してください。周辺のコンピュータ操作詳細は ツール を参照してください。

---

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

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

独自プロバイダーの実装は簡単です。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 連携 を参照してください。このアダプターを使うと Agents runtime に AI SDK モデルを直接接続できます。アプリがすでに AI SDK プロバイダーを標準化している場合や、より広いプロバイダーエコシステムを使いたい場合に便利です。また、Agents SDK の providerData と AI SDK の providerMetadata の対応、および AI SDK UI ルートで使える stream ヘルパーも説明しています。

---

トレーシング認証情報

対応サーバーランタイムではトレーシングはすでにデフォルト有効です。トレースエクスポートでデフォルト OpenAI API キーとは別資格情報を使いたい場合のみ setTracingExportApiKey() を使ってください:

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

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

setTracingExportApiKey('sk-...');

これにより、その資格情報で OpenAI dashboard にトレースが送信されます。カスタム ingest endpoint や再試行調整など exporter のカスタマイズは トレーシング を参照してください。

---

次のステップ

• エージェントの実行 を確認する
• ツール でモデルをさらに強化する
• 必要に応じて ガードレール や トレーシング を追加する