Youragent has a voice.Now give it a face.

# Add Anam to an existing or new Cartesia app

Inspect this repository before changing code: identify its framework/runtime, package manager, lockfile, agent entrypoint and private server configuration. If a Cartesia 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://docs.cartesia.ai/integrations/community/anam-cartesia 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: Anam runs the interactive avatar session and WebRTC stream while a saved Cartesia Sonic voice provides the speech output through the Anam voice ID.

Integration-specific setup:

- First distinguish hosted Anam conversation + Cartesia voice from an existing Cartesia-powered framework pipeline. The reference snippets below implement the hosted path, not an adapter for an arbitrary existing agent.
- For the hosted path, follow https://docs.cartesia.ai/integrations/community/anam-cartesia. A new project needs a private backend token route, a frontend with @anam-ai/js-sdk, and a video element. Keep the desired system prompt/behavior in server configuration. Use the Anam voice ID of a saved Cartesia voice, not the raw Cartesia provider ID; this path needs no separate Cartesia API key.
- If the app already uses LiveKit, Pipecat or another supported framework, use its documented Anam integration while retaining Cartesia TTS. For a custom audio pipeline, consult https://anam.ai/docs/javascript-sdk/examples/custom-tts and verify the existing provider's audio format, sequencing and interruption handling. Do not silently replace an existing agent with a hosted Anam LLM.
- Keep token creation server-side; return only the session token to the browser and call stopStreaming on stop/unmount.

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: use the Anam voice ID for a saved Cartesia voice
// Inside POST /api/anam-session; IDs and systemPrompt come from server config.
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: {
      name: "Cartesia voice avatar",
      avatarModel: "cara-4.1-express",
      avatarId,
      voiceId,
      llmId,
      systemPrompt,
      voiceGenerationOptions: {
        speed: 1,
        volume: 1,
        emotion: "content",
      },
    },
  }),
});
if (!response.ok) throw new Error("Could not create Anam session");
const { sessionToken } = await response.json();
// Return { sessionToken } as JSON from your /api/anam-session route.
```

## Client-side

```javascript
// Browser: never expose the private Anam API key
import { createClient } from "@anam-ai/js-sdk";

const response = await fetch("/api/anam-session", { method: "POST" });
if (!response.ok) throw new Error("Could not start avatar session");
const { sessionToken } = await response.json();
const client = createClient(sessionToken);
// Requires <video id="anam-video" autoplay playsinline></video>.
await client.streamToVideoElement("anam-video");
// On stop/unmount: await client.stopStreaming().
```

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