Narya.aiDocs
Dashboard first

Build your first talking Agent

Create a complete realtime assistant without wiring audio infrastructure yourself. This guide starts from a fresh workspace and ends with a tested, published Agent your application can connect to.

Open the Agents page Open Live conversation

Outcome

What you will build

An Agent is the versioned configuration behind every managed conversation: its identity, instructions, models, speech recognition, voice, and Avatar.

By the end of this guide you will have a support Agent that listens, responds with a voice you chose, animates an Avatar, survives a realistic test conversation, and serves new sessions from a published release.

Behavior

Persona defines who the Agent is. Live conversation instructions define what it must do.

Conversation stack

Choose the language model, speech recognition, web search, and conversation memory.

Voice

Choose the voice, provider, and model route that will speak every reply.

Avatar

Choose the visual character delivered with the published Agent to supported clients.

Before you begin
You need a workspace role of Owner, Admin, or Builder to create and publish Agents. Reviewers can view and run Agents but see no editing controls — if the buttons described below are missing, ask an Owner or Admin to change your role. You also need at least one usable voice; every new workspace already includes ready-made voices, and the Text to Speech guide shows how to add your own.

Navigation

Find the Agents page

All Agent work happens on one Dashboard page. Here is the exact path from signing in.

  1. 1

    Sign in to the Dashboard

    Open the login page and sign in. If you were invited by a teammate, use the account attached to that invitation.
  2. 2

    Switch to the right product

    In the top-left corner of the Dashboard, select the Narya.ai product switcher and choose Agents & Live. The sidebar changes to that product’s pages.
  3. 3

    Open Agents

    Select Agents in the sidebar, or go directly to /operator/agents.

The Agents page lists every Agent with its status (Release v2 · r6 for a published Agent, Draft otherwise), Avatar, models, voice, and last update. If the list is empty you will see “No agents yet. Create your first Agent.”

Dashboard workflow

Create the first draft

A new Agent starts as an unpublished draft, so you can configure and test it before it serves application sessions.

  1. 1

    Select New agent

    The button is at the top right of the Agents page. It opens the Agent editor as a side panel. Only Slug and Display name are required to save, but complete the other sections before testing.
  2. 2

    Name the Agent

    Use a stable lowercase slug such as support-guide — your backend later finds the Agent by this slug — plus a human-readable display name such as Customer Support Guide.
  3. 3

    Select Create agent

    The footer button saves the draft without publishing. You will see the notice “Saved draft support-guide.” and the Agent appears in the list with a Draft badge.
Migrating an existing Live setup
Next to New agent there is a second button, Start from live config. It opens a new draft prefilled with your current Live conversation settings (speech recognition, model, instructions, voice). Rename the prefilledlive-config-draft slug before saving.

Configuration reference

Configure every section

The editor is divided into five sections. These are the exact field names you will see and what each one controls.

SectionFieldHow to use it
IdentitySlugStable identifier used by operators and by your backend to look the Agent up through the API. Lowercase words separated by hyphens. Required.
IdentityDisplay name / DescriptionThe name shown in selectors (required) and a short explanation of the Agent’s job (optional).
IdentityAvatarThe character shown in Live and delivered to Avatar-capable clients: Violet, Ruby, Lumi, or Komano.
PersonaPersonaIdentity, tone, speaking style, and durable behavioral traits. Keep task steps out of this field.
ModelsLLM provider / LLM modelThe model that plans each reply. Providers: Anthropic, xAI · Grok, or Google · Gemini, plus the model id.
ModelsGemini thinking levelAppears only when the provider is Google · Gemini. Minimal, Low, Medium, or High; higher levels can help difficult turns but add latency.
ModelsEnable managed web searchCheckbox, on by default. Lets the Agent search the web when a reply needs current public information.
ModelsEnable conversation memoryCheckbox, off by default. Carries user context across sessions; API callers must then supply a stable end_user_id per user.
ModelsSpeech recognitionSoniox or Deepgram. Test with the accents and acoustic conditions your users actually have.
ModelsOpenAI realtime model / voiceDefaults used only when a Live session runs on the OpenAI Realtime backend instead of the standard pipeline.
VoiceTTS variantOne specific voice, provider, and model route. The route determines availability and capabilities such as emotion tags.
Live conversationLive conversation instructionsThe Agent’s task, turn-by-turn process, boundaries, escalation rules, and end condition. Must not be empty.
Persona and instructions are different
Persona answers “who is speaking and how?” Instructions answer “what must happen in this conversation?” Keeping them separate makes later revisions easier to review.

Working example

Write instructions you can test

Start with a narrow job and explicit boundaries. A voice Agent should know what to ask, what it may claim, and when to stop.

Persona
You are Sage, a calm and practical customer support guide.
You speak in short, natural sentences and ask one question at a time.
You never pretend to have completed an action that you cannot verify.
Live conversation instructions
Your job is to help customers understand their order status and next steps.

Conversation flow:
1. Greet the customer and ask for their order number.
2. Restate the issue in one sentence before proposing a solution.
3. If account data is unavailable, explain what is missing and offer a human handoff.
4. Before ending, ask whether the customer needs help with anything else.

Guardrails:
- Never invent an order status, refund, policy, or action.
- Do not request payment card details or passwords.
- For topics outside customer support, say you cannot help and redirect politely.
Role and scopeState the one outcome this Agent owns. Split unrelated jobs into separate Agents.
Conversation flowWrite the expected sequence, including what information to collect and what to confirm aloud.
GroundingTell the Agent not to invent unavailable facts or claim an action succeeded without evidence.
EscalationExplain when to hand off, refuse, or ask the user to try again.
Voice stylePrefer short sentences and one question at a time; long written answers are hard to follow when spoken.

