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 提供方的传输机制。默认值为 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');

日志中的敏感数据

某些日志可能包含用户数据。请通过设置这些环境变量来禁用它们。

要禁用 LLM 输入和输出的日志记录：

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1

要禁用工具输入和输出的日志记录：

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1