跳转到内容

构建语音智能体

一些传输层(例如默认的 OpenAIRealtimeWebRTC)会自动为您处理音频输入和输出。对于其他传输机制(例如 OpenAIRealtimeWebSocket),您必须自行处理会话音频:

import {
RealtimeAgent,
RealtimeSession,
TransportLayerAudio,
} from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'My agent' });
const session = new RealtimeSession(agent);
const newlyRecordedAudio = new ArrayBuffer(0);
session.on('audio', (event: TransportLayerAudio) => {
// play your audio
});
// send new audio to the agent
session.sendAudio(newlyRecordedAudio);

当底层传输支持时,session.muted 会报告当前的静音状态,session.mute(true | false) 则用于切换麦克风采集状态。OpenAIRealtimeWebSocket 未实现静音功能:session.muted 返回 null,而 session.mute() 会抛出异常。因此,在 WebSocket 配置中,您应自行暂停采集,并停止调用 sendAudio(),直到需要重新启用麦克风。

创建 RealtimeSession 时配置会话本身,通常通过 model 选项和 config 对象进行配置。connect(...) 用于处理连接时的事项,例如凭据、端点 URL,以及附加到现有 Realtime 通话,而非设置任意会话字段。

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Greeter',
instructions: 'Greet the user with cheer and answer questions.',
});
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
config: {
outputModalities: ['audio'],
reasoning: {
effort: 'low',
},
parallelToolCalls: true,
audio: {
input: {
format: 'pcm16',
transcription: {
model: 'gpt-live-transcribe',
delay: 'low',
prompt:
'A software support conversation about the OpenAI Agents SDK.',
keywords: ['OpenAI Agents SDK', 'RealtimeSession'],
languages: ['en', 'ja'],
},
},
output: {
format: 'pcm16',
},
},
},
});

在底层,SDK 会将此配置规范化为 Realtime session.update 格式。如果您需要使用某个原始会话字段,但 RealtimeSessionConfig 中没有对应属性,请使用 providerData,或通过 session.transport.sendEvent(...) 发送原始 session.update。

优先使用包含 outputModalities、audio.input 和 audio.output 的新版 SDK 配置结构。旧版 SDK 别名(例如 modalities、inputAudioFormat、outputAudioFormat、inputAudioTranscription 和 turnDetection)仍会经过规范化处理,以保持向后兼容,但新代码应使用此处展示的嵌套 audio 结构。

对于 gpt-realtime-2.1 等支持推理的 Realtime 模型,请在会话配置中设置 reasoning.effort。更高的推理强度可能会增加延迟和 token 用量。如果希望控制模型是否可以并行调用多个工具,还可以设置 parallelToolCalls。

对于输入转录,audio.input.transcription 支持正式发布的转录模型及其上下文选项。使用 gpt-live-transcribe 可实现低延迟的流式转录;其 delay 设置可在更快的部分转录结果与最终转录质量之间进行权衡。gpt-live-transcribe 和 gpt-transcribe 都支持自由形式的 prompt、按字面匹配的 keywords,以及 languages 数组。这些模型使用 languages;接受单个语言提示的旧版转录模型仍使用单数形式的 language 字段。有关各模型的具体工作流,请参阅官方的转录上下文指导和 Realtime 转录指南。

对于语音到语音会话,通常选择 outputModalities: ['audio'],这样既能获得音频输出,也能获得转录文本。仅在需要纯文本响应时,才切换为 ['text']。

对于 RealtimeSessionConfig 中尚无对应参数的新参数,可以使用 providerData。传入 providerData 的所有内容都会作为原始 session 对象的一部分转发。

可在构造时设置的其他 RealtimeSession 选项:

