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

# Fish Audio Quickstart

> Build a Python LiveKit agent with Fish Audio text-to-speech and an Anam avatar, then connect a frontend for your first voice and video conversation.

Build the quickstart with a coding agent

Paste this prompt into your coding agent. It adapts an existing LiveKit project or asks what to build, then waits for you to add your credentials before starting the agent.

Copy prompt

This guide builds the [Fish Audio demo](https://anam.ai/integrations/fishaudio): a Python LiveKit agent that speaks with [Fish Audio](https://fish.audio/?utm_source=anam\&utm_medium=referral) [Drama 3](https://fish.audio/drama-3/?utm_source=anam\&utm_medium=referral) and the Ethan voice and replies with GPT-OSS-120B, all through LiveKit Inference. An interactive Anam avatar speaks the replies in a React frontend. To learn how the pieces connect, see the [Overview](https://anam.ai/docs/integrations/fish-audio/overview.md).

## Prerequisites

* Python 3.10–3.14 and [uv](https://docs.astral.sh/uv/getting-started/installation/).
* The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) v2.19 or later (`brew install livekit-cli` on macOS).
* A [LiveKit Cloud](https://cloud.livekit.io) project with Inference and billing enabled. This example uses LiveKit credentials for STT, LLM, and TTS; it needs no separate provider API keys.
* An Anam API key from [Anam Lab](https://lab.anam.ai/api-keys) and an avatar ID from [Avatars](https://lab.anam.ai/avatars).
* Node.js 24 and pnpm 9.15.9 (the starter's declared package manager) for the React frontend used below.

## Set up the agent

**1. Install compatible packages**

Create a Python project:

```bash theme={"system"}
uv init --python 3.12 fish-audio-anam
cd fish-audio-anam
uv add "livekit-agents[anam,silero]==1.8.12" "python-dotenv==1.2.4"
```

The extras install `livekit-plugins-anam` and `livekit-plugins-silero` at the same version. LiveKit Agents 1.8.9 or later is required for the `fishaudio/drama-3` model. Keep the generated `uv.lock` for reproducible installs. LiveKit Inference provides Fish Audio TTS, so this example does not install the Fish Audio plugin or SDK.

**2. Configure server-side credentials**

Create a [LiveKit Cloud](https://cloud.livekit.io) account and project, then copy the project URL, API key, and API secret from the project's API key settings. Get your Anam API key from [Anam Lab](https://lab.anam.ai/api-keys).

Create `.env.local` in the project root and replace the placeholders:

```bash .env.local theme={"system"}
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret

ANAM_API_KEY=your_anam_api_key
ANAM_AVATAR_ID=your_anam_avatar_id
```

Add `.env.local` to `.gitignore`. Keep API keys and the LiveKit secret in your server environment or deployment secret store. Never put them in browser code or `NEXT_PUBLIC_` variables. The browser receives a room-scoped participant token from the frontend's server route.

`ANAM_AVATAR_ID` selects the face. The Fish Audio voice ID belongs in the LiveKit TTS configuration. `LIVEKIT_URL` must be reachable by Anam's servers; use the Cloud project's `wss://` URL, not a local LiveKit server.

**3. Create the voice and avatar session**

Create `agent.py`:

```python agent.py theme={"system"}
import logging
import os
from pathlib import Path

from dotenv import load_dotenv
from livekit import agents
from livekit.agents import Agent, AgentServer, AgentSession, inference, room_io
from livekit.plugins import anam, silero

load_dotenv(Path(__file__).with_name(".env.local"))

server = AgentServer()
logger = logging.getLogger("fish-audio-agent")


@server.rtc_session(agent_name="fish-audio-agent")
async def entrypoint(ctx: agents.JobContext):
    api_key = os.environ["ANAM_API_KEY"]
    avatar_id = os.environ["ANAM_AVATAR_ID"]

    await ctx.connect()
    visitor = await ctx.wait_for_participant()

    session = AgentSession(
        stt=inference.STT(model="auto", language="en"),
        llm=inference.LLM(model="openai/gpt-oss-120b"),
        tts=inference.TTS(
            model="fishaudio/drama-3",
            voice="536d3a5e000945adb7038665781a4aca",  # Ethan
            language="en",
        ),
        vad=silero.VAD.load(),
    )
    avatar = anam.AvatarSession(
        persona_config=anam.PersonaConfig(
            name="Fish Audio avatar",
            avatarId=avatar_id,
            avatarModel="cara-4.1-express",
        ),
        api_key=api_key,
    )

    try:
        # Route speech through the avatar before the voice session starts.
        await avatar.start(session, room=ctx.room)
        await session.start(
            room=ctx.room,
            agent=Agent(
                instructions=(
                    "You are a helpful voice assistant. Keep replies short "
                    "and conversational. Use plain speech without Markdown."
                ),
            ),
            room_options=room_io.RoomOptions(
                participant_identity=visitor.identity,
                close_on_disconnect=True,
            ),
        )
        await session.say("Hello! What would you like to talk about?")
    except Exception:
        logger.exception("Could not start the Fish Audio avatar conversation")
        session.shutdown(drain=False)
        ctx.shutdown(reason="Conversation startup failed")
        raise


if __name__ == "__main__":
    agents.cli.run_app(server)
```

The Anam plugin forwards the generated speech to Anam and publishes synchronized audio and video back into the same LiveKit room. Start `avatar.start()` before `session.start()` so speech follows that route from the first greeting. `participant_identity` binds microphone input to the visitor, rather than the avatar participant that joins afterward.

`anam.PersonaConfig` here comes from `livekit.plugins.anam` and uses `avatarId` and `avatarModel`. It is a different type from the standalone Anam Python SDK's `PersonaConfig`.

**4. Run the agent**

Download the model assets and start the worker from the project directory:

```bash theme={"system"}
uv run -m livekit.agents download-files
lk agent dev --deployment production agent.py
```

Keep this terminal open. The worker registers with your LiveKit project under the dispatch name `fish-audio-agent` and waits for a room assignment. Registration alone does not start a conversation.

By default, `lk agent dev` registers under a random `dev-` [deployment](https://docs.livekit.io/deploy/agents/deployments/), and the starter frontend below only dispatches to `production`. `--deployment production` lets the frontend reach your local worker. Don't use it in a project where a deployed agent with the same name serves real users; open the Agent Console link that `lk agent dev` prints instead.

## Connect a frontend

Use the React frontend from the [LiveKit quickstart](https://anam.ai/docs/integrations/livekit/quickstart.md#set-up-the-frontend). In a second terminal, outside the Python project:

```bash theme={"system"}
git clone https://github.com/livekit-examples/agent-starter-react.git
cd agent-starter-react
pnpm install --frozen-lockfile
```

Create a separate `.env.local` in the frontend project:

```bash .env.local theme={"system"}
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
AGENT_NAME=fish-audio-agent
```

Use the same LiveKit project as the Python worker. Leave `LIVEKIT_TOKEN_SERVER_ID` unset so the starter uses its included token endpoint. `AGENT_NAME` must match `agent_name` in `agent.py`: this requests the named agent when the visitor joins. Anam credentials stay in the Python project.

```bash theme={"system"}
pnpm dev
```

Open `http://localhost:3000`, start a session, and allow microphone access. You should hear the greeting in Ethan's Fish Audio voice and see the Anam avatar speaking in sync. Ask a short question and check that the reply has both audio and matching mouth movement. Disconnect when finished; the agent session closes when its linked visitor leaves.

The starter includes avatar rendering and a server token route for local development. Before exposing it publicly, add authentication and authorization to token issuance; follow [LiveKit's frontend authentication guidance](https://docs.livekit.io/frontends/build/authentication/).

## Next steps

* [Configuration](https://anam.ai/docs/integrations/fish-audio/configuration.md): change the voice, tune Fish Audio, use your own Fish Audio API key, deploy, and troubleshoot
* [LiveKit configuration](https://anam.ai/docs/integrations/livekit/configuration.md): avatar options, Director Notes, and advanced examples
* [Avatar gallery](https://anam.ai/docs/personas/avatars/gallery.md): browse stock avatars


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.