AniwaffleDocsHomeContact our team
Developer preview. Public API access is not open yet. Contact our team to discuss integration.

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.

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

The Character Card V3 defines identity, personality, scenario, dialogue, greetings, world book and instructions.

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. 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. Switch to the right product

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

  3. Open Agents

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

The Agents page lists every Agent with its status (Published v2 for a published Agent, Draft otherwise), Avatar and voice, and last update. A Draft changes label indicates a newer unpublished revision. 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. Select New agent

    Open the menu at the top right and choose Blank agent. The full-page editor opens on Character. Enter a name and complete the other sections before testing.

  2. Name the Agent

    Enter a character name such as Customer Support Guide. In Settings, you can set a stable lowercase slug such as support-guide for API lookup. If left blank when creating an Agent, the slug is generated from the character name.

  3. Select Create agent

    The header button saves the draft without publishing and opens its saved editor. The header shows the current draft revision; the Agent appears in the list with a Draft badge.

Migrating an existing Live setup

Choose New agent → From live configuration. It opens a new draft prefilled with your current Live conversation settings (speech recognition, model, instructions, voice). Rename the prefilled live-config-draft slug before saving.

Improve an existing Agent

Compare prompt changes on old Sessions

When you want to improve an Agent’s replies using real conversations, follow Improve an Agent’s prompt with Codex. It walks through installing the Waffle CLI and optional skill, signing in, choosing an Agent, editing prompt files, replaying old Sessions, reading original/base/candidate replies with translations, and saving only the chosen draft. You can do the same loop manually without Codex.

Configuration reference

Configure every section

The editor has five sections: Character, Appearance & voice, Runtime, Workflow, and Settings. Character opens by default. Opening dialogue, world book, advanced instructions, and metadata expand on demand. All sections edit the same draft; switching sections preserves unsaved edits. Leaving the editor with unsaved changes asks whether to discard them. Apply or discard complete-card JSON edits before saving or publishing.

SectionFieldHow to use it
SettingsSlugStable identifier used for API lookup. Generated from the character name if blank when creating an Agent; required on existing Agents.
CharacterCharacter name / NicknameName shown in selectors; nickname replaces {{char}} when provided.
Appearance & voiceAvatarThe character shown in Live and delivered to Avatar-capable clients: Violet, Ruby, Lumi, or Komano.
Appearance & voiceGenerate avatar motionExperimental checkbox, off by default for new and existing Agents. Generates body and head movement while the Agent listens as well as while it speaks, and mouth movement synchronized with speech; replaces the avatar's audio-driven lip sync and emotion cues. Adds a delay before speech starts and requires a supported client. Publish changes to apply them only to this Agent's new sessions.
CharacterDescription / Personality / ScenarioCharacter background, temperament and the conversation setting.
RuntimeLLM provider / LLM modelThe model that plans each reply. Providers: Anthropic, xAI · Grok, or Google · Gemini, plus the model id.
Runtime → AdvancedGemini thinking levelAppears only when the provider is Google · Gemini. Minimal, Low, Medium, or High; higher levels can help difficult turns but add latency.
RuntimeEnable managed web searchCheckbox, on by default. Lets the Agent search the web when a reply needs current public information.
Runtime → Reply decisionsEvaluator and custom questionsConfigure application state and workflow decisions. Parallel evaluation is the default; see reply decisions.
RuntimeEnable conversation memoryCheckbox, off by default. Carries user context across sessions and across voice and typed turns; API callers must then supply a stable end_user_id per user. Turning it on inserts the Recalled memory template, which publishing requires.
WorkflowStates and connectionsInherit the Agent configuration and override selected properties by conversation state. Write a condition for each directed connection, including a return path. See state workflows.
RuntimeSpeech recognitionSoniox or Deepgram. Test with the accents and acoustic conditions your users actually have.
Runtime → AdvancedTurn detectionProvider default uses STT endpointing without an additional worker wait. Speech recognition endpointing starts at 0 ms minimum / 3000 ms maximum; LiveKit native audio (local v1-mini) starts at 600 / 1000 ms. Both waits remain adjustable. Applies to automatic managed voice sessions; push-to-talk remains manual. Publish to apply the setting to new sessions. Short waits can split an utterance before its final transcript arrives, so test with real speech before enabling broadly.
Runtime → Advanced → OpenAI RealtimeOpenAI realtime model / voiceDefaults used only when a Live session runs on the OpenAI Realtime backend instead of the standard pipeline.
Appearance & voiceTTS variantOne specific voice, provider, and model route. The route determines availability and capabilities such as emotion tags.
Runtime → AdvancedAllow silent responsesCheckbox, off by default. Lets the Agent skip a reply during live conversations, for example for a repeated message. Publish changes to apply them to new live sessions.
CharacterSystem prompt / Post-history instructionsCharacter instructions before and after the conversation history.
CharacterExample dialogue / First message / Alternate greetingsDialogue examples and openings. Examples are never saved as real messages.
CharacterWorld bookKeyword or RE2 regex entries, enabled state, scan depth, priority, order, recursion and token budget.
CharacterCreator and metadataCreator notes, tags, assets, extensions, version and complete V3 JSON. Metadata is not character instruction text.
A single character card