选项类型用途
contextTContext合并到会话上下文中的额外本地上下文。
historyStoreAudioboolean在本地历史记录快照中存储音频数据(默认禁用)。
outputGuardrailsRealtimeOutputGuardrail[]会话的输出护栏(请参阅护栏)。
outputGuardrailSettings{ debounceTextLength?: number }护栏运行频率。默认为 100;使用 -1 可仅在完整文本可用时运行。
tracingDisabledboolean禁用会话追踪。
groupIdstring对跨会话或后端运行的追踪进行分组。需要设置 workflowName。
traceMetadataRecord<string, any>附加到会话追踪的自定义元数据。需要设置 workflowName。
workflowNamestring追踪工作流的易读名称。
automaticallyTriggerResponseForMcpToolCallsbooleanMCP 工具调用完成时,自动触发模型响应(默认值:true)。
toolErrorFormatterToolErrorFormatter自定义返回给模型的工具审批拒绝消息。
toolExecutionRealtimeToolExecutionConfig本地实时函数工具的 SDK 端执行设置。设置 preApprovalInputGuardrails: true 可在发出待审批请求前运行输入护栏。

connect(...) 选项:

选项类型用途
apiKeystring | (() => string | Promise<string>)此连接使用的 API 密钥(或其延迟加载函数)。
modelOpenAIRealtimeModels | string存在于传输层选项类型中。对于 RealtimeSession,请在构造函数中设置模型;直接使用底层传输时,也可以在连接时指定模型。
urlstring可选的自定义 Realtime 端点 URL。
callIdstring将 WebSocket 传输作为旁路连接附加到现有 Realtime 通话,包括通过 WebRTC 或 SIP 建立的通话。

RealtimeSession 构建于一个长期保持的 Realtime 连接之上。它维护对话历史记录的本地副本、监听传输事件、运行工具和输出护栏,并将当前智能体配置与传输层保持同步。

底层 API 的行为仍然很重要:

  • 成功建立连接后,首先会收到 session.created 事件,后续配置更改则会产生 session.updated。
  • 大多数会话属性可以随时间更改,但 model 不能在对话中途更改,voice 只能在会话尚未产生音频输出时更改,而且应提前决定追踪设置,因为 Realtime API 不允许在启用追踪后对其进行修改。
  • Realtime API 目前将单次会话限制为 60 分钟。
  • 输入音频转录是异步的,因此最新一句话的转录文本可能在响应生成已经开始后才到达。

在 SDK 层,await session.connect() 表示”传输已就绪,可以开始对话”,但具体的就绪时机因传输方式而异:

  • 在默认的浏览器 WebRTC 传输中,SDK 会在数据通道打开后立即发送初始 session.update,并尝试等待对应的 session.updated 事件,再让 connect() 完成。WebRTC 传输等待这一确认,是为了避免音频在您的 instructions、tools 和模态设置生效前到达服务器。如果始终未收到该确认,connect() 会在短暂超时后完成,作为回退处理。
  • 在默认的服务器端 WebSocket 传输中,套接字打开且初始配置发送完毕后,connect() 就会完成。因此,对应的 session.updated 事件可能在 connect() 已完成后才到达。

如果需要了解原始事件模型,请结合本页阅读官方的 Realtime 对话指南。

默认情况下,Realtime 会话使用内置的语音活动检测(VAD),让 API 能够判断用户何时开始或停止说话,以及何时创建响应。SDK 通过 audio.input.turnDetection 提供此功能。

import { RealtimeSession } from '@openai/agents/realtime';
import { agent } from './agent';
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
config: {
audio: {
input: {
turnDetection: {
type: 'semantic_vad',
eagerness: 'medium',
createResponse: true,
interruptResponse: true,
},
},
},
},
});

两种常见模式如下:

  • semantic_vad,旨在提供更自然的轮次边界,当用户听起来尚未说完时,可以多等待一会儿。
  • server_vad,更依赖阈值,并提供 threshold、prefixPaddingMs、silenceDurationMs 和 idleTimeoutMs 等设置。

如果希望自行管理轮次边界,请将 audio.input.turnDetection 设为 null。官方的语音活动检测指南和 Realtime 对话指南更详细地介绍了底层行为。

