SDK 配置

本页介绍通常在应用启动时一次性设置的整个 SDK 范围内的默认值，例如默认 OpenAI 客户端、传输机制、追踪导出密钥和调试日志行为。默认情况下，这些设置会在整个进程范围内生效，因此这里适合进行全局配置，而不是针对每个智能体或每次运行进行调优。

如果需要改为配置特定的 Agent、Runner 或 run() 调用，请参阅：

运行智能体，了解 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');

使用 setOpenAIResponsesTransport('websocket') 可启用 WebSocket 传输，使用 setOpenAIResponsesTransport('http') 可切换回 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');

日志中的敏感数据

默认情况下，日志中不包含模型和工具数据，包括相关错误对象及其详细信息。如果调试时需要这些详细信息，可以为当前进程明确启用敏感数据日志记录：

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

setSensitiveDataLoggingEnabled(true);

请仅在能够安全处理日志的环境中启用此功能。该编程式设置同时控制模型和工具数据，并且优先于下方的环境变量。调用 setSensitiveDataLoggingEnabled(false) 可再次禁用敏感数据日志记录。

您也可以通过环境变量分别选择启用模型数据和工具数据的日志记录。将相应的 OPENAI_AGENTS_DONT_LOG_* 变量设置为 0 或 false：

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

将任一变量设置为 1 或 true，会继续遮蔽对应数据及相关错误详细信息。未设置或无法识别的值也会使用安全默认值，不在日志中记录敏感数据。