Configuration

This page covers SDK-wide defaults that you usually set once during app startup, such as the default OpenAI client, transport, tracing export key, and debug logging behavior. These settings apply process-wide by default, so this is the right place for universal configuration rather than per-agent or per-run tuning.

If you need to configure a specific Agent, Runner, or run() call instead, see:

• Running Agents for Runner and per-run options.
• Models for agent-level and runner-level model settings.
• Tracing for run-specific tracing configuration and exporter behavior.

OpenAI client and transport

API keys and clients

By default the SDK resolves OPENAI_API_KEY lazily when it needs to create an OpenAI client. If setting the environment variable is not possible, call setDefaultOpenAIKey() manually.

Set default OpenAI key

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

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

You may also pass your own OpenAI client instance. The SDK will otherwise create one automatically using the default key.

Set default OpenAI client

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

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

API selection

Finally you can switch between the Responses API and the Chat Completions API.

Set OpenAI API

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

setOpenAIAPI('chat_completions');

Responses transport

If you are using the Responses API, you can also choose the OpenAI provider transport. The default is HTTP.

Set Responses transport

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

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

Use setOpenAIResponsesTransport('websocket') to enable the WebSocket transport and setOpenAIResponsesTransport('http') to switch back. If you route websocket traffic through a proxy or gateway, set OPENAI_WEBSOCKET_BASE_URL (or configure websocketBaseURL on your OpenAIProvider).

This process-wide default only affects models that are later resolved through the default OpenAI provider. If you pass a concrete Model instance or a custom modelProvider, configure the transport there instead. See the Models guide.

Observability and debugging

Tracing

Tracing is enabled by default in supported server runtimes. It is disabled by default in browsers and when NODE_ENV=test.

By default trace export uses the same OpenAI key from the section above.

A separate key may be set via setTracingExportApiKey():

Set tracing export API key

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

setTracingExportApiKey('sk-...');

Tracing can also be disabled entirely:

Disable tracing

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

setTracingDisabled(true);

If you’d like to learn more about the tracing feature, please check out Tracing guide.

Debug logging

The SDK uses the debug package for debug logging. Set the DEBUG environment variable to openai-agents* to see verbose logs.

export DEBUG=openai-agents*

To log session persistence activity, set OPENAI_AGENTS__DEBUG_SAVE_SESSION=1.

You can obtain a namespaced logger for your own modules using getLogger(namespace) from @openai/agents.

Get logger

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

const logger = getLogger('my-app');
logger.debug('something happened');

Sensitive data in logs

Model and tool data, including related error objects and details, is not included in logs by default. If you need those details while debugging, you can explicitly enable sensitive data logging for the process:

Enable sensitive data logging

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

setSensitiveDataLoggingEnabled(true);

Only enable this in an environment where logs are handled securely. The programmatic setting controls both model and tool data and takes precedence over the environment variables below. Call setSensitiveDataLoggingEnabled(false) to disable sensitive data logging again.

You can also opt in to model and tool data independently with environment variables. Set the corresponding OPENAI_AGENTS_DONT_LOG_* variable to 0 or false:

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

Setting either variable to 1 or true keeps the corresponding data and related error details redacted. Unset or unrecognized values also use the secure default and keep sensitive data out of logs.