構成

このページでは、デフォルトの OpenAI キーまたはクライアント、デフォルトの OpenAI API 形式、トレーシングのエクスポートに関するデフォルト設定、ログ動作など、通常はアプリケーションの起動時に一度だけ設定する SDK 全体のデフォルトについて説明します。

これらのデフォルトはサンドボックスベースのワークフローにも適用されますが、サンドボックスワークスペース、サンドボックスクライアント、セッションの再利用は個別に構成します。

代わりに特定のエージェントまたは実行を構成する必要がある場合は、以下から始めてください。

通常の Agent に対する指示、ツール、出力型、ハンドオフ、ガードレールについては、エージェントを参照してください。
RunConfig、セッション、会話状態のオプションについては、エージェントの実行を参照してください。
SandboxRunConfig、マニフェスト、ケイパビリティ、サンドボックスクライアント固有のワークスペース設定については、サンドボックスエージェントを参照してください。
モデルの選択とプロバイダーの構成については、モデルを参照してください。
実行単位のトレーシングメタデータとカスタムトレースプロセッサーについては、トレーシングを参照してください。

構成オブジェクトと辞書

SDK で定義される構成パラメーターは通常、型付きの設定オブジェクト、または同じフィールドを含む辞書のいずれかを受け付けます。これは、型アノテーションに辞書が含まれるエージェント、実行、モデル、セッション、サンドボックス、音声の各構成境界に適用されます。SDK で定義されたネストされた設定型にも辞書を使用できます。

from agents import Agent

agent = Agent(
    name="Assistant",
    model="gpt-5.6-sol",
    model_settings={
        "reasoning": {"effort": "high"},
        "verbosity": "low",
    },
)

SDK は、これらの辞書を対応する設定オブジェクトに正規化します。SDK で定義されたデータクラス構成型に不明なフィールドがあると TypeError が発生するため、オプション名の入力ミスを早期に検出できます。特定の境界が辞書を受け付けるかどうかを確認するには、そのパラメーターの型アノテーションまたは API リファレンスを確認してください。

API キーとクライアント

デフォルトでは、SDK は LLM リクエストとトレーシングに OPENAI_API_KEY 環境変数を使用します。キーは SDK が最初に OpenAI クライアントを作成するときに解決されるため（遅延初期化）、最初のモデル呼び出しの前に環境変数を設定してください。アプリの起動前にその環境変数を設定できない場合は、set_default_openai_key() 関数を使用してキーを設定できます。

from agents import set_default_openai_key

set_default_openai_key("sk-...")

また、使用する OpenAI クライアントを構成することもできます。デフォルトでは、SDK は環境変数の API キーまたは上記で設定したデフォルトキーを使用して AsyncOpenAI インスタンスを作成します。set_default_openai_client() 関数を使用すると、これを変更できます。

from openai import AsyncOpenAI
from agents import set_default_openai_client

custom_client = AsyncOpenAI(base_url="...", api_key="...")
set_default_openai_client(custom_client)

明示的なクライアントを OpenAIProvider に渡す場合、そのクライアントが接続設定とアカウント設定を管理します。OpenAIProvider に api_key、base_url、websocket_base_url、organization、project も渡さないでください。openai_client とこれらの引数のいずれかを組み合わせると、重複した値が暗黙に無視されるのではなく、UserError が発生します。意図した値は AsyncOpenAI の構築時に設定してください。

openai_client を省略した場合、api_key、base_url、websocket_base_url、organization、project がすべて None のときに限り、OpenAIProvider は SDK 全体のデフォルトクライアントを再利用します。空文字列を含め、これらのオプションのいずれかを渡すと、プロバイダーは独自のクライアントを作成し、プロバイダーオプションが SDK 全体のデフォルトクライアントより優先されます。プロバイダーが set_default_openai_client() によって設定されたクライアントを継承する必要がある場合は、すべてのプロバイダーオプションを None のままにしてください。

OpenAIVoiceModelProvider は、api_key、base_url、organization、project に対して、同じ所有権と優先順位のルールを使用します。明示的な openai_client を、これら 4 つのオプションのいずれかと組み合わせることはできません。

