コンテンツにスキップ

SDK の設定

このページでは、デフォルトの OpenAI クライアント、トランスポート、トレースのエクスポート用キー、デバッグログの動作など、通常はアプリの起動時に一度だけ設定する SDK 全体のデフォルト設定 について説明します。これらの設定はデフォルトでプロセス全体に適用されるため、エージェントごとや実行ごとの調整ではなく、全体に共通する設定に適しています。

特定の Agent、Runner、または run() 呼び出しを設定する場合は、次のページをご覧ください。

OpenAI クライアントとトランスポート

Section titled “OpenAI クライアントとトランスポート”

デフォルトでは、SDK は OpenAI クライアントの作成が必要になった時点で OPENAI_API_KEY を遅延解決します。環境変数を設定できない場合は、setDefaultOpenAIKey() を手動で呼び出してください。

デフォルトの OpenAI キーの設定
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

独自の OpenAI クライアントインスタンスを渡すこともできます。渡さない場合、SDK はデフォルトのキーを使って自動的にインスタンスを作成します。

デフォルトの OpenAI クライアントの設定
import { OpenAI } from 'openai';
import { setDefaultOpenAIClient } from '@openai/agents';
const customClient = new OpenAI({ baseURL: '...', apiKey: '...' });
setDefaultOpenAIClient(customClient);

また、Responses API と Chat Completions API を切り替えることもできます。

OpenAI API の設定
import { setOpenAIAPI } from '@openai/agents';
setOpenAIAPI('chat_completions');

Responses API を使用している場合は、OpenAI プロバイダーのトランスポートも選択できます。デフォルトは HTTP です。

Responses トランスポートの設定
import { setOpenAIAPI, setOpenAIResponsesTransport } from '@openai/agents';
setOpenAIAPI('responses');
setOpenAIResponsesTransport('websocket');

WebSocket トランスポートを有効にするには setOpenAIResponsesTransport('websocket') を、HTTP に戻すには setOpenAIResponsesTransport('http') を使用します。WebSocket トラフィックをプロキシやゲートウェイ経由でルーティングする場合は、OPENAI_WEBSOCKET_BASE_URL を設定してください(または OpenAIProvider の websocketBaseURL を設定してください)。

このプロセス全体に適用されるデフォルト設定は、設定後にデフォルトの OpenAI プロバイダーを通じて解決されるモデルにのみ影響します。具体的な Model インスタンスやカスタムの modelProvider を渡す場合は、そちらでトランスポートを設定してください。モデルをご覧ください。

トレーシングは、サポートされているサーバーランタイムではデフォルトで有効です。ブラウザーや NODE_ENV=test の場合は、デフォルトで無効です。

デフォルトでは、トレースのエクスポートに上記のセクションと同じ OpenAI キーを使用します。

setTracingExportApiKey() を使って別のキーを設定できます。

トレースのエクスポート用 API キーの設定
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

トレーシングを完全に無効にすることもできます。

トレーシングの無効化
import { setTracingDisabled } from '@openai/agents';
setTracingDisabled(true);

トレーシング機能について詳しくは、トレーシングをご覧ください。

SDK はデバッグログに debug パッケージを使用します。詳細なログを表示するには、環境変数 DEBUG を openai-agents* に設定してください。

ターミナルウィンドウ
export DEBUG=openai-agents*

セッションの永続化処理をログに記録するには、OPENAI_AGENTS__DEBUG_SAVE_SESSION=1 を設定してください。

@openai/agents の getLogger(namespace) を使って、独自のモジュール用に名前空間付きのロガーを取得できます。

ロガーの取得
import { getLogger } from '@openai/agents';
const logger = getLogger('my-app');
logger.debug('something happened');

モデルやツールのデータは、関連するエラーオブジェクトや詳細情報を含め、デフォルトではログに記録されません。デバッグ中にこれらの詳細情報が必要な場合は、プロセス全体で機密データのログ記録を明示的に有効にできます。

機密データのログ記録の有効化
import { setSensitiveDataLoggingEnabled } from '@openai/agents';
setSensitiveDataLoggingEnabled(true);

ログが安全に扱われる環境でのみ有効にしてください。このプログラムによる設定は、モデルとツールの両方のデータを制御し、以下の環境変数よりも優先されます。機密データのログ記録を再び無効にするには、setSensitiveDataLoggingEnabled(false) を呼び出してください。

環境変数を使って、モデルとツールのデータのログ記録を個別に有効にすることもできます。対応する OPENAI_AGENTS_DONT_LOG_* 変数を 0 または false に設定してください。

ターミナルウィンドウ
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

いずれかの変数を 1 または true に設定すると、対応するデータと関連するエラーの詳細情報は引き続きマスキングされます。未設定の場合や値が認識されない場合も、安全なデフォルト設定が使用され、機密データはログに記録されません。