跳转到内容

快速开始

  1. 创建项目

    在本快速开始中,我们将创建一个可在浏览器中使用的语音智能体。如果你想从一个新项目开始,可以尝试使用Next.jsVite

    Terminal window
    npm create vite@latest my-project -- --template vanilla-ts
  2. 安装 Agents SDK

    Terminal window
    npm install @openai/agents zod@3

    或者你也可以安装 @openai/agents-realtime,这是一个独立的浏览器包。

  3. 生成客户端临时令牌

    由于该应用将在用户的浏览器中运行,我们需要一种安全的方式通过 Realtime API 连接到模型。为此,我们可以使用在你的后端服务器上生成的临时客户端密钥。在测试时,你也可以使用 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_” 前缀开头。你可以稍后使用这个临时密钥建立 WebRTC 连接。注意该密钥仅在短时间内有效,需要重新生成。

  4. 创建你的第一个智能体

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

    import { RealtimeAgent } from '@openai/agents/realtime';
    const agent = new RealtimeAgent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
    });
  5. 创建会话

    与常规智能体不同,语音智能体会在一个 RealtimeSession 中持续运行并监听,该会话会随时间处理对话并与模型保持连接。该会话还会处理音频处理、打断,以及我们稍后将介绍的许多其他生命周期功能。

    import { RealtimeSession } from '@openai/agents/realtime';
    const session = new RealtimeSession(agent, {
    model: 'gpt-realtime',
    });

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

  6. 连接到会话

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

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

    这将在浏览器中使用 WebRTC 连接到 Realtime API,并自动配置你的麦克风和扬声器以进行音频输入和输出。如果你在后端服务器(如 Node.js)上运行 RealtimeSession,SDK 将自动使用 WebSocket 作为连接。你可以在传输机制指南中了解不同的传输层。

  7. 汇总

    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);
    }
    }
  8. 启动并开始对话

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

    Terminal window
    npm run dev

从这里开始,你可以设计并构建自己的语音智能体。语音智能体包含许多与常规智能体相同的功能,但也有其独特之处。