モデル

すべてのエージェントは最終的に 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-5.4-mini で、品質とレイテンシーのバランスを取るために reasoning.effort: "none" と text.verbosity: "low" が設定されています。

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

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

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

次に、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 を渡します。

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-mini 設定から始めるか、別の 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')` (デフォルト)

認証

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 は必要ありません。各実行/リクエストごとに再接続してよい場合、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 を設定してください。

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

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

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

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

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

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

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

ModelSettings

ModelSettings は OpenAI のパラメーターを反映しますが、プロバイダーに依存しません。

フィールド	型	注記
`temperature`	`number`	創造性と決定性のバランス。
`topP`	`number`	ニュークリアスサンプリング。
`frequencyPenalty`	`number`	繰り返しトークンにペナルティを与えます。
`presencePenalty`	`number`	新しいトークンを促します。
`toolChoice`	`'auto' \| 'required' \| 'none' \| string`	ツール利用の強制を参照してください。OpenAI Responses では、`toolChoice: 'computer'` は、利用可能な場合に GA 版の組み込み computer ツールを強制します。
`parallelToolCalls`	`boolean`	サポートされている場合に並列関数呼び出しを許可します。
`truncation`	`'auto' \| 'disabled'`	トークン切り捨て戦略。
`maxTokens`	`number`	レスポンス内の最大トークン数。
`store`	`boolean`	検索 / RAG ワークフローのためにレスポンスを永続化します。
`promptCacheRetention`	`'in-memory' \| '24h' \| null`	サポートされている場合にプロバイダーのプロンプトキャッシュ保持を制御します。
`contextManagement`	`ModelSettingsContextManagement`	サーバー側の圧縮など、プロバイダーのコンテキスト管理を制御します。
`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`	ランタイム専用のオプトイン再試行設定。モデル再試行を参照してください。

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

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 とエージェントの設定間でマージされます。

モデル再試行

再試行はランタイム専用で、オプトインです。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` は、この計算されたバックオフ遅延のみに上限を設定します。ポリシーや retry-after ヒントが返す明示的な `delayMs` 値には上限を設定しません。
`policy`	`RetryPolicy`	再試行するかどうかを決定するコールバック。この関数はランタイム専用で、永続化された実行状態にはシリアライズされません。

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

試行回数を考慮した判断を行うための attempt と maxRetries
ストリーミングと非ストリーミングの動作を分岐するための stream
元の内容を検査するための error
statusCode、retryAfterMs、errorCode、isNetworkError、isAbort などの正規化された情報を持つ normalized
基盤となるモデル/プロバイダーが再試行ガイダンスを提供できる場合の providerAdvice

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

単純な再試行判断のための true / false
遅延を上書きする、またはロギング用の診断理由を付与したい場合の { retry, delayMs?, reason? }

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() を通じて、プロバイダーからのリプレイ安全承認を含める必要があります。

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

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

エージェントは retry.maxRetries だけを上書きし、Runner の policy を引き続き継承できます。
エージェントは retry.backoff の一部だけを上書きし、Runner の兄弟 backoff フィールドを保持できます。
継承された policy または backoff を削除する必要がある場合は、そのフィールドを明示的に undefined に設定してください。

ロギング付きのより詳しいコード例については、examples/basic/retry.ts と examples/ai-sdk/retry.ts を参照してください。

プロンプト

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

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

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

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 computer ツールにオプトインするには、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 連携を参照してください。このアダプターを使うと、AI SDK モデルを Agents ランタイムに直接差し込めます。これは、アプリがすでに AI SDK プロバイダーに標準化している場合や、より広いプロバイダーエコシステムにアクセスしたい場合に便利です。また、Agents SDK の providerData が AI SDK の providerMetadata にどのようにマッピングされるかに加えて、AI SDK UI ルートで利用できるストリームヘルパーも説明しています。

トレーシング認証情報

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

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

setTracingExportApiKey('sk-...');

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

次のステップ

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