Kazuhiro Sera
15 KiB
search
| search | ||
|---|---|---|
|
設定
このページでは、デフォルトの 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()][agents.set_default_openai_key] 関数を使用してキーを設定できます。
from agents import set_default_openai_key
set_default_openai_key("sk-...")
また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数の API キーまたは上記で設定したデフォルトキーを使用して、AsyncOpenAI インスタンスを作成します。[set_default_openai_client()][agents.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][agents.models.openai_provider.OpenAIProvider] に渡すと、そのクライアントが接続とアカウントの設定を管理します。api_key、base_url、websocket_base_url、organization、project を OpenAIProvider に同時に渡さないでください。openai_client とこれらの引数のいずれかを組み合わせると、重複する値が暗黙に無視されるのではなく、[UserError][agents.exceptions.UserError] が発生します。目的の値は AsyncOpenAI の構築時に設定してください。
openai v3 でのカスタム HTTP クライアント
バージョン 0.21.0 では openai>=3.0.0,<4 が必要です。デフォルトの OpenAI プロバイダーは HTTPX2 を使用するため、ほとんどのアプリケーションでは HTTP クライアントを直接設定する必要はありません。アプリケーションが http_client= を AsyncOpenAI に渡す場合は、カスタムクライアントとそのトランスポート向けオプションに 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()][agents.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()][agents.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][agents.set_tracing_export_api_key] 関数を使用します。
from agents import set_tracing_export_api_key
set_tracing_export_api_key("sk-...")
モデルのトラフィックではあるキーまたはクライアントを使用し、トレーシングでは別の OpenAI キーを使用する必要がある場合は、デフォルトのキーまたはクライアントを設定するときに use_for_tracing=False を渡し、その後トレーシングを個別に設定します。カスタムクライアントを使用していない場合は、[set_default_openai_key()][agents.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()][agents.set_tracing_disabled] 関数を使用して、トレーシングを完全に無効にすることもできます。
from agents import set_tracing_disabled
set_tracing_disabled(True)
トレーシングを有効なままにしつつ、機密情報を含む可能性のある入力や出力をトレースペイロードから除外する場合は、[RunConfig.trace_include_sensitive_data][agents.run.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()][agents.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 に設定すると、ログ、例外メッセージ、例外チェーン、その他の診断コンテキストに未加工のモデルデータまたはツールデータが公開される可能性があるため、管理された開発環境でのみ有効にしてください。