SDK 配置
本页介绍通常在应用启动时一次性设置的 SDK 级默认设置,例如默认 OpenAI 客户端、传输机制、追踪导出密钥和调试日志行为。这些设置默认作用于整个进程,因此适合用于通用配置,而非针对单个智能体或单次运行的调整。
如果需要配置特定的 Agent、Runner 或 run() 调用,请参阅:
OpenAI 客户端与传输机制
Section titled “OpenAI 客户端与传输机制”API 密钥与客户端
Section titled “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 选择
Section titled “API 选择”最后,你可以在 Responses API 和 Chat Completions API 之间切换。
import { setOpenAIAPI } from '@openai/agents';
setOpenAIAPI('chat_completions');Responses 传输机制
Section titled “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,请改为在其中配置传输机制。请参阅模型。
可观测性与调试
Section titled “可观测性与调试”在受支持的服务器运行时中,追踪默认启用。在浏览器中以及 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');日志中的敏感数据
Section titled “日志中的敏感数据”默认情况下,日志不包含模型和工具数据,包括相关错误对象和详细信息。如果调试时需要这些详细信息,可以为当前进程显式启用敏感数据日志记录:
import { setSensitiveDataLoggingEnabled } from '@openai/agents';
setSensitiveDataLoggingEnabled(true);仅在能够安全处理日志的环境中启用此功能。通过代码进行的设置同时控制模型和工具数据,并且优先于下方的环境变量。调用 setSensitiveDataLoggingEnabled(false) 可再次禁用敏感数据日志记录。
你也可以通过环境变量分别启用模型和工具数据的日志记录。将对应的 OPENAI_AGENTS_DONT_LOG_* 变量设置为 0 或 false:
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0将任一变量设置为 1 或 true 会继续隐去对应的数据及相关错误详细信息。未设置变量或其值无法识别时,也会采用安全的默认设置,不将敏感数据写入日志。