コンテンツにスキップ

モデル

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

  • Model – 特定 API へ 1 回 のリクエスト方法を知っています
  • ModelProvider – 人が読みやすいモデル 名前(例: 'gpt-4o')を Model インスタンスへ解決します

日常の開発では、通常モデルの 名前 と、たまに ModelSettings だけを扱います。

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

デフォルトの ModelProvider は OpenAI の API を使って名前を解決します。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 クライアントを差し込むこともできます。

OpenAI プロバイダーの既定モデルは gpt-4o です。エージェント単位またはグローバルで上書きできます:

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

ModelSettings は OpenAI のパラメーターを反映していますが、プロバイダー非依存です。

FieldTypeNotes
temperaturenumber創造性と決定論のバランス
topPnumberニュークレアスサンプリング
frequencyPenaltynumber重複トークンをペナルティ
presencePenaltynumber新規トークンを促進
toolChoice'auto' | 'required' | 'none' | stringツール利用の強制 を参照
parallelToolCallsbooleanサポートされている場合に並列関数呼び出しを許可
truncation'auto' | 'disabled'トークン切り捨て戦略
maxTokensnumber応答内の最大トークン数
storeboolean取得 / RAG ワークフロー用に応答を永続化

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

モデル設定
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 を使用する場合のみサポートされています。

FieldTypeNotes
prompt_idstringプロンプトの一意識別子
versionstring使用したいプロンプトのバージョン
variablesobjectプロンプトに挿入する変数のキー/バリューのペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力型を指定できます
モデル設定
import { Agent, run } from '@openai/agents';
async function main() {
const agent = new Agent({
name: 'Assistant',
prompt: {
promptId: 'pmpt_684b3b772e648193b92404d7d0101d8a07f7a7903e519946',
version: '1',
variables: {
poem_style: 'limerick',
},
},
});
const result = await run(agent, 'Write about unrequited love.');
console.log(result.finalOutput);
}
if (require.main === module) {
main().catch(console.error);
}

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


独自プロバイダーの実装は簡単です。ModelProviderModel を実装し、そのプロバイダーを 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 プロバイダーを使用する際、API キーを渡すことで自動トレースエクスポートを有効にできます:

トレーシングエクスポーター
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

これによりトレースが OpenAI ダッシュボード に送信され、ワークフローの完全な実行グラフを確認できます。