Acceptance test

Test the complete experience in Live

Live conversation runs the real speech, model, voice, and Avatar path. Do this before touching any code.

  1. 1

    Open the Agent’s actions menu and select Preview in live

    In the Agents list, the ⋯ menu at the end of the row contains Preview in live. It opens Live conversation with this Agent selected. For an unpublished Agent, Live runs the draft; for a published Agent it runs the published release.
  2. 2

    Check the toolbar before speaking

    The Agent selector shows exactly what will run, for example Customer Support Guide · Draft r3 or · Release v2 · r6. Next to it, choose how you want to talk: Push to talk (hold a button while speaking) or Automatic (VAD) (open microphone with voice detection).
  3. 3

    Select Start live session and allow the microphone

    In Push to talk mode, hold Hold to talk · Space while you speak and release to send. You can also type into the message box instead of speaking.
  4. 4

    Run a happy path

    Complete the normal task from greeting through the end condition. Confirm the Agent asks for required information instead of guessing it.
  5. 5

    Probe failure paths

    Interrupt mid-sentence, stay silent, give an unclear answer, request an out-of-scope action, and correct yourself. Watch recovery, not just the ideal reply.
  6. 6

    Check voice and Avatar together

    Listen for pronunciation, pacing, and latency while checking lip sync, expression, idle motion, and gaze.
The first reply follows the Persona and does not start with an unexplained wall of speech.
The Agent stops speaking when interrupted and responds to the corrected intent.
It never invents data, completed actions, policies, or tool results.
It handles silence, recognition errors, and out-of-scope requests without getting stuck.
The selected voice and Avatar remain correct for the entire session.
Session overrides are temporary
The Advanced button in the Live toolbar opens the Agent & session panel, where you can override the model, voice, Avatar, and system prompt for this session only. The button label changes toOverrides (n) while overrides are active; each overridden field shows a Use Agent setting button that reverts it. Select Save as new version to copy the overrides into a new Agent draft revision — this never publishes by itself.

Versioning

Publish a release

Saving and publishing have deliberately different effects. New application sessions always run the published release, never the draft.

ControlWhat it doesUse it when
Create agent / Save draftWrites a new draft revision only. The published release, if any, keeps serving sessions unchanged.You are still configuring or reviewing the change.
Save & publishSaves the draft and creates a new numbered release in one action. You will see “Saved and published support-guide (v2).”The exact configuration has passed the Live test above.
Publish on saveA checkbox next to the save buttons. While ticked, even the plain save button publishes each save.You intentionally want every save to go straight to production.
Actions menu → PublishPublishes the Agent’s current saved draft directly from the list, without opening the editor.The draft was reviewed earlier and needs no further edits.
Published configuration is authoritative
New application sessions supply an agentId and use that Agent’s active release for the prompt, model, voice, and Avatar. Editing a draft never silently changes production, and a session already in progress is not rewritten by a later publish.

Audit trail

Review and restore revisions

The Agent keeps an append-only revision history, so you can improve behavior without losing the last known-good configuration.

Open an Agent in the editor and expand Revision history at the top. Each row shows the revision number, what kind of change it was (created, saved, published, restored), a Release v2 badge when that revision was published, the author, the time, and which fields changed.

Every older revision has a Restore button. Restore copies that revision into a new draft — the editor itself notes: “Restore creates a new draft revision; history is never rewritten.” Test and publish the restored draft like any other change.

Developers

Add the published Agent to your app

Only move into code after the published release passes the Live test. The full credential walkthrough lives in the SDK and API guides; this is the shape of the integration.

  1. 1

    Create a workspace API key

    An Owner or Admin opens Integrations in the Dashboard sidebar (under Config) and creates a key. The authentication guide walks through every click.
  2. 2

    Look the Agent up by slug

    Your backend calls GET /v1/agents with that key and selects this Agent by its slug to get the stable agentId.
  3. 3

    Mint a short-lived session token

    After authenticating your own user, your backend calls POST /v1/agents/{agentId}/session-tokens. The Agent must be published first. Supply a stable end_user_id when conversation memory is enabled.
  4. 4

    Connect from the browser

    Hand the token to @animated-waffle/client or @animated-waffle/react. The published Agent supplies its own runtime settings and Avatar assets.

React app

Use @animated-waffle/react for connection state, audio, transcripts, and the Agent-bound Avatar renderer.

JavaScript app

Use @animated-waffle/client when your application owns its own interface and does not need the React Avatar layer.

Common failures

Troubleshooting

SymptomLikely causeFix
New sessions still use the old behaviorThe change exists only in a draft. The list’s Status column shows Draft, or a Release older than your edit.Open the Agent, run the Live test, then Save & publish. Start a new session after publishing.
The voice or Avatar is wrong in LiveA session override is active — the toolbar button reads Overrides (n) instead of Advanced.Open Agent & session and select Use Agent setting on the overridden fields, or fix the Agent’s Voice and Avatar fields and publish.
Editing or publishing controls are missingYour workspace role is Reviewer. Reviewers can view and run only.Ask an Owner or Admin to assign you the Builder, Admin, or Owner role in Workspace settings.
The API answers 409 “Publish the agent before requesting a session token.”Session tokens are only minted for published Agents.Save & publish the Agent, then retry the token request.
The Agent is missing from GET /v1/agentsThe Agent has no public voice selection, so the API hides it as not ready.Open the Agent, choose a TTS variant in the Voice section, save, and publish.
Memory does not follow the same userThe integration omitted end_user_id or generated a different value per session.Mint every token for that user with the same stable UUID from your own identity system.