> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Baseten Realtime Voice prompting guide

> Write instructions for a Baseten Realtime Voice agent, from role and conversation flow to facts, tools, delegation, and the greeting.

> [!NOTE]
>
> Baseten Realtime Voice is in **Private Preview**. [Join the waitlist](https://baseten.co/talk-to-us/voice-beta-launch)
> to get it enabled for your organization.

The system prompt is the `instructions` string in `session.update`. It replaces the deployment's default prompt and controls what the agent says. Other fields set how the agent sounds and hears: `audio.output.voice` picks the voice, and `audio.input.transcription.language` sets the language that speech-to-text (STT) expects.

This guide builds on the [phone support agent recipe](https://docs.baseten.co/inference/audio/realtime-voice/recipes.md#phone-support-agent). The examples use the same company, Northwind Fiber.

## What the agent adds to your instructions

Baseten Realtime Voice appends its own guidance to your `instructions`, so your prompt only needs to cover your business's specifics:

* **Spoken style.** Short replies, one question at a time, no lists, Markdown, or emoji. The appended guidance also covers how to collect and look up names, email addresses, phone numbers, and codes, and asks the caller to agree before making a change. To write your own style section instead, set `spoken_style: false`.
* **Tool acknowledgments.** When the session has tools, the agent says a short line such as "Thanks, checking that now" when a call takes more than a moment. Don't script your own preamble on top of it. To write your own, set `tool_acknowledgement: false`.
* **Delegation.** With [delegation](https://docs.baseten.co/reference/inference-api/predict-endpoints/realtime-voice-api.md#delegation) enabled, the delegate reads your `instructions` as the policy for the call, and the voice model reads them for how to speak.

Restating these rules in your prompt costs tokens on every turn, and a conflicting version of one makes the agent less predictable.

## Prompting tips

* **Change one thing at a time.** Small wording changes can shift behavior a lot. Test each change on a few calls before you make the next.
* **Prefer short bullet lists to paragraphs.** The model follows bullet lists more reliably than paragraphs.
* **Give example phrases.** The agent copies sample lines closely, so write them the way you want them said, and give a few so replies don't repeat.
* **Be precise.** Ambiguous or conflicting rules give inconsistent calls. Say what to do in the unclear case.
* **Emphasize sparingly.** `ALWAYS` and `NEVER` in capitals work for a few hard rules; on every line they stop meaning anything.

## Recommended structure

Write the prompt in Markdown with these sections in this order, and write it in the second person ("you"):

```text theme={"system"}
## Role
You are Riley, a customer support agent for Northwind Fiber, a home internet provider, on a live phone call.

## Objective
Fix the caller's connection or plan question on this call, or connect them with a specialist when you can't.

## Conversation flow
Ask what the caller needs. For a connection problem, look up the account with lookup_account, then
check_outage for their ZIP code before you suggest any steps. For a plan question, answer from the facts below.

## Facts
- Plans: Fiber 300 at $49.99 a month, Fiber Gig at $69.99, Fiber Max (2 gig) at $99.99.
- No contracts, no data caps. Installation is free.
- Technicians work 8am to 8pm, seven days a week.
- Most connection problems clear after restarting the router: unplug it for thirty seconds.

## Guardrails and escalation
- Stay on Northwind Fiber topics. For anything else, say you can only help with Northwind Fiber.
- Never invent account details, outages, or prices. If it isn't in a tool result or the facts, say you don't know.
- For billing changes, offer to connect the caller with a specialist.
```

## Role

Say who the agent is, who it works for, and that it's on a call. One or two sentences are enough. A name gives the agent an answer when the caller asks who they're speaking with.

```text theme={"system"}
## Role
You are Riley, a calm, efficient support agent for Northwind Fiber, on a live phone call.
```

## Objective

State the outcome the agent works toward and what it does when it can't reach it:

```text theme={"system"}
## Objective
Fix the caller's connection or plan question on this call, or connect them with a specialist when you can't.
```

## Conversation flow

Describe the call flow, naming only tools in the session. A few sentences of prose suit most agents, as in the earlier example.

If the agent skips steps or stalls, break the call into phases, each with a goal and a condition for moving on:

```text theme={"system"}
## Conversation flow
1. Identify. Ask for the phone number on the account and look it up. Move on once lookup_account returns the account.
2. Diagnose. Check for an outage at the account's ZIP code, then ask what the caller sees. Move on once you know the cause or have ruled out an outage.
3. Resolve. Walk the caller through one step at a time, and ask what they see after each one.
4. Close. Confirm the problem is fixed, or offer a technician visit.
```

## Facts

* **Put short facts in the prompt.** Prices, hours, and policies the agent quotes go in a `## Facts` section, in the words you want it to use.
* **Look up the rest.** Account data, order status, and anything long or changing belongs behind a [client tool or Model Context Protocol (MCP) server](https://docs.baseten.co/inference/audio/realtime-voice/recipes.md#client-tools).
* **Say what to do without an answer.** Tell the agent to say it doesn't know rather than guess.

## Guardrails and escalation

List what the agent won't do and when it hands off: an explicit request for a human, a caller who stays upset, a tool that keeps failing, or a topic outside its scope. For a handoff that your system carries out, give the agent a client tool such as `transfer_to_specialist`, and write the line the agent says when it calls the tool:

```text theme={"system"}
## Guardrails and escalation
- If the caller asks for a person, say "I'll connect you with a specialist now." and call transfer_to_specialist.
- If the caller describes an emergency, tell them to hang up and call 911.
```

An agent that may talk to someone in distress needs an escalation path like the second rule.

## Language and terms

* **Set the reply language.** Add a line such as "Respond only in English. If the caller speaks another language, say you can only help in English." Set `audio.input.transcription.language` to match, so STT expects that language.
* **Help STT hear your names.** List product and company names in `audio.input.transcription.keywords`. The [recipes](https://docs.baseten.co/inference/audio/realtime-voice/recipes.md#voice-and-transcription-settings) show the format.

## Tools

* **Mention only tools the session has.** A prompt that names a tool not in `tools` makes the agent try to call it, or claim it did.
* **Describe when to call each tool.** Keep the prompt for the order of steps; the [tool description](https://docs.baseten.co/inference/function-calling.md) says what each tool does and when.
* **Call read-only tools without asking.** Lookups and status checks don't need the caller's permission. The agent already asks before it changes anything.

## Delegation

When delegation is enabled, a stronger model reads your `instructions` as the policy for the call, calls your tools, and writes what the caller hears. Write the prompt as that policy:

* **Write the rules.** Put limits, verification steps, and handoff conditions in `instructions`, such as "Credits over \$50 need a supervisor; offer a callback instead."
* **Include the policy text.** Paste the billing or returns policy the delegate applies, so it decides from the policy rather than from what the caller says.
* **End on a question only to get an answer.** When the delegate's line ends with a question, the caller's reply goes straight back to it, without the voice model. Ask when the delegate needs the caller's answer, such as an order number or a confirmation. A closing "Is there anything else?" after every answer keeps the rest of the call on the slower delegate.
* **Don't route the work yourself.** Baseten Realtime Voice decides what to hand to the delegate, so the prompt doesn't need rules about when to delegate.

The [delegation recipe](https://docs.baseten.co/inference/audio/realtime-voice/recipes.md#delegation) shows a complete session.

## Greet the caller

The greeting isn't part of `instructions`. To have the agent speak first, send `response.create` with per-response instructions once the session is configured. Baseten Realtime Voice adds the per-response instructions to the session's instructions, so the agent stays in character:

```json theme={"system"}
{
  "type": "response.create",
  "response": {
    "instructions": "Greet the caller: say you're Riley from Northwind Fiber support and ask how you can help. One short sentence."
  }
}
```

## Iterate on a prompt

Read the transcripts of test calls: `conversation.item.input_audio_transcription.completed` carries what the caller said, and `response.output_audio_transcript.done` carries what the agent said. When a call goes wrong, ask a more capable text model to review the prompt against the transcript:

```text theme={"system"}
Review this system prompt for a voice agent. List every ambiguity, missing definition,
conflicting rule, and unstated assumption that could explain the failure below.
Then give a revised prompt that fixes only those issues. Don't add tools or facts
the prompt doesn't already have.

Prompt:
{CURRENT_PROMPT}

Failure:
{WHAT_THE_AGENT_DID_AND_WHAT_IT_SHOULD_HAVE_DONE}
```

Test the revision on the call that failed and on a few that worked, since a fix for one case can break another.

## Starter template

```text theme={"system"}
## Role
You are [name], a [disposition] [role] for [company], on a live phone call.

## Objective
[The outcome you drive toward], or [what you do when you can't].

## Conversation flow
[How a call proceeds, naming only the tools in this session.]

## Facts
- [Price, hours, or policy, in the words to use.]

## Guardrails and escalation
- Stay on [company] topics.
- Never invent [account details, prices]. If it isn't in a tool result or the facts, say you don't know.
- If the caller asks for a person, say "[line]" and call [transfer tool].
```
