用 OpenAI Realtime API 做一个能开口对话的语音智能体

本教程用浏览器 + WebRTC 跑语音（最省事）。新建项目并安装推荐的包（需要 Zod v4）：

# 用 Vite 起个空项目（或直接进你现有前端项目）
npm create vite@latest my-voice-agent -- --template vanilla-ts
cd my-voice-agent

# 安装 Agents SDK 与 Zod
npm install @openai/agents zod

在你的后端（Node/Python 都行）加一个接口，用真实 Key 换一个短命临时密钥：

// 后端示例（Node）
export async function mintEphemeralKey() {
  const res = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      session: { type: "realtime", model: "gpt-realtime-2" },
    }),
  });
  const data = await res.json();
  return data.value; // 以 ek_ 开头，约 1 分钟有效
}

在前端用 RealtimeAgent 定义人设，和定义普通 Agent 很像，只是它输出的是语音：

import { RealtimeAgent } from "@openai/agents/realtime";

const agent = new RealtimeAgent({
  name: "语音小助手",
  instructions: "你是一个简洁友好的中文语音助手，回答要短、口语化，一次不超过三句话。",
  // voice 可选：alloy / echo / shimmer 等
});

用 RealtimeSession 通过 WebRTC 连接（自动处理麦克风采集和扬声器播放），传入 Step 2 的临时密钥：

import { RealtimeSession } from "@openai/agents/realtime";

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2",
});

// 用后端换来的临时密钥连接
await session.connect({ apiKey: ephemeralKey });

// 连上后，直接对麦克风说话即可；
// 想用代码触发首句，也可以：
// session.sendMessage("你好，介绍一下你自己");

纯聊天不够，给它挂个工具（比如查订单），对话中它就能自动调用：

const lookupOrder = {
  name: "lookup_order",
  description: "根据用户说的订单号查询状态",
  parameters: { type: "object", properties: { orderId: { type: "string" } } },
  async execute({ orderId }) {
    // 这里调你自己的后端 / 数据库
    return { orderId, status: "已发货", eta: "今天 18:00 前" };
  },
};

const agent = new RealtimeAgent({
  name: "语音小助手",
  instructions: "你是客服助手，需要查订单时调用 lookup_order 工具。",
  tools: [lookupOrder],
});

真人对话会打断。Realtime 原生支持：用户一开口，AI 正在说的语音会自动停止（通过 response.cancel）。WebSocket 模式下你要自己暂停采集；WebRTC 基本自动处理。关键是开启语义级语音活动检测（semantic VAD）让打断更自然：

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2",
  config: {
    audio: {
      input: { turnDetection: { type: "semantic_vad" } },
      output: { modality: "audio" },
    },
  },
});

想接到电话？用 Twilio 媒体流桥接（8kHz μ-law 需重采样到 24kHz PCM16）。上线前加固清单：

加固清单：
✅ 临时密钥只在后端签发，前端绝不出现标准 Key
✅ 写操作工具开启用户审批（approve_tool_call）
✅ 设置推理强度 reasoning.effort，平衡延迟与质量
✅ 监控 Token 用量，设预算上限
✅ 异常处理：断线自动重连 + 静音检测