SDK の設定

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

特定の Agent、Runner、または run() 呼び出しを設定する必要がある場合は、以下を参照してください。

エージェントの実行: Runner と実行ごとのオプション
モデル: エージェントレベルおよび Runner レベルのモデル設定
トレーシング: 実行固有のトレーシング設定とエクスポーターの挙動

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

API キーとクライアント

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

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

setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

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

import { OpenAI } from 'openai';
import { setDefaultOpenAIClient } from '@openai/agents';

const customClient = new OpenAI({ baseURL: '...', apiKey: '...' });
setDefaultOpenAIClient(customClient);

API の選択

最後に、Responses API と Chat Completions API を切り替えることができます。

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

setOpenAIAPI('chat_completions');

Responses トランスポート

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

import { setOpenAIAPI, setOpenAIResponsesTransport } from '@openai/agents';

setOpenAIAPI('responses');
setOpenAIResponsesTransport('websocket');

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

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

可観測性とデバッグ

トレーシング

トレーシングは、対応しているサーバーランタイムではデフォルトで有効です。ブラウザ内および NODE_ENV=test の場合は、デフォルトで無効です。

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

別のキーは setTracingExportApiKey() で設定できます。

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');

ログ内の機微データ

一部のログにはユーザーデータが含まれる場合があります。これらは以下の環境変数を設定することで無効にできます。

LLM の入力と出力のログを無効にするには、次のようにします。

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1

ツールの入力と出力のログを無効にするには、次のようにします。

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1