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

# Write spoken instructions

`avatars[].instructions` shapes **how the avatar receives a user's words, replies, and decides what belongs in spoken output**. It applies across turns. Use a [script](/streaming-avatar/interaction/scripted-performances) for one exact line or prepared performance. Default motion is enough to start; tune [speaking motion](/streaming-avatar/character/speaking-motion) or [listening motion](/streaming-avatar/character/listening-motion) only when you need a particular style.

A useful starting structure is **Character → Identity → Personality → Chat Style → Hard Rules**. The first four sections establish a consistent conversational presence. The last holds a few output boundaries that must not drift. Keep the headings if they help you edit; you do not have to fill every section with a long backstory.

## 1. Character: who is the user talking to?

Use a sentence or two to establish the avatar's relationship with the user. Is it someone they can talk to easily, or a guide for a particular subject? That relationship shapes every later reply more than a name or a biography does. The avatar is present on screen, face to face with the user; do not cast it as a voice without a body.

**Too generic:** `You are a helpful AI assistant.`

**More specific:** `You are an on-camera companion who is easy to talk to and pays close attention to the person speaking with you.`

This is only a starting point. Add a distinctive temperament if it matters to your experience, but a long invented past will do less work than a clear relationship.

## 2. Identity: what kind of conversation is this?

The purpose can be simple: talk with the user in a way that feels attentive and unforced. Tell it how to do that: answer a concrete question when asked, stay with a casual topic when the user wants to chat, and meet a difficult feeling before rushing into advice. The same character should be able to answer a question and stay present in a quiet conversation.

**Likely to derail the chat:** `Turn every conversation into advice and end every reply with a question.`

**More natural:** `Follow the user's lead. Answer direct questions plainly. When they want to chat, stay with their topic instead of turning every exchange into advice.`

Not every turn has to advance a task. Do not claim to know live facts or private details about the user that were never supplied.

## 3. Personality: show how it reacts

“Warm”, “smart”, and “playful” do not tell the avatar what to say next. Pick a few moments it will encounter: being corrected, hearing that the user has had a hard day, or sharing a joke. Lightness need not become a joke in every turn; meeting someone's mood does not mean agreeing with everything they say.

**Adjectives alone:** `Be friendly, smart, and empathetic.`

**Behavior you can hear:** `When corrected, own the mistake briefly and answer again. When the user is upset, acknowledge it before offering an idea. Keep humor light and occasional.`

Use apologies and signature phrases sparingly. A clear response to a situation is more useful than a list of lines the avatar repeats on cue.

## 4. Chat Style: write for a real conversation

Set a normal reply length, answer order, when to ask a question, and how to follow the user's language. Give a direct answer to a direct question. In small talk, respond to the thing the user just said. Long lists can look tidy on a page but sound like a speech. Choose the [voice](/streaming-avatar/character/voice) separately; this section controls wording and pace.

**Likely to sound like an article:** `Give a comprehensive, structured answer to every request.`

**Better aloud:** `Match the user's language. Use short, natural sentences. Answer direct questions first; in casual chat, respond to what they just said. Ask a follow-up only when it adds to the conversation.`

Examples should contain only words the user is meant to hear. If Chat Style asks for an action before each line, the model may produce `(smiles) Hello there.` and TTS may read the parenthesized text. Do not teach screenplay formatting here; section 5 sets the final boundary for spoken output.

**Likely to create spoken stage directions:** `Write every reply as a screenplay, with the character's action in parentheses before the line.`

**Write instead:** `Write replies as words the user can hear. Keep actions and emotions out of the reply text.`

## 5. Hard Rules: bound speech and physical requests

Two boundaries matter most here: **the reply contains only spoken words, and the character does not treat ordinary movement as impossible because it is an AI.** Put them at the end of the full `instructions`. Changing the voice or motion prompt cannot remove stage directions or refusals that the dialogue model has already written into its reply.

### 5.1 Keep non-speech out of the reply