启用 VAD 后,在智能体说话时开口可以打断当前响应。在 WebSocket 传输中,SDK 会监听 input_audio_buffer.speech_started,将助手音频截断到用户实际听到的位置,并发出 audio_interrupted 事件。在使用 WebSocket 并自行管理播放时,该事件尤其有用。

import { session } from './agent';
session.on('audio_interrupted', () => {
// handle local playback interruption
});

如果希望提供手动停止按钮,请自行调用 interrupt():

import { session } from './agent';
session.interrupt();
// This still triggers `audio_interrupted` so your UI can stop playback

WebRTC 和 WebSocket 都会停止正在进行的响应,但底层机制因传输方式而异。WebRTC 会为您清除缓冲的输出音频。在 WebSocket 配置中,您仍需要自行停止本地播放,而本地历史记录会在传输层返回相应的截断事件和对话事件时更新。

如果希望将键入的输入或额外的结构化用户内容发送到实时对话中,请使用 sendMessage()。

import { RealtimeSession, RealtimeAgent } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Assistant',
});
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
});
session.sendMessage('Hello, how are you?');

这适用于混合文本与语音的用户界面、带外上下文注入,或为语音输入配上明确的文字说明。

Realtime 语音到语音会话也可以包含图像。在 SDK 中,使用 addImage() 将图像附加到当前对话。

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Assistant',
});
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
});
const imageDataUrl = 'data:image/png;base64,...';
session.addImage(imageDataUrl, { triggerResponse: false });
session.sendMessage('Describe what is in this image.');

传入 triggerResponse: false 后,您可以先将图像与后续的文本或音频轮次合并,再请求模型响应。这与官方的 Realtime 对话图像输入指导一致。

在 SDK 的较高层级,sendMessage() 和 addImage() 默认会为您触发响应。当您使用原始传输事件、按键说话流程或自定义审核/验证步骤时,手动响应控制就很重要。

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Greeter',
instructions: 'Greet the user with cheer and answer questions.',
});
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
});
session.transport.on('*', (event) => {
// Event received from the underlying Realtime transport
});
// Send any valid client event, for example, to trigger a new response
session.transport.sendEvent({
type: 'response.create',
// ...
});

常见情况有两种:

  1. 如果通过 audio.input.turnDetection = null 完全禁用 VAD,您需要负责提交音频轮次,然后发送 response.create。
  2. 如果保持 VAD 启用,但设置 turnDetection.interruptResponse = false 和 turnDetection.createResponse = false,API 仍会检测轮次,但由您决定何时创建响应。

如果希望在模型响应之前检查或审核用户输入,可以保持 VAD 启用,同时将 turnDetection.interruptResponse 和 turnDetection.createResponse 都设为 false。此配置与官方 Realtime 对话中关于禁用自动响应的指导一致。

与常规智能体类似,您可以使用交接将智能体拆分为多个智能体,并在它们之间进行编排,以提升性能并更清晰地界定问题范围。

import { RealtimeAgent } from '@openai/agents/realtime';
const mathTutorAgent = new RealtimeAgent({
name: 'Math Tutor',
handoffDescription: 'Specialist agent for math questions',
instructions:
'You provide help with math problems. Explain your reasoning at each step and include examples',
});
const agent = new RealtimeAgent({
name: 'Greeter',
instructions: 'Greet the user with cheer and answer questions.',
handoffs: [mathTutorAgent],
});

与常规智能体相比,语音智能体的交接行为略有不同。执行交接时,会使用新的智能体配置就地更新当前会话。因此,新智能体会自动获得当前对话历史记录的访问权限,且目前不会应用输入过滤器。

由于会话始终保持连接,该会话的模型不会在交接过程中更改。声音更改遵循底层 Realtime API 的规则:只有在会话尚未产生音频输出时才能更改。Realtime 交接主要用于在同一会话中切换不同的 RealtimeAgent 配置;如果需要使用不同的模型(例如 gpt-5.4 这样的推理模型),或委派给非实时的后端智能体,请使用通过工具委派。

