跳转到内容

快速开始

项目设置与凭据

Section titled “项目设置与凭据”

  1. 创建项目

    在本快速开始中，我们将创建一个可在浏览器中使用的语音智能体。如果您想快速搭建一个新项目，可以从 Next.js 或 Vite 开始。

    Terminal window
    npm create vite@latest my-project -- --template vanilla-ts

  2. 安装推荐包（需要 Zod v4）

    Terminal window
    npm install @openai/agents zod

  3. 生成客户端临时令牌

    由于该应用将在用户的浏览器中运行，我们需要一种安全的方式，通过 Realtime API 连接到模型。推荐流程与官方的 Realtime API with WebRTC 指南一致：由您的后端创建一个短期有效的临时客户端令牌，然后浏览器使用该令牌建立 WebRTC 连接。出于测试目的，您也可以使用 curl 和常规的 OpenAI API 密钥生成令牌。

    Terminal window
    export OPENAI_API_KEY="sk-proj-...(your own key here)"
    curl -X POST https://api.openai.com/v1/realtime/client_secrets \
       -H "Authorization: Bearer $OPENAI_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
         "session": {
           "type": "realtime",
           "model": "gpt-realtime"
         }
       }'

    响应中包含一个顶层 value 字段，其值以 ek_ 前缀开头，同时还包含实际生效的 session 对象。建立 WebRTC 连接时，请将 value 用作客户端密钥。该令牌的有效期较短，因此您的后端应在需要时生成新的令牌。如果您的浏览器会话需要带有 authorization 或自定义 headers 的远程 MCP 工具，请将这些远程 MCP 配置包含在发送到 POST /v1/realtime/client_secrets 的服务端 session 负载中，而不是将这些凭据暴露在浏览器代码里。

语音智能体的创建与连接

Section titled “语音智能体的创建与连接”

  1. 创建您的第一个 Agent

    创建新的 RealtimeAgent 与创建常规的 Agent 非常相似。

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

    const agent = new RealtimeAgent({
      name: 'Assistant',
      instructions: 'You are a helpful assistant.',
    });

  2. 创建会话

    与常规智能体不同，语音智能体会持续运行在 RealtimeSession 中，由它处理对话以及与模型的长期连接。这个会话还会管理音频处理、中断，以及您稍后将配置的更广泛的对话生命周期。

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

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

    RealtimeSession 构造函数的第一个参数接收一个 agent。这个智能体将是用户最先与之交互的智能体。

  3. 连接到会话

    要连接到会话，您需要传入之前生成的客户端临时令牌。

    await session.connect({ apiKey: 'ek_...(put your own key here)' });

    在浏览器中，这会通过 WebRTC 连接到 Realtime API，并自动为您配置麦克风采集和音频播放。在默认的 WebRTC 路径下，SDK 会在数据通道打开后立即发送初始会话配置，并尽量在 connect() 完成前等待对应的 session.updated 确认；如果该确认始终未到达，则会在超时后回退。如果您在诸如 Node.js 之类的服务器运行时中运行 RealtimeSession，SDK 会自动回退为使用 WebSocket；在 WebSocket 路径下，connect() 会在套接字打开且初始配置已发送后完成，因此 session.updated 可能会稍晚到达。您可以在传输机制指南中进一步了解传输方式的选择。

应用运行与测试

Section titled “应用运行与测试”

  1. 整合所有内容

    import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
    

    export async function setupCounter(element: HTMLButtonElement) {
      // ....
      // for quickly start, you can append the following code to the auto-generated TS code
    

      const agent = new RealtimeAgent({
        name: 'Assistant',
        instructions: 'You are a helpful assistant.',
      });
      const session = new RealtimeSession(agent);
      // Automatically connects your microphone and audio output in the browser via WebRTC.
      try {
        await session.connect({
          // To get this ephemeral key string, you can run the following command or implement the equivalent on the server side:
          // curl -s -X POST https://api.openai.com/v1/realtime/client_secrets -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"session": {"type": "realtime", "model": "gpt-realtime"}}' | jq .value
          apiKey: 'ek_...(put your own key here)',
        });
        console.log('You are connected!');
      } catch (e) {
        console.error(e);
      }
    }

  2. 启动应用并开始对话

    启动您的 Web 服务器并打开包含新 Realtime Agent 代码的页面。您应该会看到麦克风权限请求。授予访问权限后，您就可以开始与智能体对话了。

    Terminal window
    npm run dev

后续步骤

Section titled “后续步骤”

接下来，您可以开始设计并构建自己的语音智能体：