First remove screenplay-style requirements and action-bearing examples from Chat Style. Then set a clear output boundary at the end of Hard Rules. If an earlier section says to prefix every line with an action, a late “do not narrate” sentence leaves conflicting instructions. Exclude full-width and half-width parentheses, bracketed emotion tags, emojis, and speaker labels from ordinary speech.

**Use this in Hard Rules:**

```markdown wrap theme={null}
## Spoken Output
Output only the character's spoken words as plain text. Do
not include emojis, parentheses of either width,
square-bracket tags, JSON, Markdown, speaker labels,
character-name prefixes, action narration, stage directions,
self-description, or quotation marks around the reply.
```

If a user asks for a wave, `Sure, hi!` can be the spoken reply. `(waves) Sure, hi!` cannot. This rule governs **what is said aloud**, not how the avatar moves.

### 5.2 Do not teach the character to refuse every action

Start with Character. `You are a text-only AI assistant with no body.` casts the avatar as a bodiless assistant. Then check Hard Rules: `Never move. Politely refuse any request for a physical action.` will make even a wave sound impossible. The problem is the instruction, not a lack of enthusiasm.

**In Character, write:** `You are physically present in the scene and speak with the user face to face.`

**In Hard Rules, set the limit:** `Respond naturally to harmless physical-action requests that fit the visible scene. Do not refuse an in-place gesture by claiming to have no body. Do not claim an unseen object has been picked up or a larger movement completed unless the scene supports it.`

A wave or nod can receive a natural reply. A costume change, object interaction, or larger move needs the right scene and capability. If the words stop refusing but the image does not move, check [speaking motion](/streaming-avatar/character/speaking-motion) and the room to move in the first image. More commands in speaking instructions will not produce movement by themselves.

## 6. A conversational character you can adapt

Here is a conversational character with no name or industry attached. It can stay with everyday chat, answer a real question, and admit a mistake without making a scene. Adapt the response habits to your character and put the result in its `instructions`. See the [Quickstart](/streaming-avatar/get-started/quickstart) for the Create Session request.

```markdown wrap theme={null}
# Character
You are a warm, quick-witted companion on camera.
You speak face to face with the user and listen closely.

# Identity
Follow the user's lead. Answer direct questions plainly.
When they want to chat, stay with their topic instead of
turning every exchange into advice.

# Personality
When the user is upset, acknowledge it before offering an
idea. When corrected, own the mistake briefly, answer
again, and move on. Let humor appear only when it fits.

# Chat Style
Use the language of the user's latest message. Speak in
short, natural sentences. For a direct question, answer
first. In casual chat, respond to what they just said.
Ask a follow-up only when it adds to the conversation.

# Hard Rules
Output only the character's spoken words as plain text. Do
not include emojis, parentheses of either width,
square-bracket tags, JSON, Markdown, speaker labels,
character-name prefixes, action narration, stage directions,
self-description, or quotation marks around the reply.
Respond naturally to harmless physical-action requests that
fit the visible scene. Do not refuse an in-place gesture by
claiming to have no body. Do not claim an unseen object has
been picked up or a larger movement completed unless the
scene supports it. Do not invent facts, shared memories with
the user, or access to private information.
```

Try a few turns in a new session: ordinary small talk, a correction, a question it cannot know the answer to, and a request to wave. If a reply feels out of character, edit the relevant section instead of adding more stock phrases.

## 7. FAQ

### Why does the avatar read stage directions aloud?

Remove screenplay-style directions and examples such as `(smiles) Hello there.` from Chat Style, then add the Hard Rules in 5.1. A “do not narrate” sentence alone leaves mixed signals if the example is still there.

### Why does it refuse every request to move?

Check the identity in Character and any blanket ban in Hard Rules, as shown in 5.2. Try a wave in a new session after editing. If the words are right but the image does not move, check [speaking motion](/streaming-avatar/character/speaking-motion) and the first image.