Youragent has a voice.Now give it a face.

# Add an Anam avatar to a LiveKit voice agent

Add a real-time Anam avatar to an existing LiveKit Agents app or create a new one. The plugin consumes the agent's generated audio and publishes synchronized avatar video and audio into the room. Preserve existing STT, LLM, TTS, tools, system prompts and business logic.

Before coding, read https://anam.ai/docs/integrations/livekit/quickstart and https://docs.livekit.io/agents/models/avatar/plugins/anam/. Use https://anam.ai/docs/llms.txt to find further Anam docs as needed. Check the installed SDK's types/source when docs disagree. The reference snippets below are entrypoint fragments, not complete apps. If network access is unavailable, inspect local package definitions and state what remains unverified; do not claim the inlined examples are sufficient for every version.

## Step 0 — existing app or fresh project

Inspect the repository, runtime, package manager, lockfile and existing agent before editing:

- **Python** — `pyproject.toml` / `requirements.txt`, a `livekit-agents` dependency, agent code in `.py` files.
- **Node.js** — `package.json` with `@livekit/agents`, agent code in `.ts` / `.js` files.

If multiple agents are present, use the requested target or ask which one to extend. Add compatible dependencies using the existing package manager; do not upgrade unrelated packages.

If no LiveKit agent exists, choose Python or Node.js from the user's request and project conventions. Follow https://docs.livekit.io/agents/start/voice-ai/ to scaffold the matching starter without overwriting existing files. Configure server-side LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET and any selected provider credentials. Include agent startup/dispatch, a room-token endpoint where required, and a frontend that subscribes to and renders the avatar video track. Use current compatible stable package versions, record them in the lockfile, and provide exact local run commands. Ask only for choices that cannot be inferred safely.

## Environment

```bash
ANAM_API_KEY=your-anam-api-key   # the user pastes their key into .env themselves — it is NOT in this prompt, and if they pasted a key into this chat, tell them to put it in .env and rotate it. Never ask for the key in chat; never put it in a client bundle
ANAM_API_URL=https://api.anam.ai   # optional plugin endpoint override; this is the default
ANAM_AVATAR_ID=cf437b5e-5bcb-481a-937f-b4f16560a152   # "Olivia" — browse more at https://anam.ai/docs/personas/avatars/gallery
```

The plugin listens to the audio your agent sends to users and publishes a synchronized avatar video as a separate room track — it handles the audio routing itself; do not pipe TTS audio manually.

Both runtimes start the avatar BEFORE the agent session. Starting it later replaces the session's existing audio output.

---

## Python

Dependency example (adapt to the project's package manager and compatible versions):

```bash
pip install livekit-agents livekit-plugins-anam
```

In the agent entrypoint, start the avatar session BEFORE starting the AgentSession, so the avatar is ready the moment the agent first speaks:

```python
import logging
import os
from livekit.plugins import anam

avatar_id = os.getenv("ANAM_AVATAR_ID")
if avatar_id:
    avatar = anam.AvatarSession(
        persona_config=anam.PersonaConfig(
            name="Olivia",
            avatarId=avatar_id,
            avatarModel="cara-4.1-express",
        ),
        api_key=os.environ["ANAM_API_KEY"],
    )
    await avatar.start(session, room=ctx.room)
else:
    logging.getLogger(__name__).warning(
        "ANAM_AVATAR_ID is not set — continuing voice-only"
    )

await session.start(
    agent=agent,
    room=ctx.room,
)
```

---

## Node.js

Dependency example (adapt to the project's package manager and compatible versions):

```bash
pnpm add @livekit/agents-plugin-anam
```

In the agent entrypoint, start the avatar session BEFORE `session.start()`:

```ts
import * as anam from '@livekit/agents-plugin-anam';

const avatarId = process.env.ANAM_AVATAR_ID;
if (!avatarId) {
  console.warn('ANAM_AVATAR_ID is not set — avatar session will not start');
}

if (avatarId) {
  const avatarSession = new anam.AvatarSession({
    personaConfig: {
      name: 'Olivia',
      avatarId,
      avatarModel: "cara-4.1-express",
    },
    apiUrl: process.env.ANAM_API_URL,
  });
  await avatarSession.start(session, ctx.room);
}

await session.start({ agent, room: ctx.room });
```

---

## Rules

ALWAYS:

- Set the Anam avatar model to "cara-4.1-express" in every avatar configuration.
- Keep the existing STT / LLM / TTS pipeline untouched — Anam replaces nothing in it.
- Start the avatar before `session.start()` in both runtimes.
- Read `ANAM_API_KEY` from the environment on the server.
- Preserve the agent's domain knowledge, business logic and system prompt unless changes are requested or necessary for this integration.

NEVER:

- Configure a voice, LLM or system prompt on the Anam side — those belong to the LiveKit agent. Use only avatar options supported by the installed runtime; the minimal examples above are not the complete `PersonaConfig` / `personaConfig` schema.
- Pipe TTS audio to the avatar manually — the plugin intercepts the room audio itself.
- Hardcode the API key or import it anywhere that ships to a browser.

## Optional prompt and expression changes

Adding an avatar does not require rewriting the existing system prompt. For a new agent, or if the user requests prompt improvements, consult https://anam.ai/docs/personas/llms/prompting-guide. Preserve domain instructions and configured tools; do not invent tools or require a particular heading structure.

For Cara-4.1 Express expressions, check https://docs.livekit.io/agents/models/avatar/plugins/anam/ and https://anam.ai/docs/personas/director-notes against the installed plugin. Current Python supports baseline Director Notes through `anam.DirectorNotes` in `PersonaConfig.directorNotes`; current Node does not expose that field. Both support `avatarModel`. Do not put inline expression tags into the LiveKit agent's output unless the integration documents and implements their forwarding to Anam; an audio-only path does not establish cue support.

Do not create or overwrite persistent agent-rules files as part of adding the avatar unless the user asks.

## Verify before you declare this done

1. The avatar joins the room as a separate participant and publishes a video track.
2. The avatar's lips sync to the agent's spoken replies, with no doubled audio.
3. With `ANAM_AVATAR_ID` unset the agent still runs (voice-only) and logs a clear warning.
4. `ANAM_API_KEY` appears only in server-side environment config.
5. Existing agent behavior and tools still work; the receiving client renders the avatar, interruptions work, and disconnects clean up sessions/tracks.
6. For a new project, the documented commands start the backend and frontend with placeholder-only environment instructions. If credentials or live sessions are unavailable, state which checks could not run.

## After setup

Swap the face anytime by changing `ANAM_AVATAR_ID` — no code changes. Create a custom avatar from a single photo at https://anam.ai/docs/personas/avatars/custom-avatars. For screen-aware agents (vision), see https://anam.ai/cookbook/gemini-vision-with-anam-livekit.

## Reference

- LiveKit quickstart: https://anam.ai/docs/integrations/livekit/quickstart
- Current partner plugin API: https://docs.livekit.io/agents/models/avatar/plugins/anam/
- Fresh-project starter: https://docs.livekit.io/agents/start/voice-ai/
- Prompting guide: https://anam.ai/docs/personas/llms/prompting-guide
- Node cookbook: https://anam.ai/cookbook/getting-started-with-livekit
- Python cookbook: https://anam.ai/cookbook/gemini-vision-with-anam-livekit
- Machine-readable docs index: https://anam.ai/docs/llms.txt

## If anything is unclear

If an API, method, parameter or config field is not shown in the docs or installed SDK, do not invent it. Report source/version conflicts and any unresolved setup requirements. Summarize changed files, required environment variables, run commands and verification results.