`openai` v3 でのカスタム HTTP クライアント

バージョン 0.21.0 では openai>=3.0.0,<4 が必要です。デフォルトの OpenAI プロバイダーは HTTPX2 を使用するため、ほとんどのアプリケーションでは HTTP クライアントを直接構成する必要はありません。アプリケーションから AsyncOpenAI に http_client= を渡す場合は、カスタムクライアントとそのトランスポート関連オプションに HTTPX2 の型を使用してください。

import httpx2
from openai import AsyncOpenAI, DefaultAsyncHttpx2Client

from agents import set_default_openai_client

http_client = DefaultAsyncHttpx2Client(
    timeout=httpx2.Timeout(30.0, connect=5.0),
)
custom_client = AsyncOpenAI(
    api_key="...",
    http_client=http_client,
)
set_default_openai_client(custom_client)

同じ移行が、カスタムトランスポート、認証、イベントフック、モックトランスポート、URL、リクエスト、レスポンス、トランスポート例外処理にも適用されます。それぞれの httpx2 相当のものを使用してください。Agents SDK は、任意の従来の httpx オブジェクトを HTTPX2 に変換しません。アプリケーションが httpx を明示的にインストールすると、OpenAI Python SDK は従来のクライアント向けに一時的な互換性確保の手段を提供しますが、新規コードおよび移行済みコードでは HTTPX2 を使用する必要があります。

この OpenAI クライアント境界は、ローカル MCP トランスポートのカスタマイズとは別のものです。MCP Python SDK v1 は独自の従来の httpx 依存関係を使用し、MCP Python SDK v2 は httpx2 を使用します。MCP Python SDK v1 と v2を参照してください。

環境変数ベースのエンドポイント構成を使用する場合、デフォルトの OpenAI プロバイダーは OPENAI_BASE_URL も読み取ります。Responses の WebSocket トランスポートを有効にすると、WebSocket の /responses エンドポイント用に OPENAI_WEBSOCKET_BASE_URL も読み取ります。

export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1"
export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1"

最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは、OpenAI Responses API を使用します。set_default_openai_api() 関数を使用すると、これをオーバーライドして Chat Completions API を使用できます。

from agents import set_default_openai_api

set_default_openai_api("chat_completions")

OpenAI プロバイダーのデフォルト

SDK の OpenAI バックエンドを使用するプロバイダーも、モデル名の文字列をモデルに対応付ける際に、SDK 全体のデフォルトを読み取ります。OpenAI Responses モデルでデフォルトで WebSocket トランスポートを使用するには、set_default_openai_responses_transport() を使用します。

from agents import set_default_openai_responses_transport

set_default_openai_responses_transport("websocket")

これは、デフォルトの OpenAI プロバイダーがモデル名を解決した結果として得られる OpenAI Responses モデルに影響します。プロバイダーレベルの設定、接続の再利用、キープアライブオプション、カスタム WebSocket エンドポイントについては、Responses WebSocket トランスポートを参照してください。

OpenAI の設定でプロバイダーレベルのエージェント登録メタデータが必要な場合は、起動時にデフォルトのハーネス ID を一度構成します。

from agents import set_default_openai_harness

set_default_openai_harness("your-harness-id")

完全な登録オブジェクトを渡すこともできます。

from agents import OpenAIAgentRegistrationConfig, set_default_openai_agent_registration

set_default_openai_agent_registration(
    OpenAIAgentRegistrationConfig(harness_id="your-harness-id")
)

SDK のデフォルトが設定されていない場合、SDK の OpenAI バックエンドを使用するプロバイダーは OPENAI_AGENT_HARNESS_ID 環境変数にフォールバックします。ハーネス ID が構成されている場合、RunConfig.trace_metadata にそのキーがすでに存在しない限り、SDK はトレースメタデータに agent_harness_id として追加します。

トレーシング

