SDK 配置

本页介绍通常在应用启动时一次性设置的SDK 全局默认项，例如默认 OpenAI 客户端、传输方式、追踪导出 key 以及调试日志行为。这些设置默认在整个进程范围内生效，因此这里适合做通用配置，而不是针对单个智能体或单次运行做调优。

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

运行智能体：了解 Runner 和按运行配置选项。
模型：了解智能体级别和 runner 级别的模型设置。
追踪：了解特定运行的追踪配置和导出器行为。

OpenAI 客户端与传输

API key 与客户端

默认情况下，SDK 会在需要创建 OpenAI 客户端时再延迟解析 OPENAI_API_KEY。如果无法设置环境变量，请手动调用 setDefaultOpenAIKey()。

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

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

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

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 provider 传输方式。默认是 HTTP。

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

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

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

这个进程级默认值只会影响后续通过默认 OpenAI provider 解析的模型。如果你传入的是具体的 Model 实例或自定义 modelProvider，请改为在对应位置配置传输。参见模型指南。

可观测性与调试

追踪

在受支持的服务器运行时中，追踪默认开启。在浏览器中以及 NODE_ENV=test 时，默认关闭。

默认情况下，追踪导出会使用上文中的同一个 OpenAI key。

你也可以通过 setTracingExportApiKey() 设置单独的 key：

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)，为自己的模块获取带命名空间的 logger。

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