跳转到内容

快速开始

项目设置与凭据

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 连接到模型。推荐流程与官方的 通过 WebRTC 使用 Realtime API指南一致：后端创建一个短期有效的临时客户端令牌，然后浏览器使用该令牌建立 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-2.1"
         }
       }'

    响应包含一个以 ek_ 为前缀的顶层 value 字段，以及实际生效的 session 对象。建立 WebRTC 连接时，请使用 value 作为客户端密钥。此令牌有效期很短，因此后端应在需要时生成新令牌。如果浏览器会话需要带有 authorization 或自定义 headers 的托管 MCP 工具，请将相应的托管 MCP 配置包含在服务器端发送至 POST /v1/realtime/client_secrets 的 session 载荷中，而不要在浏览器代码中暴露这些凭据。

语音智能体的创建与连接

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

  1. 首个智能体的创建

    创建新的 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-2.1',
    });

    RealtimeSession 构造函数将 agent 作为第一个参数。该智能体将是用户首先交互的智能体。

  3. 会话连接

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

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

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

应用运行与测试

Section titled “应用运行与测试”

  1. 完整整合

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

    async function main() {
      const agent = new RealtimeAgent({
        name: 'Assistant',
        instructions: 'You are a helpful assistant.',
      });
      const session = new RealtimeSession(agent, {
        model: 'gpt-realtime-2.1',
      });
      // 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-2.1"}}' | jq .value
          apiKey: 'ek_...(put your own key here)',
        });
        console.log('You are connected!');
      } catch (e) {
        console.error(e);
      }
    }
    

    main().catch(console.error);

  2. 应用启动与对话

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

    Terminal window
    npm run dev

后续步骤

Section titled “后续步骤”

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