SDK の設定

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

特定の 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') を使用し、HTTP に戻すには 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