SDK 配置

OpenAI 客户端与传输

API 密钥与客户端

默认情况下，SDK 在首次导入时会读取环境变量 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');

使用 setOpenAIResponsesTransport('websocket') 启用 WebSocket 传输，使用 setOpenAIResponsesTransport('http') 切回。若通过代理或网关路由 websocket 流量，请设置 OPENAI_WEBSOCKET_BASE_URL（或在 OpenAIProvider 上配置 websocketBaseURL）。

可观测性与调试

追踪

追踪默认启用，并使用上文中的 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