モデル

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

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

日々の作業では、通常はモデルの名前と、時折 ModelSettings のみを扱います。

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

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

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

モデルの選択

デフォルトモデル

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

gpt-5.2 など他のモデルへ切り替えるには、エージェントを構成する方法が 2 つあります。

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

export OPENAI_DEFAULT_MODEL=gpt-5.2
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.2 のような任意の 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.2 is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.2',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

より低レイテンシを求める場合は、gpt-5.2 とともに reasoning.effort: "none" を使用することをおすすめします。gpt-4.1 ファミリー（mini と nano を含む）も、対話型エージェントアプリの構築における堅実な選択肢のままです。

非 GPT-5 モデル

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

---

OpenAI プロバイダーの設定

OpenAI プロバイダー

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

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

認証

デフォルトの 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 は不要です。各実行／リクエストごとに再接続で問題なければ、setOpenAIResponsesTransport('websocket') を有効にした後も、既存の run() / Runner.run() の使用はそのまま機能します。

接続の再利用を最適化し、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 の code examples は examples/basic/stream-ws.ts を参照してください。

---

モデル動作とプロンプト

ModelSettings

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

フィールド	型	メモ
temperature	number	創造性と決定論のバランス
topP	number	Nucleus サンプリング
frequencyPenalty	number	繰り返しトークンのペナルティ
presencePenalty	number	新しいトークンの促進
toolChoice	'auto' | 'required' | 'none' | string	ツール使用の強制 を参照
parallelToolCalls	boolean	対応している場合に並列の関数呼び出しを許可
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>	基盤モデルにフォワードされるプロバイダー固有の透過オプション

設定はどちらのレベルにもアタッチできます:

Model settings

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 レベルの設定は、競合するエージェントごとの設定を上書きします。

---

プロンプト

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

フィールド	型	メモ
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);
});

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

---

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

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

独自のプロバイダーの実装は簡単です。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);

OpenAI 以外のモデル向けの既製アダプターが必要な場合は、AI SDK で任意モデルを指定 を参照してください。

---

トレーシング資格情報

対応するサーバーランタイムでは、トレーシングは既定で有効になっています。トレースのエクスポートに既定の OpenAI API キーとは異なる資格情報を使用する必要がある場合のみ、 setTracingExportApiKey() を使用してください:

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

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

setTracingExportApiKey('sk-...');

これは、その資格情報を使用して OpenAI ダッシュボード にトレースを送信します。独自の取り込みエンドポイントやリトライ調整など、エクスポーターのカスタマイズについては トレーシング を参照してください。

---

次のステップ

• エージェントの実行 を試す
• ツール でモデルにスーパーパワーを与える
• 必要に応じて ガードレール や トレーシング を追加する