跳转到内容

SDK 配置

本页介绍通常在应用启动时一次性设置的 SDK 级默认设置,例如默认 OpenAI 客户端、传输机制、追踪导出密钥和调试日志行为。这些设置默认作用于整个进程,因此适合用于通用配置,而非针对单个智能体或单次运行的调整。

如果需要配置特定的 Agent、Runner 或 run() 调用,请参阅:

  • 运行智能体,了解 Runner 和单次运行的选项。
  • 模型,了解智能体级和 Runner 级的模型设置。
  • 追踪,了解针对单次运行的追踪配置和导出器行为。

默认情况下,SDK 仅在需要创建 OpenAI 客户端时才读取 OPENAI_API_KEY。如果无法设置环境变量,请手动调用 setDefaultOpenAIKey()。

设置默认 OpenAI 密钥
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

你也可以传入自己的 OpenAI 客户端实例。否则,SDK 会使用默认密钥自动创建一个实例。

设置默认 OpenAI 客户端
import { OpenAI } from 'openai';
import { setDefaultOpenAIClient } from '@openai/agents';
const customClient = new OpenAI({ baseURL: '...', apiKey: '...' });
setDefaultOpenAIClient(customClient);

最后,你可以在 Responses API 和 Chat Completions API 之间切换。

设置 OpenAI API
import { setOpenAIAPI } from '@openai/agents';
setOpenAIAPI('chat_completions');

如果使用 Responses API,你还可以选择 OpenAI 提供方的传输机制。默认使用 HTTP。

设置 Responses 传输机制
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() 设置单独的密钥:

设置追踪导出 API 密钥
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 会继续隐去对应的数据及相关错误详细信息。未设置变量或其值无法识别时,也会采用安全的默认设置,不将敏感数据写入日志。