Choose New agent → From character card, then Import card, to create a new Agent. For an existing Agent, open Edit → Character → Replace from card. Import replaces the entire character; it preserves the existing Agent ID, slug, models, voice, Avatar and tools. Save and publish normally. Restore uses the existing revision history.

V2 and V3 JSON and standard PNG cards are supported (10 MB file, 2 MB normalized card JSON including embedded images). Export produces V3 JSON. Unknown fields and extensions survive editing and export. PNG default images are embedded in the exported JSON. Asset references are preserved without replacing the 3D Avatar or voice; third-party scripts are not executed. Choose Use as first message to promote an alternate greeting for new conversations. Lorebook decorators are preserved but their rules are not executed. CharX and group chat are not supported.

Voice

Voice providers and billing

Agents can speak with Waffle voices and, when enabled for your workspace, with Fish Audio and ElevenLabs voices. Waffle Live speech requires region: "jp"; unsupported regions are rejected before the session starts. Pick the voice, provider, and model under Appearance & voice → TTS variant. A voice cloned from your recordings is copied to the selected provider when you save the Agent; publishing and starting speech wait until that copy is ready, without saving again.

How speech is billed in Agents

Agent Live connections cost 15 credits per minute, plus LLM, ASR and TTS supplier costs without markup. Avatar adds its own 100 credits per minute duration fee. Workspace Owners and Admins can configure BYOK for exact provider/model IDs, including JEV and other decision models: matching calls record usage but deduct no model credits. Connection and Avatar fees still apply. These rules also apply to text Agents, translation, summaries, review, replay/tests, speech annotations, and standalone speech. Owners/Admins select the LLM for each purpose in Workspace Settings; an unset override keeps the Agent or platform default. Key and model changes apply to new calls; active contexts retain their snapshot. Model call audit records show usage, key references, outcome and deductions, including BYOK calls at zero credits. Replaying saved results makes no new model call.