与常规智能体一样,语音智能体可以调用工具来执行操作。Realtime 支持函数工具(在本地执行)和托管 MCP 工具(由 Realtime API 远程执行)。您可以使用与常规智能体相同的 tool() 辅助函数来定义函数工具。

仅适用于 Responses 的工具选项不适用于语音智能体。函数工具的 outputSchema 以及包含 'programmatic' 的 allowedCallers 值都会被拒绝,托管 MCP 工具上的程序化调用方也同样会被拒绝。请在 Realtime 会话中使用可直接调用的函数工具或托管 MCP 工具,或将需要程序化工具调用的工作委派给 Responses 智能体。

import { tool, RealtimeAgent } from '@openai/agents/realtime';
import { z } from 'zod';
const getWeather = tool({
name: 'get_weather',
description: 'Return the weather for a city.',
parameters: z.object({ city: z.string() }),
async execute({ city }) {
return `The weather in ${city} is sunny.`;
},
});
const weatherAgent = new RealtimeAgent({
name: 'Weather assistant',
instructions: 'Answer weather questions.',
tools: [getWeather],
});

函数工具在与 RealtimeSession 相同的环境中运行。这意味着,如果会话在浏览器中运行,工具也会在浏览器中执行。如果需要执行敏感操作,请在工具内部调用后端,让服务器执行需要特权的工作。

这样,浏览器端工具就可以作为通往服务器端逻辑的轻量级后向通道。例如,examples/realtime-next 代码示例在浏览器中定义了一个 refundBackchannel 工具,将请求和当前对话历史记录转发给服务器上的 handleRefundRequest(...)。在服务器上,单独的 Runner 可以使用不同的智能体或模型评估退款请求,再将结果返回给语音会话。

托管 MCP 工具可以通过 hostedMcpTool 配置,并在远程执行。当 MCP 工具的可用性发生变化时,会话会发出 mcp_tools_changed。要防止会话在 MCP 工具调用完成后自动触发模型响应,请设置 automaticallyTriggerResponseForMcpToolCalls: false。

当前经过筛选的 MCP 工具列表也可以通过 session.availableMcpTools 获取。该属性和 mcp_tools_changed 事件都只反映当前智能体上启用的托管 MCP 服务器,并已应用智能体配置中的所有 allowed_tools 过滤条件。

将安全的服务器选择、请求头和审批视为连接前配置,会更容易理解托管 MCP 的设置过程。在 RealtimeSession.connect() 打开传输连接之前,SDK 会解析当前智能体的托管 MCP 工具定义,并将受支持的 MCP 字段包含在发送给 Realtime API 的初始会话配置中。

在浏览器 WebRTC 应用中,在 connect() 之前提供安全的托管 MCP 配置尤为重要。临时客户端机密信息始终在服务器上生成,因此,任何必须保密的托管 MCP 凭据或自定义 headers 都应在服务器端的 POST /v1/realtime/client_secrets 请求中,作为初始 session 载荷的一部分附加。不要将长期有效的凭据放在浏览器代码中,并打算在 connect() 启动后再添加它们。

在 Realtime API 层面,后续的 session.update 调用仍然可以更改工具和其他可变的会话字段,而且 SDK 本身也会在当前智能体发生变化时发送 session.update。不过,在浏览器应用中,您应将安全的托管 MCP 初始化视为服务器端、连接前的工作,并使浏览器端的 RealtimeSession 配置与服务器生成临时凭据时使用的配置保持一致。

工具执行期间,智能体无法处理用户的新请求。改善体验的一种方式是,要求智能体在即将执行工具时提前告知用户,或说一些特定的话,为工具执行争取时间。

如果希望函数工具完成后不立即触发另一次模型响应,请返回 @openai/agents/realtime 中的 backgroundResult(output)。这会将工具输出发回会话,同时由您控制何时触发响应。