トレーシングはデフォルトで有効です。デフォルトでは、上記のセクションにあるモデルリクエストと同じ OpenAI API キー、つまり環境変数または設定したデフォルトキーを使用します。トレーシングに使用する API キーを個別に設定するには、set_tracing_export_api_key 関数を使用します。

from agents import set_tracing_export_api_key

set_tracing_export_api_key("sk-...")

モデルの通信で 1 つのキーまたはクライアントを使用し、トレーシングでは別の OpenAI キーを使用する必要がある場合は、デフォルトのキーまたはクライアントを設定するときに use_for_tracing=False を渡し、その後トレーシングを個別に構成します。カスタムクライアントを使用していない場合は、set_default_openai_key() でも同じ方法を使用できます。

from openai import AsyncOpenAI
from agents import (
    set_default_openai_client,
    set_tracing_export_api_key,
)

custom_client = AsyncOpenAI(base_url="https://your-openai-compatible-endpoint.example/v1", api_key="provider-key")
set_default_openai_client(custom_client, use_for_tracing=False)

set_tracing_export_api_key("sk-tracing")

デフォルトのエクスポーターを使用して、特定の組織またはプロジェクトにトレースを関連付ける必要がある場合は、アプリの起動前に次の環境変数を設定します。

export OPENAI_ORG_ID="org_..."
export OPENAI_PROJECT_ID="proj_..."

グローバルエクスポーターを変更せずに、実行ごとにトレーシング API キーを設定することもできます。

from agents import Runner, RunConfig

await Runner.run(
    agent,
    input="Hello",
    run_config=RunConfig(tracing={"api_key": "sk-tracing-123"}),
)

set_tracing_disabled() 関数を使用して、トレーシングを完全に無効にすることもできます。

from agents import set_tracing_disabled

set_tracing_disabled(True)

トレーシングを有効なまま維持しつつ、機密情報を含む可能性のある入出力をトレースペイロードから除外するには、RunConfig.trace_include_sensitive_data を False に設定します。

from agents import Runner, RunConfig

await Runner.run(
    agent,
    input="Hello",
    run_config=RunConfig(trace_include_sensitive_data=False),
)

アプリの起動前に次の環境変数を設定することで、コードを使わずにデフォルトを変更することもできます。

export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0

トレーシングのすべての制御については、トレーシングガイドを参照してください。

デバッグログ

SDK は 2 つの Python ロガー（openai.agents と openai.agents.tracing）を定義しますが、デフォルトではハンドラーをアタッチしません。ログは、アプリケーションの Python ロギング構成に従います。

詳細ログを有効にするには、enable_verbose_stdout_logging() 関数を使用します。

from agents import enable_verbose_stdout_logging

enable_verbose_stdout_logging()

また、ハンドラー、フィルター、フォーマッターなどを追加して、ログをカスタマイズすることもできます。詳細については、Python ロギングガイドを参照してください。

import logging

logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger

# To make all logs show up
logger.setLevel(logging.DEBUG)
# To make info and above show up
logger.setLevel(logging.INFO)
# To make warning and above show up
logger.setLevel(logging.WARNING)
# etc

# You can customize this as needed, but this will output to `stderr` by default
logger.addHandler(logging.StreamHandler())

ログと診断情報に含まれる機密データ

一部のログや診断例外には、機密データが含まれる場合があります（たとえば、モデルやツールの入出力）。

デフォルトでは、SDK は LLM の入出力やツールの入出力を ログに記録しません 。これらの保護は以下によって制御されます。

OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1

デバッグのためにこのデータを一時的に含める必要がある場合は、アプリの起動前にいずれかの変数を 0（または false）に設定します。

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

これらのフラグは、影響を受けるエラーでペイロードを含む診断の詳細を保持するかどうかも制御します。たとえば、ツールデータの編集が有効な場合、FunctionTool の無効な引数によって、基礎となる検証エラーを例外チェーンに含まない汎用的な ModelBehaviorError が発生します。いずれかの変数を 0 に設定すると、ログ、例外メッセージ、例外チェーン、その他の診断コンテキストに未加工のモデルデータまたはツールデータが公開される可能性があるため、管理された開発環境でのみ有効にしてください。

構成