Web-Apps erstellen

Dies ist der praktische Leitfaden, um einen Echtzeit-Agenten in einem Browser zu platzieren: das Server-Side-Bridge-Muster, das WebSocket-Protokoll und der Web Audio-Code, der das Mikrofon aufnimmt und den Agenten lückenlos abspielt. Jedes Web-Beispiel in diesem Abschnitt ist genau auf diese Weise aufgebaut; der customer_service Server ist die Referenzimplementierung.

Warum eine Server-Side-Bridge

Ein Browser kann den Echtzeit-WebSocket des Anbieters nicht direkt halten:

• Ihre OPENAI_API_KEY / GEMINI_API_KEY würden an jeden Client versendet,
• Tools würden im Browser ausgeführt, fern von Ihren Daten und Anmeldeinformationen,
• Sie wären im Client-Code an das Wire-Format eines Anbieters gebunden.

Der Browser ist also ein dünnes Audio-/Videogerät und Ihr Rust-Server besitzt die Session:

  browser ──mic PCM16 + camera JPEG (base64 over your WS)──▶  Axum /ws
  browser ◀──agent PCM16 + transcripts + tool events───────   IntegratedRealtimeRunner ──▶ provider

Der Schlüssel bleibt auf dem Server, Tools laufen auf dem Server, und Sie können den Provider pro Verbindung (/ws?provider=openai|gemini) wechseln, ohne den Client zu berühren.

Das WebSocket-Protokoll

Ein kleines JSON-Protokoll läuft über Ihr eigenes WebSocket. Browser → Server:

Server → Browser:

Dies ist ein dünnes, app-definiertes Mapping über ServerEvent — siehe server_event_to_client_json unten.

Server: die Axum-Brücke

Der Handler erstellt ein IntegratedRealtimeRunner, verbindet sich, sendet ready, dann führt er zwei gleichzeitige Schleifen aus — Outbound (Echtzeit-Ereignisse → Browser) und Inbound (Browser → Session) — verbunden mit tokio::select!.

async fn handle_ws(socket: WebSocket, provider: Provider) {
    let session_id = uuid::Uuid::new_v4().to_string();
    let (mut sender, mut receiver) = socket.split();

    let runner = Arc::new(build_runner(provider, &session_id).await.unwrap());
    runner.connect().await.unwrap();

    // Negotiate audio rates to the browser BEFORE any audio flows.
    let (input_rate, output_rate) = provider.audio_rates();
    sender.send(Message::Text(json!({
        "type": "ready", "provider": provider.name(),
        "input_rate": input_rate, "output_rate": output_rate,
    }).to_string().into())).await.ok();

    // Outbound: realtime events → browser.
    let out_runner = runner.clone();
    let outbound = async move {
        while let Some(event) = out_runner.next_event().await {
            if let Ok(ev) = event {
                if let Some(payload) = server_event_to_client_json(ev) {
                    if sender.send(Message::Text(payload.to_string().into())).await.is_err() { break; }
                }
            }
        }
    };

    // Inbound: browser mic/camera/text → session.
    let in_runner = runner.clone();
    let inbound = async move {
        while let Some(Ok(Message::Text(text))) = receiver.next().await {
            match serde_json::from_str::<ClientMsg>(&text) {
                Ok(ClientMsg::InputAudio { audio }) => { in_runner.send_audio(&audio).await.ok(); }
                Ok(ClientMsg::VideoFrame { mime, data }) => { in_runner.send_video_frame(&mime, &data).await.ok(); }
                Ok(ClientMsg::Text { text }) => {
                    if in_runner.send_text(&text).await.is_ok() { in_runner.create_response().await.ok(); }
                }
                Ok(ClientMsg::Hangup) => break,
                _ => {}
            }
        }
    };

    tokio::select! { _ = outbound => {}, _ = inbound => {} }
    runner.close().await.ok();
}

Beachten Sie die beiden Eingabe-Asymmetrien, die Sie richtig handhaben müssen:

• Text benötigt create_response() — es gibt kein VAD, um eine Antwort auszulösen (siehe Architecture: turn lifecycle). Audio unter Server-VAD tut dies nicht.
• Videofehler sind nicht fatal — protokollieren und fortfahren; ein verlorener Frame sollte den Anruf nicht beenden.

Server-Ereignisse zuordnen

Die ausgehende Schleife wandelt jedes provider-unabhängige ServerEvent in das oben genannte kompakte Client-JSON um, und gibt None für Ereignisse zurück, die die Benutzeroberfläche ignoriert:

fn server_event_to_client_json(event: ServerEvent) -> Option<serde_json::Value> {
    match event {
        ServerEvent::AudioDelta { delta, .. } =>
            Some(json!({ "type": "audio", "audio": BASE64.encode(&delta) })),
        ServerEvent::TranscriptDelta { delta, .. } =>
            Some(json!({ "type": "agent_transcript", "delta": delta })),
        ServerEvent::InputTranscriptDelta { delta, .. } =>
            Some(json!({ "type": "user_transcript_delta", "delta": delta })),
        ServerEvent::SpeechStarted { .. } => Some(json!({ "type": "user_speaking" })),
        ServerEvent::FunctionCallDone { name, arguments, .. } =>
            Some(json!({ "type": "tool", "name": name, "args": arguments })),
        ServerEvent::ResponseDone { .. } => Some(json!({ "type": "response_done" })),
        ServerEvent::Error { error, .. } => Some(json!({ "type": "error", "message": error.message })),
        _ => None,   // ServerEvent is #[non_exhaustive]
    }
}

Browser: Mikrofon als PCM16 erfassen

Der Anbieter möchte rohes PCM16 Mono mit der ausgehandelten input_rate. Erfassen Sie mit einem AudioContext mit dieser Rate, wandeln Sie die Float-Samples auf 16-Bit herunter, base64-kodieren Sie sie und senden Sie sie:

let inputRate, outputRate;
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'ready') { inputRate = msg.input_rate; outputRate = msg.output_rate; startMic(); }
  // …handle audio / transcripts / tool / etc.
};

async function startMic() {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const ctx = new AudioContext({ sampleRate: inputRate });
  const src = ctx.createMediaStreamSource(stream);
  const node = ctx.createScriptProcessor(4096, 1, 1);  // or an AudioWorklet
  node.onaudioprocess = (ev) => {
    const f32 = ev.inputBuffer.getChannelData(0);
    const pcm16 = new Int16Array(f32.length);
    for (let i = 0; i < f32.length; i++) {
      const s = Math.max(-1, Math.min(1, f32[i]));
      pcm16[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
    }
    ws.send(JSON.stringify({ type: 'input_audio', audio: bytesToBase64(new Uint8Array(pcm16.buffer)) }));
  };
  src.connect(node); node.connect(ctx.destination);
}

Browser: lückenlose Wiedergabe + barge-in

Das Audio des Agent kommt als Strom von PCM16-Chunks mit output_rate. Dekodieren Sie jedes in Float, planen Sie es direkt hintereinander auf einem Wiedergabe-AudioContext, und halten Sie einen laufenden Cursor, damit Chunks sich nicht überlappen oder Lücken entstehen:

const playCtx = new AudioContext({ sampleRate: outputRate });
let playHead = 0;
const sources = [];

function playChunk(base64) {
  const bytes = base64ToBytes(base64);
  const pcm16 = new Int16Array(bytes.buffer);
  const buf = playCtx.createBuffer(1, pcm16.length, outputRate);
  const ch = buf.getChannelData(0);
  for (let i = 0; i < pcm16.length; i++) ch[i] = pcm16[i] / 0x8000;

  const node = playCtx.createBufferSource();
  node.buffer = buf;
  node.connect(playCtx.destination);
  const startAt = Math.max(playCtx.currentTime, playHead);
  node.start(startAt);
  playHead = startAt + buf.duration;
  sources.push(node);
}

// Barge-in: when the user starts speaking, stop the agent immediately.
function flushPlayback() {
  for (const n of sources) { try { n.stop(); } catch {} }
  sources.length = 0;
  playHead = 0;
}

Rufen Sie flushPlayback() für die user_speaking Nachricht auf, damit der Agent sofort aufhört zu sprechen, wenn der Benutzer unterbricht — das natürliche Gefühl einer echten Konversation.

Kamera-Frames

Siehe Multimodal für die Leinwand-Erfassungsschleife — zeichnen Sie den <video> auf eine Leinwand, toDataURL('image/jpeg', 0.6), entfernen Sie das Präfix und senden Sie eine video_frame Nachricht in einem anbietergerechten Takt (~700 ms Gemini, ~2.5 s OpenAI).

Eine Checkliste

• Schlüssel + Werkzeuge leben auf dem Server, niemals im Browser.
• Senden Sie ready mit input_rate/output_rate vor dem Audio; erstellen Sie AudioContexts mit diesen Raten.
• Nehmen Sie das Mikrofon als PCM16 mono bei input_rate auf.
• Spielen Sie Agenten-Audio lückenlos mit einem Planungs-Cursor bei output_rate ab.
• Leeren Sie die Wiedergabe bei user_speaking (barge-in).
• Rufen Sie create_response() nach send_text auf (nicht für VAD audio).
• Behandeln Sie video_frame Sende-Fehler als nicht-fatal.
• _ => {} aktivieren, wenn es ServerEvent entspricht (es ist #[non_exhaustive]).

Weiter: Beispiele →