函数工具的超时选项(timeoutMs、timeoutBehavior、timeoutErrorFunction)在 Realtime 会话中的工作方式相同。使用默认的 error_as_result 时,超时消息会作为工具输出发送。使用 raise_exception 时,会话会发出包含 ToolTimeoutError 的 error 事件,且不会为该次调用发送工具输出。

除了智能体调用特定工具时传入的参数,您还可以访问 Realtime 会话跟踪的当前对话历史记录快照。如果需要根据当前对话状态执行更复杂的操作,或计划使用工具进行委派,这会很有用。

import {
tool,
RealtimeContextData,
RealtimeItem,
} from '@openai/agents/realtime';
import { z } from 'zod';
const parameters = z.object({
request: z.string(),
});
const refundTool = tool<typeof parameters, RealtimeContextData>({
name: 'Refund Expert',
description: 'Evaluate a refund',
parameters,
execute: async ({ request }, details) => {
// The history might not be available
const history: RealtimeItem[] = details?.context?.history ?? [];
// Call your backend to process the refund request
},
});

如果定义工具时设置了 needsApproval: true,智能体会在执行工具之前发出 tool_approval_requested 事件。

通过监听此事件,您可以向用户显示界面,以批准或拒绝工具调用。

使用 await session.approve(request.approvalItem) 或 await session.reject(request.approvalItem) 处理请求。对于函数工具,您可以传入 { alwaysApprove: true } 或 { alwaysReject: true },在会话余下时间内对重复调用沿用相同决定,也可以使用 session.reject(request.approvalItem, { message: '...' }),为该次调用向模型发回自定义拒绝消息。托管 MCP 审批不支持持续生效的批准/拒绝决定;请改用托管 MCP 的 allowedTools 配置限制这些工具。

如果没有为单次调用传入拒绝 message,会话会回退到 toolErrorFormatter(如已配置),然后再回退到 SDK 的默认拒绝文本。

默认情况下,函数工具的输入护栏在审批通过后、工具即将执行前运行。如果向 new RealtimeSession(...) 传入 toolExecution: { preApprovalInputGuardrails: true },本地函数工具的输入护栏还会在会话发出 tool_approval_requested 之前运行。护栏拒绝调用时,会将拒绝消息作为工具输出发回,并跳过审批事件。如果护栏允许调用,仍会发出审批事件,且在 session.approve(...) 之后、执行之前,护栏会再次运行。

import { session } from './agent';
session.on('tool_approval_requested', (_context, _agent, request) => {
// Show a UI to let the user approve or reject the tool call
// Then resolve the request with `session.approve(...)` or `session.reject(...)`
session.approve(request.approvalItem);
});

护栏可以监控智能体说出的内容是否违反一组规则,并立即切断响应。这些检查针对智能体响应的输出流运行。在纯文本会话中,SDK 会评估输出文本增量。在音频会话中,它会使用输出音频的转录文本及其增量,因此关键前提是转录文本可用,而不是存在单独的文本输出模态。

您提供的护栏会在模型返回响应时异步运行,让您能够根据预定义的分类触发条件(例如”提及特定禁用词”)切断响应。

护栏触发时,会话会发出 guardrail_tripped 事件。该事件还提供一个 details 对象,其中包含触发护栏的 itemId。

import {
RealtimeOutputGuardrail,
RealtimeAgent,
RealtimeSession,
} from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Greeter',
instructions: 'Greet the user with cheer and answer questions.',
});
const guardrails: RealtimeOutputGuardrail[] = [
{
name: 'No mention of Dom',
async execute({ agentOutput }) {
const domInOutput = agentOutput.includes('Dom');
return {
tripwireTriggered: domInOutput,
outputInfo: { domInOutput },
};
},
},
];
const guardedSession = new RealtimeSession(agent, {
outputGuardrails: guardrails,
});

默认情况下,护栏每隔 100 个字符运行一次,并在最终转录文本可用时再次运行。由于说出文本通常比生成转录文本耗时更长,护栏往往能够在用户听到不安全输出之前将其切断。

