Youragent has a voice.Now give it a face.

# Add Anam to an existing or new ElevenLabs app

Inspect this repository before changing code: identify its framework/runtime, package manager, lockfile, agent entrypoint and private server configuration. If a ElevenLabs integration exists, extend it in place. Otherwise, use the documented starter below to create the missing integration without overwriting unrelated files. Infer runtime/provider choices from the user's request and repository; ask only when a material choice cannot be inferred.

Before implementing, fetch https://anam.ai/cookbook/elevenlabs-server-side-agents and the relevant partner setup references below. Use https://anam.ai/docs/llms.txt to discover additional Anam pages as needed. Cross-check installed SDK types/source when live docs disagree with the package version. Do not invent APIs or silently combine incompatible examples. If sources are unavailable or conflict, report what is unverified.

Set the Anam avatar model to "cara-4.1-express" in every configuration. Do not inherit a catalog default or fall back to another model.

The reference architecture is: Your server fetches an ElevenLabs signed WebSocket URL and includes it in the Anam session token. Anam connects directly to the agent; the browser uses only the Anam SDK to receive synchronized audio and video over WebRTC.

Integration-specific setup:

- Use the server-side signed-URL flow in https://anam.ai/cookbook/elevenlabs-server-side-agents. For a new project, use its complete backend/frontend example and create or select an ElevenLabs agent; for an existing app, retain its agent ID and behavior.
- Set the ElevenLabs agent's input audio format to PCM 16000 Hz. Keep ELEVENLABS_API_KEY and ANAM_API_KEY on the server. Validate configured agent/avatar IDs before minting tokens; the example selects Cara-4.1 Express.
- Implement POST /api/anam-session and a browser video element using @anam-ai/js-sdk. Anam owns the media connection for this path; do not run a second ElevenLabs browser audio session alongside it.
- If the existing agent has browser client tools, migrate those handlers using client.registerToolCallHandler before streaming. Preserve names, arguments, results and failure handling. Call returned unregister functions on stop/unmount, then stopStreaming. See https://anam.ai/docs/personas/tools/client-tools.

Requirements:

- Preserve existing providers, tools, system prompts and business logic within the selected documented integration mode. Do not replace the app's architecture or write persistent agent-rules files without a user request.
- Keep the Anam API key in private server-side configuration. Never expose or request it in client code or chat.
- Preserve compatible installed versions and the project's package manager. For a fresh project, resolve current compatible stable releases and record them in the lockfile; do not use remembered versions or force unrelated upgrades.
- Implement the missing imports, environment loading, backend/agent startup, session/room authentication and frontend video rendering required by the chosen starter. The fragments below assume configured providers and entrypoint variables; do not copy them as standalone programs.
- When extending an existing voice app, preserve its voice-only path when Anam is not configured and log a clear warning. Missing optional avatar config must not prevent the ordinary voice session from starting.
- Check types/build and relevant tests. When credentials are available, verify visible synchronized video, one audio output, working tools/interruptions and stop/disconnect cleanup. State explicitly which live checks could not run.
- Summarize changed files, placeholder-only environment variables, exact install/run commands, package versions and verification results. Never fabricate credentials or claim an unrun check passed.

Reference fragments — use only the matching runtime/mode:

## Server-side

```javascript
// Server: keep both API keys private
// Prerequisite: set the ElevenLabs agent's input audio format to PCM 16000 Hz.
// agentId and avatarId must be validated by your /api/anam-session route.
const signedUrlResponse = await fetch(
  `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${encodeURIComponent(agentId)}`,
  { headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY } },
);
if (!signedUrlResponse.ok) throw new Error("Could not authorize ElevenLabs agent");
const { signed_url: signedUrl } = await signedUrlResponse.json();

const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personaConfig: {
      avatarId,
      avatarModel: "cara-4.1-express",
      directorNotes: { presetStyle: "warm", expressivity: 0.5 },
    },
    environment: {
      elevenLabsAgentSettings: {
        signedUrl,
        agentId,
      },
    },
  }),
});
if (!response.ok) throw new Error("Could not create Anam session");
const { sessionToken } = await response.json();
// Return { sessionToken } from your /api/anam-session route.
```

## Client-side

```javascript
// Browser: only the session token is sent to the client
import { createClient } from "@anam-ai/js-sdk";

const sessionResponse = await fetch("/api/anam-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ avatarId, agentId }),
});
if (!sessionResponse.ok) throw new Error("Could not start avatar session");
const session = await sessionResponse.json();
const client = createClient(session.sessionToken);
// If the agent has client tools, register their Anam handlers before streaming.
// Requires <video id="avatar-video" autoplay playsinline></video>.
await client.streamToVideoElement("avatar-video");
// On stop/unmount: unregister tool handlers and await client.stopStreaming().
```

If live docs differ from these fragments, check the installed implementation and explain the version-specific correction before using it.