Design a voice agent

An agent that writes beautifully will, without changes, make a terrible speaker. It will read bullet markers out loud, spell URLs character by character, and deliver a four-paragraph answer to a question someone asked while driving.

Create voice.toml beside agent.toml to fix that:

voice_instructions = """
Speak in short, conversational sentences.
Do not read markdown, raw URLs, or code aloud.
Confirm before taking consequential actions.
"""

[voice_ids]
cartesia = "your-cartesia-voice-id"
elevenlabs = "your-elevenlabs-voice-id"

Write for the ear

A listener cannot skim, cannot scroll back, and has no visual structure to lean on. Everything follows from that:

• Use short sentences and natural transitions instead of headings.
• Use summaries rather than dense lists. A brief structure, such as naming three things and walking through them, works better than a nine-item list.
• Acknowledge slow actions out loud. Tools add latency, and silence on a phone call reads as a dropped connection, not as thinking.

The instruction to confirm before consequential actions matters too. Voice removes the pause that typing gives someone, so an agent that acts quickly can act before the user has finished reconsidering.

Test the awkward paths

A happy-path conversation tells you almost nothing. The interesting cases are the ones that break the rhythm:

• Interruption - the user talks over the agent.
• Silence - the user says nothing for a while.
• A slow tool call - what fills the gap.
• A long response - whether it stays listenable past thirty seconds.

Next

• Configure voice providers - the platform half of the setup.
• Create your first agent - where response_format lives.
• Voice reference - voice IDs and session behavior.