如果希望修改此行为,可以向会话传入 outputGuardrailSettings 对象。

如果只希望在响应结束时对完整生成的转录文本评估一次,请设置 debounceTextLength: -1。

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Greeter',
instructions: 'Greet the user with cheer and answer questions.',
});
const guardedSession = new RealtimeSession(agent, {
outputGuardrails: [
/*...*/
],
outputGuardrailSettings: {
debounceTextLength: 500, // run guardrail every 500 characters or set it to -1 to run it only at the end
},
});

RealtimeSession 会自动维护本地 history 快照,跟踪用户消息、助手输出、工具调用和截断状态。您可以在界面中呈现它、在工具内部检查它,或在需要修正或删除条目时更新它。

对话发生变化时,会话会发出 history_updated。如果需要请求更改历史记录,请使用 updateHistory()。它会请求传输层对比当前历史记录,并发送必要的删除/创建事件;当相应的对话事件返回时,本地 session.history 视图会随之更新。

import { RealtimeSession, RealtimeAgent } from '@openai/agents/realtime';
const agent = new RealtimeAgent({
name: 'Assistant',
});
const session = new RealtimeSession(agent, {
model: 'gpt-realtime-2.1',
});
await session.connect({ apiKey: '<client-api-key>' });
// listening to the history_updated event
session.on('history_updated', (history) => {
// returns the full history of the session
console.log(history);
});
// Option 1: explicit setting
session.updateHistory([
/* specific history */
]);
// Option 2: override based on current state like removing all agent messages
session.updateHistory((currentHistory) => {
return currentHistory.filter(
(item) => !(item.type === 'message' && item.role === 'assistant'),
);
});
  1. 目前无法在事后编辑函数工具调用。
  2. 历史记录中的助手文本依赖于可用的转录文本,包括 output_audio.transcript。
  3. 因打断而被截断的响应不会保留最终转录文本。
  4. 输入音频转录最好仅作为用户所说内容的粗略参考,而不是模型对音频理解的精确副本。

通过工具委派

通过将对话历史记录与工具调用相结合,您可以将对话委派给另一个后端智能体,以执行更复杂的操作,然后将其结果返回给用户。

import {
RealtimeAgent,
RealtimeContextData,
tool,
} from '@openai/agents/realtime';
import { handleRefundRequest } from './serverAgent';
import z from 'zod';
const refundSupervisorParameters = z.object({
request: z.string(),
});
const refundSupervisor = tool<
typeof refundSupervisorParameters,
RealtimeContextData
>({
name: 'escalateToRefundSupervisor',
description: 'Escalate a refund request to the refund supervisor',
parameters: refundSupervisorParameters,
execute: async ({ request }, details) => {
// This will execute on the server
return handleRefundRequest(request, details?.context?.history ?? []);
},
});
const agent = new RealtimeAgent({
name: 'Customer Support',
instructions:
'You are a customer support agent. If you receive any requests for refunds, you need to delegate to your supervisor.',
tools: [refundSupervisor],
});

随后,以下代码在服务器上运行,本例中通过 Next.js Server Action 执行。

// This runs on the server
import 'server-only';
import { Agent, run } from '@openai/agents';
import type { RealtimeItem } from '@openai/agents/realtime';
import z from 'zod';
const agent = new Agent({
name: 'Refund Expert',
instructions:
'You are a refund expert. You are given a request to process a refund and you need to determine if the request is valid.',
model: 'gpt-5.4',
outputType: z.object({
reason: z.string(),
refundApproved: z.boolean(),
}),
});
export async function handleRefundRequest(
request: string,
history: RealtimeItem[],
) {
const input = `
The user has requested a refund.
The request is: ${request}
Current conversation history:
${JSON.stringify(history, null, 2)}
`.trim();
const result = await run(agent, input);
return JSON.stringify(result.finalOutput, null, 2);
}