モデル
すべてのエージェントは最終的に 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',});
OpenAI プロバイダー
Section titled “OpenAI プロバイダー”デフォルトの ModelProvider
は OpenAI の API を使って名前を解決します。2 つのエンドポイントをサポートします:
API | 使用用途 | setOpenAIAPI() 呼び出し |
---|---|---|
Chat Completions | 標準的なチャットと関数呼び出し | setOpenAIAPI('chat_completions') |
Responses | ストリーミング優先の新しい生成 API(ツール呼び出し、柔軟な出力) | setOpenAIAPI('responses') (default) |
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...
ネットワーク設定をカスタマイズしたい場合は、setDefaultOpenAIClient(client)
で独自の OpenAI
クライアントを差し込むこともできます。
既定のモデル
Section titled “既定のモデル”OpenAI プロバイダーの既定モデルは gpt-4o
です。エージェント単位またはグローバルで上書きできます:
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt‑4.1-mini' });
ModelSettings
Section titled “ModelSettings”ModelSettings
は OpenAI のパラメーターを反映していますが、プロバイダー非依存です。
Field | Type | Notes |
---|---|---|
temperature | number | 創造性と決定論のバランス |
topP | number | ニュークレアスサンプリング |
frequencyPenalty | number | 重複トークンをペナルティ |
presencePenalty | number | 新規トークンを促進 |
toolChoice | 'auto' | 'required' | 'none' | string | ツール利用の強制 を参照 |
parallelToolCalls | boolean | サポートされている場合に並列関数呼び出しを許可 |
truncation | 'auto' | 'disabled' | トークン切り捨て戦略 |
maxTokens | number | 応答内の最大トークン数 |
store | boolean | 取得 / RAG ワークフロー用に応答を永続化 |
設定はどちらのレベルにも付与できます:
import { Runner, Agent } from '@openai/agents';
const agent = new Agent({ name: 'Creative writer', // ... modelSettings: { temperature: 0.7, toolChoice: 'auto' },});
// or globallynew Runner({ modelSettings: { temperature: 0.3 } });
Runner
レベルの設定は、エージェントレベルの競合する設定を上書きします。
エージェントは prompt
パラメーターで設定でき、これはサーバーに保存されたプロンプト設定を指し、エージェントの挙動を制御します。現在、このオプションは OpenAI の Responses API を使用する場合のみサポートされています。
Field | Type | Notes |
---|---|---|
prompt_id | string | プロンプトの一意識別子 |
version | string | 使用したいプロンプトのバージョン |
variables | object | プロンプトに挿入する変数のキー/バリューのペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力型を指定できます |
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 など追加のエージェント設定は、保存済みプロンプト内で設定した値を上書きします。
カスタムモデルプロバイダー
Section titled “カスタムモデルプロバイダー”独自プロバイダーの実装は簡単です。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);
トレーシングエクスポーター
Section titled “トレーシングエクスポーター”OpenAI プロバイダーを使用する際、API キーを渡すことで自動トレースエクスポートを有効にできます:
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');
これによりトレースが OpenAI ダッシュボード に送信され、ワークフローの完全な実行グラフを確認できます。