In Workspace Settings → Provider keys, OpenAI and xAI LLM keys can also specify an optional Base URL for a compatible gateway. Enter the API base (for example, https://api.example.com/v1), the gateway's key, and the exact model IDs used by your Agents or Workspace overrides. Leave the URL blank to use the official provider. Custom endpoints must be public HTTPS addresses on the standard port, without embedded credentials, query parameters or fragments. They must support the Responses API, including streaming, usage and any tools your Agent uses; OpenAI decision models additionally require the Decisions API. Failed gateway calls never retry with a platform key. The endpoint is saved with the key version and appears in the model call audit.

ProviderModelsEmotion and delivery cues
Waffle Stereowaffle:0.1-stereo-betaNative stereo with paired position, emotion and delivery tags. Availability depends on the environment’s voice catalog.
Wafflewaffle:0.1-1111-betaFixed paired emotion/delivery tags and sound events; see the tag guide.
Fish Audios2-pro, s2.1-pro, s2.1-pro-freeNatural-language [directions] such as calm, empathetic, whispering, laughing. Results vary; see Fish Audio models.
Fish Audiodrama-3[directions] and [sounds], plus paired word-level tags such as <soft>slow breath</soft> (whisper, emphasis, soft, fast, slow, stress, forceful). See Drama 3.
ElevenLabseleven_v3, eleven_v4, eleven_v4_turbo, eleven_v3_conversationalAudio Tags such as curious, whispers, laughs, sighs. See the ElevenLabs prompting guide.
ElevenLabseleven_multilingual_v2, eleven_flash_v2_5, eleven_flash_v2No inline emotion tags; cues are removed. eleven_flash_v2 is English only.

Models from the same provider reuse one cloned or imported voice. Send only the bare tag value; Narya adds each provider's syntax. Do not mix Drama's paired tags with S2 or ElevenLabs, or Waffle spans such as <happy> with Drama.

Third-party voices

Import a voice from a provider

When a third-party provider is enabled, an Owner, Admin, or Builder can import a voice already authorized in the workspace or available in the public voice library, without new recordings.

  1. Open Create voice → Import existing

    On the Voices page, select Create voice, then Import existing.

  2. Choose the provider account and catalog

    Pick ElevenLabs or Fish Audio, then Workspace voices (voices already authorized in this workspace) or Public voice library.

  3. Search and preview

    Type a name and select Search. Public library results offer previews when available; selecting a result fills the Name field.

  4. Confirm permission and import

    Confirm the permission checkbox and select Import voice. Import uses the provider's default model; no samples or cloning are required. Choose the model in the Agent, or change Default provider and Default model on the voice detail page for API callers.

Reply behavior

Decide state independently of spoken delivery

Open Runtime → Reply decisions to configure application state and workflow transitions. The speaking model generates dialogue and provider-native voice tags inline. TTS receives that annotated text; the server removes tags from streaming captions, final transcript messages and application callbacks before publishing them. Existing SDKs receive clean text without an upgrade. No JSON envelope or separate voice-tag classifier is required, and speech does not wait for label evaluation.

voiceTagWaitMs remains readable for historical compatibility but no longer controls live speech. Retired mode: "json" values normalize to parallel; historical diagnostics retain their original mode.

Parallel evaluation can use one of these choices:

EvaluatorConfiguration
LLMBy default, makes a separate minimal-thinking call to the current state's speaking model. Select an explicit provider and model together to use a different evaluator. It can derive an application state JSON object from application instructions.
TypeSafe JevSelect jev-1.14.0 or jev-1.13.0. The runtime needs TYPESAFE_API_KEY. This is a fixed-choice evaluator, not a speaking model.
OpenAI DecisionsUses gpt-6-luna through the Decisions API, with runtime OPENAI_API_KEY. It is also a fixed-choice evaluator; this setting does not replace the speaking model.

Jev and OpenAI Decisions use minProbability (0.85 by default, range 0–1) for each selected choice. A value below the threshold is undecided: it does not trigger that state change. This starting threshold is not a measured accuracy guarantee. Test actual languages, ambiguous conditions, and return paths; TypeSafe's model guidance specifically calls for testing non-English content.

For custom application state with either dedicated evaluator, define Custom questions with a field name, instructions, and a finite set of choices. They cannot infer an arbitrary state object from free-form instructions alone. Up to 16 questions are supported, each with 2–64 choices. A regular LLM can use these questions too, or derive a JSON state object from the application's existing instructions. Keep credentials in the runtime environment, never in an Agent revision or browser setting.

A workflow transition affects a later input only. The trigger reply keeps its original model and state; a new input arriving before a decision is ready does not wait for the transition. Failed or invalid decisions keep the current state. Application state output still needs the application's own validation and stale-input checks; see application sessions.

Decision evaluation overlaps generation. Do not add its duration to speech latency. See CLI configuration examples.

Prompt ownership

Select every instruction explicitly

The platform compiles authored instructions and selected templates. It does not append sentence limits, tag bans, tool policies, memory wrappers, state policies, clocks, application-event descriptions, or model-control text such as /no_think.

In Character → Advanced instructions & card metadata, use Insert an optional template. The database catalog supplies each template's body and version. Selection copies those bodies into the Character's aniwaffle_prompt_templates extension and inserts its marker, such as {{tts_voice_tags}}. Save creates an immutable Agent revision; later catalog changes cannot change a published Agent. Edit the copied bodies or remove the marker to change behavior. A marker without a saved definition has no platform-supplied fallback.

TemplateOptional content
tts_voice_tagsProvider/model-specific inline directions. Eleven v3/v4 and Fish accept open directions; Waffle uses its supported controls. Text-only replies omit cues.
reply_style, speech_outputReply length/style and spoken-only formatting.
session_contextSupplied user name, current time and timezone.
tool_instructions, tool_preambleEnabled-tool guidance and announcements.
workflow_stateCurrent state and the author's node instructions.
memoryRecalled memories, when Memory is enabled. Required by Memory: publishing fails with memory_prompt_slot_required when the prompt, or any workflow state that overrides it, does not render this template.
history_summarySummarized older application history. Without a consuming template, history stays verbatim.
application_eventAn application-requested reply without new user input.

Migrated Agents also expose conversation and examples prompt layouts. These saved sources control where each selected template appears. {{character_instructions}} inserts the Agent-owned prompt. Both Live and SDK use this same layout. Rendering processes authored sources once; user messages, memories, summaries, names, and tool results cannot introduce new template expansions. Actual conversation messages and tool schemas/results remain protocol data. Independent decision, summary and review models still have their own task instructions; these are not appended to the speaking model.

Existing Agents are migrated after deployment by apps/web/scripts/migrate-agent-prompt-templates.mjs (dry-run by default, --apply to commit). Migration creates new revisions, preserves unpublished drafts, moves existing publication and Viewer bindings together in one transaction, and leaves historical revisions intact. It preserves prior policies as explicit templates except the retired tag ban and independent tag classifier policy; provider guidance now asks the main model to emit tags directly. New Agents start without selected runtime templates.

Conversation states

Change behavior with conversation states

Open Workflow in the Agent editor and enable it. The first state is the entry state. Add another state, choose the properties it overrides, and connect the states with a natural-language condition. For example, keep a fast everyday model in Main and select a different model in Focus when the user asks for a focused discussion. Add a return connection for “The user asks to return to casual conversation.”

Each state starts from the Agent configuration. An omitted property inherits its current base value; changing a state never rewrites the base character. Returning to a state restores that state's overrides, so values from the state you left do not leak into the next one.

State settingBehavior
Model and thinking levelInherit the Agent model, or select an explicit provider and model together. Each model needs instructions and tests suited to its behavior.
State instructionsAppend instructions for this state to the character instructions.
Character overridesReplace selected name, description, personality, scenario, example dialogue, system prompt, or post-history instructions. Other character fields inherit the base card. Empty text clears an overridden field; the name must remain nonempty.
Web searchInherit, enable, or disable managed web search, subject to the chosen model's support.
Turn detectionInherit or override the existing endpointing mode and delays. This applies to automatic voice turns; push-to-talk remains manual.

The first version supports up to 12 states and 40 directed connections. Every state must be reachable from the entry state, conditions must be nonempty, and a connection must lead to a different state. A return connection is valid. Voice/TTS, ASR provider, Avatar, memory, and connected tools remain Agent-level settings in this version; unknown node properties are rejected.

With the default parallel decision mode, conditions are evaluated in the background, separately from the speaking model's prompt. The turn that triggers a condition keeps its current state and streams that state's reply normally. A ready, valid decision can change the state only at a later turn boundary; it never replaces or interrupts the reply already in progress. If a new turn starts before the decision is ready, that turn continues in the current state without waiting. Failed or invalid decisions leave the current state unchanged.

For example, a request to enter Focus still receives a Main reply. Once the background decision is ready and applied at a turn boundary, a subsequent reply uses Focus's model and overrides with the same conversation history. A request to leave Focus follows the same rule. Conditions are interpreted by a model, so test ambiguous requests, corrections, rapid follow-ups, and exit phrases as well as the happy path. Workflow state is separate from emotion tags. Background evaluation has its own model cost and duration; not waiting for it does not imply zero total latency.

Choose the shared decision mode and evaluator under Runtime → Reply decisions. These are Agent properties, separate from the workflow graph. Graph editing preserves the Agent's decision configuration.

Save a draft, run its matching revision in Agent tests, and check the trigger reply, later state change, every model's wording, and return path before publishing. Live's selector identifies whether you are previewing a draft or a published release. Native and external application / speech_state sessions inherit the published workflow. Application instructions supply current context while the active node supplies its model, character overrides, and appended instructions. Application tools retain their session permissions, including disabled managed web search. Check completed transitions and the model that actually generated each reply separately from background evaluation.

In Live conversation, open Diagnostics to see reply timing, the persisted state for the next reply, and automatic or manual transitions. The panel is hidden by default and refreshes while open. Each transition records its time, source and destination, configured condition, and destination model when known. Up to 200 transitions from the last 7 days are retained; older sessions can have incomplete history. A reply already in progress may still use the previous state and model. This view reads the session's runtime snapshot, not the Agent's current draft.

Diagnostics opens beside the conversation on wide screens. Its Activity section shows the assembled model input, the provider request body and raw model response (including audio tags), Memory recall results and asynchronous write submissions, decision events, tool calls, and turn progress. Expand an event to load and copy its payload; credentials and binary media are omitted, and oversized payloads are marked truncated. A provider request can be incremental and reference an earlier response; the separate Model input record shows the assembled context. Voice requests reuses the TTS source text, submitted text, tags, and timings.

In Sessions, open a conversation and select Diagnostics to inspect the same saved activity, last workflow state, transitions, and voice requests beside the transcript. The panel starts closed. Finished sessions read once when opened; Refresh reloads the saved records. Dashboard Live captures detailed content by default; SDK sessions require the explicit detailedDiagnostics option described in the SDK guide.

Debug records and Live TTS request text are available for 7 days. Expired records stop being returned immediately and background cleanup removes their stored debug data. Conversation messages, actual long-term memory, recordings, and billing records keep their existing retention. Recording debug data adds no model call and never waits for debug database writes before replying. Debug lists show at most the latest 200 records; a missing record is not proof that an operation did not run.

The workflow CLI commands expose the same nodes, connections, inheritance, validation, and draft revisions.

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.

Character description
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.
System prompt
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.

Want to test the same questions after each edit? Follow the illustrated Agent test scripts walkthrough. It shows how to import examples, save a script, run a saved draft, and keep each version's results. To resume a prepared exchange instead, see Start a chat from an example.

  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. Check the toolbar before speaking

    The Agent selector shows exactly what will run, for example Customer Support Guide · Not published · Draft or Customer Support Guide · Published v2. 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. 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. 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. 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. 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 character card for this session only. The button label changes to Overrides (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.
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.
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 select Settings, then expand Revision history. 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. Create a workspace API key

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

  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. 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, documents, or Google Calendar is enabled.

  4. Connect from the browser

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

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 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.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.

The unified-layout migration is apps/web/scripts/migrate-unified-conversation-prompt.mjs (dry-run by default). It preserves selected template bodies, merges template markers once, and blocks ambiguous literal application policies for author review. Applying it creates revisions/publications and updates Viewer bindings transactionally; it never edits historical snapshots.

Contact our team

Tell us about your character and what you’d like to build.