Build a conversational agent

Beta. This is an experimental pattern under active development. The speculative prefetch approach chains several real-time behaviors — interim results, debounced finalization, and stateless prefetch calls — so response quality and timing can vary. Treat it as a starting point for exploration rather than a production-ready recipe, and reach out to discuss your use case or share feedback.

Follow along with the runnable example. This guide walks through the conversational agent example in corti-examples — bootstrap your build from it or use it as reference.

Unlike the wake-command agent, a conversational agent needs no trigger phrase. The mic runs continuously and every completed utterance is forwarded to the agent. The core UX technique is speculative prefetch: the agent fires a stateless request while the user is still speaking so the response is often ready the instant they stop.

This builds on the agent lifecycle from On-Demand Agent and the threading pattern from Wake-Command Agent.The prompts used here are mere examples - be sure to test and refine the prompt to support your specific needs.

Configure for always-on capture

Enable interim results so transcripts arrive while the user is still speaking. Disable automatic punctuation to reduce noise in partial text, and enable audio events so the session can detect silence. See the conversational agent example in corti-examples for the full dictationConfig and event wiring.

Fire a speculative request on interim text

On the first interim of each turn, schedule a short debounce (200 ms) then fire a stateless agent call — no contextId, so the real conversation thread is never touched. If the user keeps speaking, the timer resets and a fresh call fires with the updated text.

JavaScript

let speculativeTimer: ReturnType<typeof setTimeout> | null = null;
let heldResponse: string | null = null;

function handleInterim(text: string) {
  if (speculativeTimer) clearTimeout(speculativeTimer);
  speculativeTimer = setTimeout(() => {
    speculativeTimer = null;
    void fireSpeculative(text);
  }, 200);
}

fireSpeculative sends the text to the agent without a contextId and stores the result in heldResponse. See the conversational agent example in corti-examples for the full implementation.

The speculative call is intentionally stateless. Sending partial interim text (e.g. “patient April”) with a contextId would corrupt the real thread — the provisional response is shown for perceived speed, then replaced in-place by the real contextual response.

Debounce finals and flush the turn

Buffer consecutive final segments and restart a silence timer on every new transcript event. When speech genuinely pauses — the timer fires without interruption — treat it as a complete turn and call handleFinal.

JavaScript

const RESPONSE_DEBOUNCE_MS = 1500; // configurable; 0.5–3.0 s range works well
let finalBuffer: string[] = [];
let debounceTimer: ReturnType<typeof setTimeout> | null = null;

dictation.addEventListener("transcript", (e: CustomEvent) => {
  const { text, isFinal } = e.detail.data;
  if (!isFinal) {
    handleInterim(text);
    resetDebounce();
  } else {
    finalBuffer.push(text);
    resetDebounce();
  }
});

function resetDebounce() {
  if (debounceTimer) clearTimeout(debounceTimer);
  debounceTimer = setTimeout(flushFinal, RESPONSE_DEBOUNCE_MS);
}

function flushFinal() {
  const text = finalBuffer.join(" ").trim();
  finalBuffer = [];
  if (text) void handleFinal(text);
}

// Also flush immediately when recording stops — no artificial delay at end of session.
dictation.addEventListener("recordingstop", () => {
  if (debounceTimer) clearTimeout(debounceTimer);
  flushFinal();
});

Commit the turn with the real context

When handleFinal fires, cancel any pending speculative timer. If heldResponse is set, display it optimistically and then replace it in-place with the real contextual response. If not set, show a thinking spinner while the contextual call completes. The real messageSend always uses contextId to keep the thread coherent — pass the current one and update it from the response. See the conversational agent example in corti-examples for the full implementation.

See Context & Memory for how threads work in the Agentic Framework. A 404 on messageSend means the agent or context was deleted — recreate the agent and retry the turn without the stale contextId.

Reset the conversation

To start over, call client.agents.deleteContext(agentId, contextId) to remove the server-side thread, then clear contextId, heldResponse, finalBuffer, and the message list.

Next steps

Wake-Command Agent

Gate the agent behind a spoken wake phrase instead of forwarding every utterance.

On-Demand Agent

The agent lifecycle and message API, for a single isolated pass.

Context & Memory

How conversation threads and memory work in the Agentic Framework.

Example code

The complete, runnable conversational agent example in corti-examples.

Please contact us for help or questions.

Endpoints

Features

Best Practices

Guides

Resources

Configure for always-on capture

Fire a speculative request on interim text

Debounce finals and flush the turn

Commit the turn with the real context

Reset the conversation

Next steps

Wake-Command Agent

On-Demand Agent

Context & Memory

Example code

​Configure for always-on capture

​Fire a speculative request on interim text

​Debounce finals and flush the turn

​Commit the turn with the real context

​Reset the conversation

​Next steps

Wake-Command Agent

On-Demand Agent

Context & Memory

Example code

Configure for always-on capture

Fire a speculative request on interim text

Debounce finals and flush the turn

Commit the turn with the real context

Reset the conversation

Next steps