AI-translated from English; not yet reviewed by a fluent editor.
# Crie um agente de voz Realtime local com chamadas de ferramentas apenas de leitura
> Crie uma conversa de voz em direto no navegador com OpenAI Realtime e duas ferramentas fictícias apenas de leitura. O código completo do servidor, navegador e controlador mostra a associação de IDs, a continuação segura, a interrupção e a libertação do microfone.
By BIG CHANGE Editorial
Published: 2026-10-19T23:39:53.236Z
Updated: 2026-10-19T23:39:53.236Z
Canonical: https://bigchange.ai/blog/openai-realtime-voice-read-only-tool-calls-guide
AI-generated conceptual illustration by BIG CHANGE; no actual OpenAI interface, API session, device test or heard answer is depicted.
Uma conversa de voz no navegador fica mais complexa quando a resposta exige várias consultas. O modelo pode devolver várias chamadas de função em uma única resposta concluída. Cada resultado deve voltar com seu próprio `call_id`, e uma nova resposta só deve começar depois do envio dos resultados. Este guia oferece um exemplo localhost completo para desenvolvedores: entrada de microfone em direto, reprodução WebRTC contínua, duas ferramentas fictícias apenas de leitura, turnos repetidos e limpeza após interrupções. Ele amplia nosso [guia básico de voz no navegador](https://bigchange.ai/blog/openai-realtime-browser-voice-webrtc-guide), que gera uma resposta falada sem ferramentas externas.
## A grande mudança
- **O que mudou:** A [API Realtime](https://developers.openai.com/api/docs/guides/realtime-conversations) da OpenAI pode devolver chamadas de função em uma sessão de voz em direto. Este exemplo associa chamadas concluídas aos resultados locais por `call_id` antes de pedir que o modelo continue.
- **Por que importa:** Um desenvolvedor pode testar uma resposta falada que dependa de várias consultas apenas de leitura, mantendo a captura e a reprodução do microfone no navegador e a chave API padrão no servidor local.
- **O que observar:** As verificações locais exercitam a ordem dos eventos e a limpeza com eventos sintéticos. Sua própria sessão paga precisa confirmar se conta, navegador, dispositivos e rede produzem respostas audíveis, corretas e a faturação esperada.
O exemplo usa o endpoint WebRTC Realtime padrão da OpenAI `/v1/realtime/calls` com `gpt-realtime-2.1`. Não usa o protocolo separado de sessões GPT-Live. Os dois valores de “biblioteca” abaixo são dados fictícios para testes de software, não informações sobre um lugar real. A BIG CHANGE verificou a documentação atual de [WebRTC](https://developers.openai.com/api/docs/guides/voice-webrtc), [conversas](https://developers.openai.com/api/docs/guides/realtime-conversations), [ferramentas](https://developers.openai.com/api/docs/guides/realtime-mcp) e [eventos](https://developers.openai.com/api/reference/resources/realtime/client-events) em 20 de outubro de 2026. Executamos verificações locais sintéticas do controlador e do navegador, mas não abrimos uma sessão API paga nem testamos captura real de microfone ou som.
## 1. Verifique o acesso e crie os cinco ficheiros
É necessário ter Node.js 22.6 ou posterior, um navegador atual com microfone e colunas e um projeto API da OpenAI com acesso a `gpt-realtime-2.1`. A [página do modelo](https://developers.openai.com/api/docs/models/gpt-realtime-2.1) informa que o nível Free não é compatível. Verifique primeiro a faturação API e os limites de pedidos e gastos do projeto; uma subscrição ChatGPT não cobre o uso da API. Coloque `OPENAI_API_KEY` no **ambiente do processo servidor** pelo seu mecanismo local habitual de proteção de segredos. Não a coloque nestes ficheiros, no código do navegador ou em transcrições. Use falas que tenha autorização para enviar à OpenAI.
Crie um diretório e guarde cada um dos cinco blocos completos abaixo com o nome indicado acima dele. Preserve as extensões `.mjs` e mantenha todos os ficheiros no mesmo diretório. O servidor escuta em `127.0.0.1:3000`. Ele recebe a oferta SDP da página local, encaminha à OpenAI com a chave do servidor e devolve a resposta SDP. O navegador não recebe uma chave API padrão. As verificações locais de Host e Origin ajudam a restringir a demonstração ao localhost; não autenticam utilizadores de um serviço partilhado.
**server.mjs**
```javascript
import express from "express";
const app = express();
// This demo accepts only the local page, including protection against DNS rebinding.
app.use((req, res, next) => {
const hosts = ["localhost:3000", "127.0.0.1:3000"];
if (!hosts.includes(req.get("host"))) return res.status(403).send("Local host required");
if (req.method === "POST" && req.get("origin") !== `http://${req.get("host")}`) {
return res.status(403).send("Same-origin local page required");
}
next();
});
app.use(express.text({ type: "application/sdp", limit: "64kb" }));
app.get("/", (_req, res) => res.sendFile("index.html", { root: process.cwd() }));
app.get("/controller.mjs", (_req, res) => res.sendFile("controller.mjs", { root: process.cwd() }));
app.post("/session", async (req, res) => {
if (!process.env.OPENAI_API_KEY) return res.status(500).send("Server API key missing");
if (typeof req.body !== "string" || !req.body.startsWith("v=")) {
return res.status(400).send("Expected an SDP offer");
}
const form = new FormData();
form.set("sdp", req.body);
form.set("session", JSON.stringify({
type: "realtime",
model: "gpt-realtime-2.1",
output_modalities: ["audio"],
audio: { output: { voice: "marin" } },
instructions: "Answer questions about the fictional demo library only using its read-only tools. State clearly that the data is synthetic software test data, not real venue information. For a lookup that may take noticeable time, give one short spoken progress preamble when useful, then call the tools. A preamble is never a result. Do not invent missing information. If a tool result is an error, say that lookup failed. Respond concisely in speech.",
tools: [
{ type: "function", name: "get_demo_hours", description: "Read synthetic demo-library opening hours; no external account or network.", parameters: { type: "object", properties: {}, additionalProperties: false } },
{ type: "function", name: "get_demo_address", description: "Read synthetic demo-library address; no external account or network.", parameters: { type: "object", properties: {}, additionalProperties: false } }
],
tool_choice: "auto"
}));
try {
const upstream = await fetch("https://api.openai.com/v1/realtime/calls", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
body: form,
signal: AbortSignal.timeout(25000)
});
const answer = await upstream.text();
if (!upstream.ok) {
console.error("Realtime session rejected", upstream.status);
return res.status(502).send(`OpenAI session request failed (${upstream.status})`);
}
res.type("application/sdp").send(answer);
} catch (error) {
console.error("Realtime session network failure", error.name);
res.status(502).send("Could not reach the Realtime API");
}
});
app.listen(3000, "127.0.0.1", () => console.log("Open http://localhost:3000"));
```
**index.html**
```html
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Local Realtime voice and read-only tool check</title>
<h1>Local voice and tool check</h1>
<p>The library data in this demo is synthetic software test data.</p>
<button id="start">Start voice</button>
<button id="stop" disabled>Stop and release microphone</button>
<p id="status" role="status">Idle</p>
<audio id="reply" autoplay controls></audio>
<pre id="events" aria-label="Event status"></pre>
<script type="module">
import { ToolController } from "/controller.mjs";
const start = document.querySelector("#start");
const stop = document.querySelector("#stop");
const status = document.querySelector("#status");
const events = document.querySelector("#events");
const reply = document.querySelector("#reply");
let current;
function note(line) {
events.textContent = `${line}\n${events.textContent}`.slice(0, 3000);
}
// These values are synthetic test fixtures, never real business records.
async function runDemoTool(call, signal) {
if (signal.aborted) throw Error("interrupted");
let args;
try { args = JSON.parse(call.arguments); } catch { return { ok: false, error: "Invalid arguments" }; }
if (!args || Array.isArray(args) || typeof args !== "object" || Object.keys(args).length) {
return { ok: false, error: "Expected an empty object" };
}
if (call.name === "get_demo_hours") return { ok: true, value: "Synthetic demo library hours: Monday-Friday 09:00-17:00." };
if (call.name === "get_demo_address") return { ok: true, value: "Synthetic demo library address: 1 Example Lane. This is not a real venue." };
return { ok: false, error: "Tool is not allowed" };
}
function closeSession(session = current, message = "Stopped") {
if (!session || session.closed) return;
session.closed = true;
clearTimeout(session.setupTimer);
clearTimeout(session.sessionTimer);
session.controller?.close();
session.abort.abort();
session.mic?.getTracks().forEach(track => track.stop());
if (session.pc) session.pc.onconnectionstatechange = null;
session.dc?.close();
session.pc?.close();
reply.pause();
if (current === session) {
current = null;
reply.srcObject = null;
start.disabled = false;
stop.disabled = true;
status.textContent = message;
note(message);
}
}
start.onclick = async () => {
const session = { abort: new AbortController(), closed: false };
current = session;
start.disabled = true;
stop.disabled = false;
status.textContent = "Requesting microphone";
events.textContent = "";
session.setupTimer = setTimeout(() => closeSession(session, "Setup timed out; microphone stopped"), 30000);
try {
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
if (session.closed) { mic.getTracks().forEach(track => track.stop()); return; }
session.mic = mic;
const pc = session.pc = new RTCPeerConnection();
pc.ontrack = event => {
if (session.closed) return;
reply.srcObject = event.streams[0];
reply.play().catch(() => note("Playback blocked; press Play on the audio control"));
};
pc.onconnectionstatechange = () => {
if (session.closed) return;
note(`Peer: ${pc.connectionState}`);
if (pc.connectionState === "connected") {
clearTimeout(session.setupTimer);
clearTimeout(session.sessionTimer);
session.sessionTimer = setTimeout(() => closeSession(session, "Local session limit reached; microphone stopped"), 55 * 60000);
status.textContent = "Connected; ask about the synthetic demo library";
}
if (["failed", "closed", "disconnected"].includes(pc.connectionState)) closeSession(session, "Connection ended; microphone stopped");
};
pc.addTrack(mic.getAudioTracks()[0], mic);
const dc = session.dc = pc.createDataChannel("oai-events");
const send = event => {
if (session.closed || dc.readyState !== "open") throw Error("Event channel is not open");
dc.send(JSON.stringify(event));
};
session.controller = new ToolController({
send, runTool: runDemoTool,
status: note,
fatal: message => closeSession(session, `${message}; microphone stopped`)
});
dc.onmessage = message => {
if (session.closed) return;
let event;
try { event = JSON.parse(message.data); } catch { closeSession(session, "Invalid event; microphone stopped"); return; }
if (event.type === "session.created") note("Realtime session created");
if (event.type === "output_audio_buffer.cleared") note("Server cleared unplayed speech after interruption");
session.controller.handle(event).catch(() => closeSession(session, "Controller failed; microphone stopped"));
};
dc.onclose = () => { if (!session.closed) closeSession(session, "Event channel closed; microphone stopped"); };
dc.onerror = () => closeSession(session, "Event channel failed; microphone stopped");
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
if (session.closed) return;
const response = await fetch("/session", {
method: "POST", headers: { "Content-Type": "application/sdp" },
body: offer.sdp, signal: session.abort.signal
});
if (!response.ok) throw Error(`Session request failed (${response.status})`);
const answer = await response.text();
if (session.closed) return;
await pc.setRemoteDescription({ type: "answer", sdp: answer });
if (!session.closed) status.textContent = "Signaling complete; waiting for connection";
} catch (error) {
if (!session.closed) closeSession(session, `Start failed: ${error.message}`);
}
};
stop.onclick = () => closeSession();
window.addEventListener("pagehide", () => closeSession());
</script>
</html>
```
**controller.mjs**
```javascript
// The same controller runs in the browser and in the synthetic local checks.
export class ToolController {
constructor({ send, runTool, status, fatal, setTimer = setTimeout, clearTimer = clearTimeout }) {
Object.assign(this, { send, runTool, status, fatal, setTimer, clearTimer });
this.epoch = 0;
this.rounds = 0;
this.counter = 0;
this.responses = new Map();
this.pending = null;
this.closed = false;
}
abortPending() {
if (!this.pending) return;
this.pending.abort.abort();
if (this.pending.timer) this.clearTimer(this.pending.timer);
this.pending = null;
}
close() {
this.closed = true;
this.epoch++;
this.abortPending();
this.responses.clear();
}
fail(message) {
if (this.closed) return;
this.status(message);
this.close();
this.fatal(message);
}
interrupt() {
if (this.closed) return;
this.epoch++;
this.rounds = 0;
this.abortPending();
this.status("Speech detected; interrupted result discarded");
}
async handle(event) {
if (this.closed) return;
if (event.type === "error") {
this.fail(`Realtime error: ${event.error?.code || event.error?.message || "unknown"}`);
return;
}
if (event.type === "input_audio_buffer.speech_started") { this.interrupt(); return; }
if (event.type === "response.created") {
if (event.response?.id) this.responses.set(event.response.id, this.epoch);
return;
}
if (event.type === "conversation.item.done") {
const p = this.pending;
const id = event.item?.id;
if (!p || p.epoch !== this.epoch || !p.acks.has(id)) return;
p.acks.delete(id);
if (p.acks.size === 0) {
if (p.timer) this.clearTimer(p.timer);
this.pending = null;
if (!p.abort.signal.aborted && !this.closed && p.epoch === this.epoch) {
this.status("All tool outputs acknowledged; resuming response");
this.send({ type: "response.create" });
}
}
return;
}
if (event.type !== "response.done") return;
const response = event.response;
const id = response?.id;
const responseEpoch = this.responses.get(id);
this.responses.delete(id);
if (responseEpoch === undefined || responseEpoch !== this.epoch) return;
this.status(`Response ${id}: ${response.status || "unknown"}`);
if (response.status !== "completed") return; // Never execute partial/cancelled calls.
const calls = (response.output || []).filter(item => item.type === "function_call");
if (!calls.length) return;
if (this.pending) { this.fail("Overlapping tool batches in one turn"); return; }
if (calls.length > 8 || ++this.rounds > 3) { this.fail("Tool call or round bound reached"); return; }
const ids = new Set();
for (const call of calls) {
if (call.status !== "completed" || !call.call_id || ids.has(call.call_id)) {
this.fail("Incomplete or repeated function call ID"); return;
}
ids.add(call.call_id);
}
const p = { epoch: this.epoch, abort: new AbortController(), acks: new Set(), timer: null };
this.pending = p;
this.status(`Executing ${calls.length} read-only local call(s) from ${id}`);
const outputs = await Promise.all(calls.map(async call => {
try { return { call, result: await this.runTool(call, p.abort.signal) }; }
catch { return { call, result: { ok: false, error: "Local lookup failed" } }; }
}));
if (this.closed || this.pending !== p || p.epoch !== this.epoch || p.abort.signal.aborted) return;
try {
for (const { call, result } of outputs) {
const itemId = `tool_output_${++this.counter}`;
p.acks.add(itemId);
this.send({
type: "conversation.item.create",
event_id: `tool_event_${this.counter}`,
item: { id: itemId, type: "function_call_output", call_id: call.call_id, output: JSON.stringify(result) }
});
this.status(`Sent result for ${call.call_id}`);
}
p.timer = this.setTimer(() => this.fail("Tool output acknowledgement timed out"), 8000);
} catch { this.fail("Could not send tool outputs"); }
}
}
```
**protocol-check.mjs**
```javascript
import assert from "node:assert/strict";
import { ToolController } from "./controller.mjs";
const deferred = () => { let resolve, reject; const promise = new Promise((a, b) => { resolve = a; reject = b; }); return { promise, resolve, reject }; };
const tick = () => new Promise(resolve => setImmediate(resolve));
const call = (id, name = "get_demo_hours") => ({ type: "function_call", status: "completed", call_id: id, name, arguments: "{}" });
const created = id => ({ type: "response.created", response: { id } });
const done = (id, status, output = []) => ({ type: "response.done", response: { id, status, output } });
function harness(runTool = async x => ({ ok: true, value: x.name })) {
const sent = [], statuses = [], failures = [];
const timers = new Map(); let nextTimer = 0;
const controller = new ToolController({
send: e => sent.push(e), runTool,
status: s => statuses.push(s), fatal: e => failures.push(e),
setTimer: callback => { const id = ++nextTimer; timers.set(id, callback); return id; },
clearTimer: id => timers.delete(id)
});
return { controller, sent, statuses, failures, timers };
}
// Mixed audio/message output, two asynchronous calls resolved in reverse order.
{
const a = deferred(), b = deferred();
const h = harness(x => x.call_id === "call_A" ? a.promise : b.promise);
await h.controller.handle(created("resp_1"));
const work = h.controller.handle(done("resp_1", "completed", [
{ type: "message", status: "completed", content: [{ type: "output_audio", transcript: "Checking." }] },
call("call_A"), call("call_B", "get_demo_address")
]));
b.resolve({ ok: true, value: "address" }); await tick();
assert.equal(h.sent.length, 0, "first finished lookup must not send or resume early");
a.resolve({ ok: true, value: "hours" }); await work;
assert.deepEqual(h.sent.map(x => x.item?.call_id), ["call_A", "call_B"]);
assert.equal(h.sent.filter(x => x.type === "response.create").length, 0);
await h.controller.handle({ type: "conversation.item.done", item: { id: h.sent[1].item.id } });
assert.equal(h.sent.filter(x => x.type === "response.create").length, 0);
await h.controller.handle({ type: "conversation.item.done", item: { id: h.sent[0].item.id } });
assert.equal(h.sent.filter(x => x.type === "response.create").length, 1, "one resume after both item acknowledgements");
}
// One local lookup error does not erase the other result.
{
const h = harness(async x => { if (x.call_id === "bad") throw Error("synthetic failure"); return { ok: true, value: "fixture" }; });
await h.controller.handle(created("resp_2"));
await h.controller.handle(done("resp_2", "completed", [call("bad"), call("good")]));
assert.equal(JSON.parse(h.sent[0].item.output).ok, false);
assert.equal(JSON.parse(h.sent[1].item.output).ok, true);
for (const e of h.sent.slice()) await h.controller.handle({ type: "conversation.item.done", item: { id: e.item.id } });
assert.equal(h.sent.filter(x => x.type === "response.create").length, 1);
}
// Partial/cancelled responses never dispatch a call.
for (const status of ["failed", "incomplete", "cancelled"]) {
const h = harness();
await h.controller.handle(created(`resp_${status}`));
await h.controller.handle(done(`resp_${status}`, status, [call("ignored")]));
assert.equal(h.sent.length, 0);
}
// Distinct rounds are bounded, and missing/duplicate IDs are rejected.
{
const h = harness();
for (let i = 1; i <= 3; i++) {
await h.controller.handle(created(`round_${i}`));
await h.controller.handle(done(`round_${i}`, "completed", [call(`call_${i}`)]));
const last = h.sent.at(-1);
await h.controller.handle({ type: "conversation.item.done", item: { id: last.item.id } });
}
await h.controller.handle(created("round_4"));
await h.controller.handle(done("round_4", "completed", [call("too_many")]));
assert.match(h.failures[0], /bound/);
assert.equal(h.sent.filter(x => x.type === "response.create").length, 3);
}
{
const h = harness();
await h.controller.handle(created("dup"));
await h.controller.handle(done("dup", "completed", [call("same"), call("same")]));
assert.match(h.failures[0], /repeated/);
}
// User speech or Stop invalidates in-flight lookups and ignores their late results.
for (const mode of ["speech", "stop"]) {
const d = deferred(), h = harness(() => d.promise);
await h.controller.handle(created(`resp_${mode}`));
const work = h.controller.handle(done(`resp_${mode}`, "completed", [call("late")]));
if (mode === "speech") await h.controller.handle({ type: "input_audio_buffer.speech_started" });
else h.controller.close();
d.resolve({ ok: true, value: "late fixture" }); await work;
assert.equal(h.sent.length, 0);
}
// A late response completion or acknowledgement from the interrupted turn cannot resume it.
{
const h = harness();
await h.controller.handle(created("old"));
await h.controller.handle({ type: "input_audio_buffer.speech_started" });
await h.controller.handle(done("old", "completed", [call("late_call")]));
assert.equal(h.sent.length, 0);
await h.controller.handle(created("new"));
await h.controller.handle(done("new", "completed", [call("fresh_call")]));
const output = h.sent[0];
await h.controller.handle({ type: "input_audio_buffer.speech_started" });
await h.controller.handle({ type: "conversation.item.done", item: { id: output.item.id } });
assert.equal(h.sent.filter(x => x.type === "response.create").length, 0);
}
// Missing server acknowledgement closes instead of speculatively resuming.
{
const h = harness();
await h.controller.handle(created("no_ack"));
await h.controller.handle(done("no_ack", "completed", [call("one")]));
assert.equal(h.timers.size, 1);
[...h.timers.values()][0]();
assert.match(h.failures[0], /timed out/);
assert.equal(h.sent.filter(x => x.type === "response.create").length, 0);
}
console.log("Synthetic controller checks passed: ordering, single resume, error isolation, bounds and interruption.");
```
**browser-check.mjs**
```javascript
import assert from "node:assert/strict";
import fs from "node:fs";
import vm from "node:vm";
import { ToolController } from "./controller.mjs";
const html = fs.readFileSync(new URL("./index.html", import.meta.url), "utf8");
const script = html.match(/<script type="module">([\s\S]*?)<\/script>/)?.[1]
.replace('import { ToolController } from "/controller.mjs";', "");
assert.ok(script, "inline browser module found");
function fakePage(mediaPromise) {
const nodes = Object.fromEntries(["#start", "#stop", "#status", "#events", "#reply"].map(k => [k, {
disabled: k === "#stop", textContent: "", srcObject: null,
pause() { this.paused = true; }, play() { return Promise.resolve(); }
}]));
let fetches = 0, peer;
class FakePeer {
constructor() { peer = this; this.connectionState = "new"; }
addTrack() {}
createDataChannel() { return this.dc = { readyState: "open", close() { this.closed = true; }, send() {} }; }
async createOffer() { return { sdp: "v=0" }; }
async setLocalDescription() {}
async setRemoteDescription() {}
close() { this.closed = true; }
}
vm.runInNewContext(script, {
ToolController, document: { querySelector: k => nodes[k] },
navigator: { mediaDevices: { getUserMedia: () => mediaPromise } },
RTCPeerConnection: FakePeer,
fetch: async () => { fetches++; return { ok: true, text: async () => "answer" }; },
window: { addEventListener() {} },
AbortController, setTimeout, clearTimeout, console
});
return { nodes, peer: () => peer, fetches: () => fetches };
}
// Stop while permission is pending; any late track is released without a session request.
{
let allowMic;
const page = fakePage(new Promise(resolve => { allowMic = resolve; }));
const starting = page.nodes["#start"].onclick();
page.nodes["#stop"].onclick();
const track = { stopped: false, stop() { this.stopped = true; } };
allowMic({ getTracks: () => [track], getAudioTracks: () => [track] });
await starting;
assert.equal(track.stopped, true);
assert.equal(page.fetches(), 0);
assert.equal(page.nodes["#start"].disabled, false);
}
// Stop after signaling: microphone, data channel, peer and playback all close.
{
const track = { stopped: false, stop() { this.stopped = true; } };
const page = fakePage(Promise.resolve({ getTracks: () => [track], getAudioTracks: () => [track] }));
await page.nodes["#start"].onclick();
page.nodes["#stop"].onclick();
assert.equal(page.fetches(), 1);
assert.equal(track.stopped, true);
assert.equal(page.peer().closed, true);
assert.equal(page.peer().dc.closed, true);
assert.equal(page.nodes["#reply"].paused, true);
assert.equal(page.nodes["#reply"].srcObject, null);
}
console.log("Synthetic browser lifecycle checks passed: late microphone and full Stop cleanup.");
```
Nesse diretório, instale a única dependência do servidor e inicie-o:
```bash
npm init -y
npm install express
node server.mjs
```
Abra `http://localhost:3000`. A página deve mostrar **Start voice**, **Stop and release microphone**, um leitor de áudio e o estado dos eventos. Somente a página do navegador e o módulo controlador são servidos; as duas funções fictícias são executadas no navegador e não acessam lugar real, calendário, CRM ou conta empresarial.
## 2. Inicie, ouça e inspecione o resultado
Clique em **Start voice**, autorize o microfone e espere por **Connected**. Pergunte o horário e o endereço da biblioteca fictícia de demonstração. O navegador envia o som pela faixa de mídia WebRTC e liga a fala remota ao controlo de áudio assim que a faixa chega. Se a reprodução automática for bloqueada, pressione **Play** no controlo visível. O prompt do servidor pede uma breve fala de progresso quando útil. O modelo pode omiti-la; ouvi-la não comprova que uma consulta funcionou.
O painel de eventos informa estados das respostas, IDs de chamadas e confirmações de saída sem imprimir chave, áudio bruto ou transcrição. O modelo pode escolher nenhuma, uma ou várias ferramentas. Quando um `response.done` tem `status: completed`, o controlador examina **todos** os itens de saída em busca de itens `function_call` concluídos e verifica se cada `call_id` está presente e é único. Executa as consultas permitidas, inclusive várias simultaneamente, e envia um `function_call_output` para cada ID original. Uma consulta malsucedida vira um resultado de erro para aquela chamada, preservando os demais resultados. O controlador espera `conversation.item.done` para cada ID atribuído ao item de saída antes de enviar um único `response.create`. Esperar todas as confirmações é uma escolha conservadora de ordenação deste exemplo, não uma exigência da API. Ele permite no máximo oito chamadas por resposta e três rodadas de ferramentas por turno sem interrupção; são limites locais.
Procure **Realtime session created**, o par ligado, IDs de chamadas se houver, confirmações das saídas e uma resposta subsequente concluída. Ouça e compare o horário e endereço informados com as strings fictícias em `index.html`. Um evento de resposta concluída não comprova reprodução audível nem exatidão. Essas observações exigem sua própria execução cobrada no navegador; a BIG CHANGE não a realizou.
## 3. Repita um turno, interrompa e liberte o microfone
Faça outra pergunta sem reiniciar. Para testar uma interrupção, fale enquanto o modelo responde ou uma consulta está pendente. Com WebRTC e detecção de atividade de voz, a OpenAI documenta cancelamento e truncamento, gerido pelo servidor, do áudio ainda não reproduzido. Ao receber `input_audio_buffer.speech_started`, o controlador local também invalida consultas pendentes para que um resultado tardio não retome a resposta interrompida. Este código não implementa o cursor de reprodução e os eventos de truncamento separados necessários a um leitor de áudio WebSocket.
Clique em **Stop and release microphone** e confirme que o indicador de microfone do navegador se apaga. A paragem funciona mesmo durante um pedido de permissão: se a autorização chegar tarde, a faixa devolvida é imediatamente parada. A mesma limpeza interrompe as faixas, cancela o pedido de sessão em curso, fecha o canal de dados e o par, pausa e desliga a reprodução, cancela as ferramentas e remove os temporizadores ao sair da página, exceder o prazo de configuração ou da sessão local, ou falhar a ligação. O exemplo usa 30 segundos para a configuração e 55 minutos para a sessão local; a OpenAI documenta um máximo Realtime de 60 minutos.
## 4. Execute as verificações locais e recupere falhas
No mesmo diretório, execute:
```bash
node --check server.mjs
node --check controller.mjs
node protocol-check.mjs
node browser-check.mjs
```
Os dois scripts usam eventos sintéticos e simulações do navegador. Verificam uma resposta mista de mensagem/funções, duas chamadas concluídas na ordem inversa, todas as saídas e confirmações antes de uma continuação única, isolamento de erros por chamada, execução apenas de chamadas concluídas, limites de rodadas, interrupção de fala, libertação após permissão tardia e limpeza com Stop. Não fazem pedidos API. Passar não mede tempos de rede, dispositivos reais, qualidade de voz ou confiabilidade em produção.
Se **Start** falhar, leia o estado visível e o status HTTP recebido pelo servidor local do serviço externo. Verifique permissão, `localhost:3000`, chave no ambiente do servidor, acesso ao modelo, faturação, limites e rede. Um 502 pode refletir rejeição externa, falha de rede ou o prazo de 25 segundos da pedido do exemplo; não prova que a OpenAI nunca a recebeu. Se o par ligar sem som, verifique dispositivos de entrada e saída e pressione **Play**. Uma resposta com falha, incompleta ou cancelada não executa chamadas parciais. Se uma confirmação de saída exceder o prazo, o controlador fecha a sessão em vez de enviar uma continuação possivelmente duplicada e incerta. Quando o resultado do início ou da rede for desconhecido, pare a sessão, confirme a libertação do microfone e consulte a utilização do projeto antes de tentar novamente; um pedido cancelado pode já ter gerado custos.
## Custos e limites
A [página do modelo](https://developers.openai.com/api/docs/models/gpt-realtime-2.1) e a [tabela de preços](https://developers.openai.com/api/docs/pricing) da OpenAI, verificadas em 20 de outubro de 2026, indicam texto de entrada/saída sem cache a 4/24 dólares dos EUA por milhão de tokens e áudio de entrada/saída a 32/64 dólares dos EUA. Os valores reais dependem dos tokens, áudio e contexto de conversa repetido. Não medimos fatura, latência, comportamento de ferramentas em direto ou fala inicial de progresso. O som do microfone é enviado à OpenAI. As funções sintéticas fixas não autorizam integrações empresariais reais nem ações de escrita. Uma disponibilização partilhada exigiria identidade de utilizador, limites, autorização de ferramentas, monitorização e revisão próprios.
### Fontes e leituras adicionais
- [Guia WebRTC da OpenAI](https://developers.openai.com/api/docs/guides/voice-webrtc): faixa de mídia do navegador, reprodução remota, canal de dados e troca SDP pelo servidor confiável. Não testa este navegador ou conta específicos.
- [Conversas Realtime](https://developers.openai.com/api/docs/guides/realtime-conversations): saída completa de respostas concluídas, sequência de resultados de funções, interrupção e máximo de sessão de 60 minutos. Não promete que um modelo específico use ferramenta.
- [Ferramentas Realtime](https://developers.openai.com/api/docs/guides/realtime-mcp): chamadas de função geridas pela aplicação e `function_call_output`. Não comprova o sucesso destes dados locais de teste.
- [Eventos do cliente](https://developers.openai.com/api/reference/resources/realtime/client-events) e do [servidor](https://developers.openai.com/api/reference/resources/realtime/server-events): IDs de itens, confirmações e formatos de eventos de resposta. Esperar todas as confirmações é uma escolha local do exemplo.
- [Orientação de prompts Realtime](https://developers.openai.com/api/docs/guides/voice-prompting): instrução para uma fala prévia condicional de progresso; não garante saída audível.
- [Acesso ao modelo](https://developers.openai.com/api/docs/models/gpt-realtime-2.1) e [preços API](https://developers.openai.com/api/docs/pricing): níveis de acesso atuais e tarifas de tokens. Verifique o uso do projeto para conhecer a faturação real.
## Sources
- [Guia WebRTC da OpenAI](https://developers.openai.com/api/docs/guides/voice-webrtc) — Documenta faixas de microfone e áudio remoto, canal de dados oai-events e troca SDP por servidor confiável com chave API padrão via /v1/realtime/calls. Não comprova o comportamento real dos dispositivos ou rede neste exemplo.
- [Conversas OpenAI Realtime](https://developers.openai.com/api/docs/guides/realtime-conversations) — Documenta saída completa de response.done e continuação após resultados de funções, interrupção WebRTC VAD com truncamento de áudio não reproduzido no servidor e máximo de 60 minutos. Não garante ferramentas nem exatidão falada na execução do leitor.
- [OpenAI Realtime com ferramentas](https://developers.openai.com/api/docs/guides/realtime-mcp) — Documenta funções geridas pela aplicação, itens function_call_output associados ao call_id original e continuação response.create. Esperar cada confirmação de saída é uma escolha local adicional.
- [Eventos do cliente OpenAI Realtime](https://developers.openai.com/api/reference/resources/realtime/client-events) — Define estruturas de conversation.item.create, IDs de itens, function_call_output e response.create usadas no exemplo; a referência não é teste de integração.
- [Eventos do servidor OpenAI Realtime](https://developers.openai.com/api/reference/resources/realtime/server-events) — Define estruturas de resposta concluída, confirmações de itens finalizados e erros do exemplo. A espera por todas as confirmações é escolha local, não exigência API nem teste de integração.
- [Detecção de atividade de voz da OpenAI](https://developers.openai.com/api/docs/guides/realtime-vad) — Documenta speech_started e speech_stopped para invalidar trabalho local; não testa uma interrupção real aqui.
- [Orientação de prompts OpenAI Realtime](https://developers.openai.com/api/docs/guides/voice-prompting) — Apoia pedir uma breve fala de progresso como comportamento condicional. Nenhuma foi observada em sessão paga.
- [Modelo OpenAI gpt-realtime-2.1](https://developers.openai.com/api/docs/models/gpt-realtime-2.1) — Indica o ID do modelo, o nível Free não suportado e as tarifas sem cache por milhão de tokens: texto entrada/saída 4/24 dólares dos EUA, áudio entrada/saída 32/64 dólares dos EUA. Acesso e faturação exigem a verificação da conta do leitor.
- [Preços API da OpenAI](https://developers.openai.com/api/docs/pricing) — Confirma os preços publicados de tokens de texto e áudio do gpt-realtime-2.1; não fornece custo fixo para a sessão deste guia.
- [Cobrança API OpenAI e ChatGPT](https://help.openai.com/en/articles/9039756-managing-billing-for-chatgpt-and-the-api-platform) — A OpenAI informa que a API é cobrada separadamente da subscrição ChatGPT. Não estabelece saldo atual ou limites do projeto do leitor.
Newsletter BIG CHANGE
A perspetiva geral, ao seu ritmo.
Histórias recentes sobre IA e robótica, mudanças que vale a pena acompanhar e ideias práticas para utilizar. Escolha um briefing diário, um resumo semanal ou uma perspetiva mensal.
Next scheduled send (UTC): . Your first edition arrives at the next scheduled send after you confirm.
A sua privacidade, a sua escolha.
O armazenamento necessário ajuda a proteger o site e a memorizar as suas escolhas. O Google Analytics opcional permanece desativado até que o autorize. Pode ler todos os artigos utilizando apenas o armazenamento necessário. Detalhes de privacidade