Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Conversation design

The conversation option shapes how the agent participates without exposing low-level audio or model controls.
ts
const session = await LiveVoice.connect({
  token,
  prompt: `Guide the user through an equipment inspection.
  Record completed checks with the supplied tools.`,
  conversation: {
    starts: "assistant",
    prompt: `Be warm and direct.
    Let the user finish a sequence before asking about missing details.`,
  },
  tools,
});

Choose who opens

Set starts to define the opening rule:
ts
conversation: {
  starts: "assistant",
}
  • "assistant" lets the agent greet the user and begin the task.
  • "user" keeps the agent listening until the user speaks.
Put the substance of an opening in the task prompt. Use starts only to decide who goes first.

Add phase-aware guidance

Phases let your application give the agent a shared vocabulary for a workflow. They are useful when conversational behavior should change as the task advances.
ts
conversation: {
  starts: "assistant",
  phases: {
    initial: "introduction",
    prompt: `Move phases only when the current phase's goal is complete.
    Briefly orient the user whenever the phase changes.`,
    definitions: {
      introduction: "Explain the process and establish what the user is checking.",
      inspection: "Collect observations and use tools to record completed checks.",
      review: "Summarize unresolved items and confirm the final result.",
    },
  },
}
The agent can advance the tracked phase when the conversation establishes that the next stage has begun. Your application receives the committed change:
ts
session.on("phase", ({ phase, previousPhase }) => {
  showWorkflowStep(phase, previousPhase);
});
Phase names and definitions belong to the developer. They should describe product or task stages—not whether someone is speaking, waiting, or being interrupted.

Keep the boundary clean

Good conversation guidance expresses intent:
  • "Let the user complete a short list before clarifying missing values."
  • "Use brief acknowledgments during long explanations."
  • "Be more deliberate during the final review."
Avoid prescribing hidden implementation mechanics:
  • model or provider names;
  • millisecond thresholds;
  • audio buffering or playback rules;
  • transcript reconciliation instructions;
  • score formulas for deciding who speaks.
This keeps the application contract stable as Live Voice improves underneath it.