Skip to main content

Installation

The anam extra installs the Anam avatar plugin. LiveKit Agents 1.8.9 or later is required for fishaudio/drama-3. Add the fishaudio extra only if you use your own Fish Audio API key.

Environment variables

Keep these in server configuration. Never put them in browser code or NEXT_PUBLIC_ variables.

Fish Audio voice

With LiveKit Inference, set the Fish Audio model and voice on inference.TTS:
All three models support en, zh, ja, de, fr, es, ko, ar, ru, nl, it, pl, and pt. Choose a voice from LiveKit’s Fish Audio voice list. Pre-existing custom or community Fish Audio voices aren’t available through Inference; use the plugin for those.

Fish Audio options

Pass Fish Audio parameters through extra_kwargs:
See LiveKit’s Fish Audio model parameters for the full list.

Speech-to-text (STT) and large language model (LLM)

The Quickstart uses inference.STT(model="auto", language="en"), which lets LiveKit Inference pick the best STT model for the language, and inference.LLM(model="openai/gpt-oss-120b"). Any LiveKit Inference STT or LLM model works without extra API keys. When adding the avatar to an existing agent, keep your current STT, LLM, tools, and instructions.

Avatar

Start the avatar before session.start() so all speech goes through Anam from the first greeting. For Director Notes, custom participant identities, and other avatar options, see LiveKit configuration.

Use your own Fish Audio API key

Use the Fish Audio plugin to bill Fish Audio directly or to use custom and community voices:
Add FISH_API_KEY to .env.local, then replace the tts setting:
voice_id is the voice’s reference ID in Fish Audio, not your Anam avatar ID. The plugin also provides Fish Audio speech-to-text:
See Fish Audio’s LiveKit guide and LiveKit’s Fish Audio plugin reference for every option.

Running your agent

lk agent dev (LiveKit CLI v2.19 or later) reloads on file changes. By default it registers under a random dev- deployment, which a frontend dispatching by agent name can’t reach. --deployment production makes your local worker receive those dispatches. In a project where a deployed agent with the same name serves real users, leave the flag off and use the Agent Console link that lk agent dev prints.

Troubleshooting

  • Match AGENT_NAME in the frontend to agent_name in agent.py
  • Use the same LiveKit project for the agent and the frontend
  • Start the local worker with --deployment production; a dev- deployment doesn’t receive dispatches that don’t name one
  • See agent dispatch
  • Check that LiveKit Inference and billing are enabled for your project
  • Confirm that the model and voice are supported by Inference
  • For the plugin, confirm that FISH_API_KEY can access the voice and your Fish Audio account has credit
  • Read the provider error in the agent logs
  • Check ANAM_API_KEY and ANAM_AVATAR_ID
  • Confirm that avatar.start() succeeds before session.start()
  • Make sure your frontend renders the avatar participant’s video track
  • Replace local LiveKit URLs such as ws://localhost:7880 with a publicly reachable endpoint
  • Allow microphone access in the browser
  • Confirm that the visitor publishes audio and that participant_identity points at the visitor, not the avatar
  • Check the agent logs for STT or LLM errors
Last modified on November 17, 2026