SDK 配置

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

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

运行智能体了解 Runner 和按次运行选项。
模型了解智能体级和 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 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 密钥。

也可以通过 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