Back to Details

liveavatar-demo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LiveAvatar Demos

LiveAvatar 演示

Three curated demos, each a real open-source repo. This skill does every mechanical step: clone, install, provision, configure, launch.
精选3个演示项目，均为开源仓库。本技能可完成所有机械步骤：克隆、安装、配置、启动。

What this skill cannot do — say this up front

本技能无法完成的操作——请提前说明

You cannot verify that the avatar talks. Every demo ends at a microphone and a human ear. Do not claim success you can't observe, and do not stall waiting for something you can't reach. Name these moments as you hit them:
MomentWhy it's human-only
Supplying API keysCannot be fetched or guessed
Demo 1: 
npm run setup
prompts		Interactive 
readline
. See the reference — running it wrong orphans a context in the user's account
Demo 1: fill name + work email, click Chat with WayneThe submit button is disabled until both fields are filled
Demos 2/3: grant browser mic permission, then speakNo mic, no conversation
Confirming the avatar spoke and lip-syncedAudio + video, in a human's browser
Vercel login / deploy (demo 1, Full level only)Interactive auth
Everything else is yours. Do it without narrating each command.
无法验证虚拟人是否发声。每个演示的最终环节都需要麦克风和人耳的参与。请勿做出无法验证的成功承诺，也不要因无法监测的环节而停滞。遇到以下环节时请明确告知用户：
环节需人工操作的原因
提供API密钥无法获取或猜测密钥
演示1：
npm run setup
交互提示		交互式
readline
流程。参考文档显示：错误运行会导致用户账户中遗留无效上下文
演示1：填写姓名+工作邮箱，点击Chat with Wayne提交按钮需填写完两个字段后才会启用
演示2/3：授予浏览器麦克风权限并讲话无麦克风则无法进行对话
确认虚拟人发声并完成唇形同步需要人类在浏览器中查看音频和视频
Vercel登录/部署（仅演示1的完整版本）交互式身份验证
其余所有操作均由本技能完成，无需逐一说明每个命令。

Step 1: Get the LiveAvatar API key — before anything else

步骤1：获取LiveAvatar API密钥——优先完成

All three demos need it, and having it early removes most branching. Ask for it now, in your first message, alongside the catalog:
Grab an API key from https://app.liveavatar.com → Settings → API keys and paste it here. I'll take it from there.
Do not proceed past Step 3 without it. You may clone and install while waiting, so the user is one paste away from a running demo — say that's what you're doing.
Never write a placeholder or fake value into an env file. 
setup.mjs
and both Python entrypoints treat whatever is in the file as authoritative, and a bogus key produces a 401 that looks like an account problem.
三个演示均需该密钥，提前获取可减少后续分支流程。请在第一条消息中，结合演示目录向用户索要密钥：
请从https://app.liveavatar.com → 设置 → API密钥页面获取API密钥并粘贴在此处，我将继续后续操作。
未获取该密钥前，请勿进入步骤3。可在等待用户提供密钥的同时完成克隆和安装操作，这样用户粘贴密钥后即可快速启动演示——请告知用户你正在进行这些准备工作。
切勿在环境文件中写入占位符或虚假值。
setup.mjs
及两个Python入口文件会将文件中的内容视为有效配置，无效密钥会返回401错误，看起来像是账户问题。

Step 2: Pick the Demo

步骤2：选择演示项目

Show this table unless the user already named one.
#DemoWhat it doesStackExtra keys needed
1AI Sales AgentAvatar qualifies leads, writes a summary to Notion + Slack on hangupNext.js 15 / TypeScript, Node 22+none for a local run; Anthropic + a public URL for the full sales brain
2LiveKit Agent (LiveAvatar-hosted room)Your own LiveKit STT→LLM→TTS pipeline driving the avatar. LiveAvatar owns the roomPython 3.10+ / LiveKit AgentsLiveKit Cloud key + secret
3BYO LiveKit AgentSame pipeline, avatar joins a room in your LiveKit project. Production-shapedPython 3.10+ / LiveKit AgentsLiveKit Cloud key + secret + URL, 
livekit-cli
Routing: fastest thing that talks → 1. Wants to see a voice pipeline, has LiveKit Cloud → 2. Already runs LiveKit rooms in production → 3. "Just show me anything" → 1.
Demos 2 and 3 are the same repo, two entrypoints. Wanting both means cloning once.
除非用户已指定项目，否则请展示以下表格：
序号演示项目功能说明技术栈所需额外密钥
1AI Sales Agent虚拟助手完成潜客资质审核，通话结束后将总结内容同步至Notion和SlackNext.js 15 / TypeScript, Node 22+本地运行无需额外密钥；完整销售功能需要Anthropic密钥及公网URL
2LiveKit Agent（LiveAvatar托管房间）由自定义LiveKit STT→LLM→TTS流程驱动虚拟人，房间由LiveAvatar托管Python 3.10+ / LiveKit AgentsLiveKit Cloud密钥和密钥密码
3自定义LiveKit Agent（BYO LiveKit Agent）流程与演示2相同，虚拟人加入你的LiveKit项目中的房间，适用于生产环境Python 3.10+ / LiveKit AgentsLiveKit Cloud密钥、密钥密码、URL，以及
livekit-cli
路由规则：最快可运行的发声演示→1。用户希望查看语音流程且拥有LiveKit Cloud→2。用户已在生产环境中运行LiveKit房间→3。用户说“随便展示一个”→1。
演示2和3使用同一仓库的两个入口文件，若用户同时需要两者，只需克隆一次。

Costs — state this once, before launching

费用说明——启动前告知用户一次

  • LiveAvatar sandbox sessions are free and duration-capped at roughly a minute. Demos 2 and 3 default to sandbox; demo 1 uses the shared public demo avatar.
  • Demos 2 and 3 bill STT/LLM/TTS to the user's LiveKit Cloud project — including demo 2, where LiveAvatar owns the room. Room ownership and inference billing are separate. People assume otherwise. Demo 3 also bills RTC minutes.
  • Demo 1 bills Anthropic tokens per turn, and only once the brain is wired.
  • LiveAvatar沙箱会话免费，时长限制约为1分钟。演示2和3默认使用沙箱；演示1使用共享的公开演示虚拟人。
  • 演示2和3的STT/LLM/TTS费用将计入用户的LiveKit Cloud项目——包括演示2中由LiveAvatar托管房间的情况。房间所有权与推理计费是分开的，用户通常会误以为两者绑定。演示3还会产生RTC分钟数费用。
  • 演示1在启用完整销售功能后，将按对话次数消耗Anthropic令牌。

Step 3: Preflight

步骤3：预检

Run only the checks for the chosen demo. Report anything missing with its install command; don't install runtimes without asking.
Demo 1:
bash
node --version                 # need >= 22 (engines.node enforces it)
git --version
lsof -ti tcp:3003              # MUST be empty — see below
Port 3003 is pinned in both 
dev
and 
start
. An occupied port is fatal, not a warning, and there is no auto-increment. If 
lsof
returns a PID, either free it or plan to bypass npm with 
npx next dev --port <free>
— and remember the handoff URL changes with it.
Demos 2 and 3:
bash
git --version
uv --version                   # install: brew install uv
Do not gate on 
python3 --version
. 
uv venv
reads 
requires-python
from 
pyproject.toml
and selects a compatible interpreter itself — a system Python 3.9 is irrelevant. Checking it produces a false negative that aborts a setup which would have worked. If 
uv
is genuinely unavailable, fall back to 
python3.13 -m venv .venv && .venv/bin/pip install -e .
and say you did.
Demo 3 also needs 
lk
: 
brew install livekit-cli
(tap 
livekit/livekit
first if it doesn't resolve), then 
lk cloud auth
— interactive, hand it to the user.
仅针对所选演示项目运行检查。若检测到缺失项，请告知用户安装命令；未经询问请勿自动安装运行时环境。
演示1：
bash
node --version                 # 需要 >= 22（engines.node 已强制要求）
git --version
lsof -ti tcp:3003              # 必须为空——详见下文
端口3003在
dev
和
start
模式下均为固定端口。端口被占用会导致启动失败，而非警告，且无自动递增机制。若
lsof
返回PID，请释放该端口或计划使用
npx next dev --port <可用端口>
绕过npm，并注意交接URL会随端口变化。
演示2和3：
bash
git --version
uv --version                   # 安装命令：brew install uv
无需检查
python3 --version
。
uv venv
会从
pyproject.toml
读取
requires-python
配置并自动选择兼容的解释器——系统中的Python 3.9版本不影响。检查Python版本会产生错误的否定结果，导致原本可成功的安装流程终止。若
uv
确实不可用，可回退至
python3.13 -m venv .venv && .venv/bin/pip install -e .
并告知用户你已采用该方案。
演示3还需要
lk
工具：
brew install livekit-cli
（若无法解析，请先执行
tap livekit/livekit
），然后运行
lk cloud auth
——该步骤为交互式操作，请交给用户完成。

Step 4: Remaining Credentials

步骤4：剩余凭证

Ask for these in one message, after the demo is chosen — not before, since what's required depends on it.
DemoAlso neededSource
1, local runnothing—
1, full sales brain
ANTHROPIC_API_KEY
https://console.anthropic.com
2
LIVEKIT_API_KEY
, 
LIVEKIT_API_SECRET
https://cloud.livekit.io → project → Settings → Keys
3those two plus 
LIVEKIT_URL
(
wss://….livekit.cloud
)		same page
For demo 1, read the Local-vs-Full section of its reference and pick a level before asking — asking for an Anthropic key the local run never uses blocks users who have only a LiveAvatar key.
Avatar ID: never ask. Both repos ship a working sandbox avatar in 
.env.example
. Leave it.
Optional and demo-1-only, skip unless raised: 
NOTION_TOKEN
+ 
NOTION_DATABASE_ID
, 
SLACK_WEBHOOK_URL
.
在用户选择演示项目后，一次性询问所需的额外凭证——不要提前询问，因为不同项目所需凭证不同。
演示项目所需额外凭证获取来源
1（本地运行）无—
1（完整销售功能）
ANTHROPIC_API_KEY
https://console.anthropic.com
2
LIVEKIT_API_KEY
, 
LIVEKIT_API_SECRET
https://cloud.livekit.io → 项目 → 设置 → 密钥
3上述两个密钥 加上 
LIVEKIT_URL
（格式为
wss://….livekit.cloud
）		同一页面
对于演示1，请先阅读参考文档中的“本地运行vs完整功能”部分并选择相应层级再询问凭证——若询问本地运行无需的Anthropic密钥，会阻碍仅持有LiveAvatar密钥的用户。
虚拟人ID：无需询问。两个仓库的
.env.example
文件中均包含可用的沙箱虚拟人ID，请保留该值。
可选且仅适用于演示1的凭证：
NOTION_TOKEN
+ 
NOTION_DATABASE_ID
、
SLACK_WEBHOOK_URL
——除非用户提及，否则无需询问。

Where to clone

克隆路径

Default to 
../liveavatar-demos/<repo-name>
relative to the current directory, and confirm the path before running 
git clone
. Never clone inside the user's project tree — if cwd is their project, go up and out. If the target exists and is non-empty, stop and ask.
默认克隆至当前目录的相对路径
../liveavatar-demos/<仓库名称>
，运行
git clone
前请确认路径。切勿克隆至用户的项目目录内——若当前目录即为用户项目目录，请向上切换至外部目录。若目标路径已存在且非空，请停止操作并询问用户。

Step 5: Set Up and Run

步骤5：配置与运行

Follow the matching reference. It has the exact commands, env layout, ready signal, and failure modes.
DemoReference
1 — AI Sales Agentreferences/sales-agent.md
2 — LiveKit hosted roomreferences/livekit-agent.md
3 — BYO LiveKitreferences/livekit-agent.md (BYO section)
Rules for every demo:
Secrets go in 
.env.local
, never 
.env
, never a committed file. Both repos gitignore 
.env.local
and ship 
.env.example
.
Write keys with an editor tool, not a shell command. Shell history and logs persist. The exception is demo 1's 
setup.mjs
, which reads 
LIVEAVATAR_API_KEY
from the environment — the reference covers that case.
Copying 
.env.example
is not enough. Both 
.env.example
files ship keys with empty values that are not equivalent to unset. The references name each one. Getting this wrong is the single most common way these demos die.
Never activate a venv. 
source .venv/bin/activate
does not persist between your tool calls. Use 
uv run <command>
every time.
Launch long-lived processes in the background and read the log rather than blocking on a foreground process. Interactive setup scripts are the exception — see the reference.
Report the ready signal you actually saw, then stop. Each reference names one. Every ready signal proves the process started, not that the avatar works. Do not extrapolate.
遵循对应参考文档的说明，其中包含确切的命令、环境变量配置、就绪信号及故障排查方式。
演示项目参考文档
1 — AI Sales Agentreferences/sales-agent.md
2 — LiveKit托管房间references/livekit-agent.md
3 — 自定义LiveKitreferences/livekit-agent.md（BYO章节）
所有演示项目的通用规则：
密钥请写入
.env.local
，切勿写入
.env
或已提交的文件。两个仓库均已将
.env.local
加入git忽略列表，并提供了
.env.example
文件。
使用编辑器工具写入密钥，而非Shell命令。Shell历史记录和日志会留存密钥。例外情况：演示1的
setup.mjs
会从环境变量读取
LIVEAVATAR_API_KEY
——参考文档已覆盖该场景。
仅复制
.env.example
文件是不够的。两个
.env.example
文件中的密钥值为空，这与未设置密钥并不等价。参考文档会列出每个需要配置的密钥。这是导致演示失败最常见的原因。
请勿激活虚拟环境。
source .venv/bin/activate
在工具调用之间不会持久生效。请始终使用
uv run <命令>
。
在后台启动长时运行的进程并读取日志，而非阻塞在前台进程。交互式安装脚本除外——请遵循参考文档说明。
报告实际检测到的就绪信号，然后停止操作。每个参考文档都会指定一个就绪信号。就绪信号仅证明进程已启动，不代表虚拟人可正常工作。请勿过度推断。

Step 6: Hand Off

步骤6：交接

Give exactly this, then stop:
  1. What the user must do now, concretely. Demo 1: open http://localhost:3003, fill in a name and work email, click Chat with Wayne. Demos 2/3: a browser tab opened automatically — allow the microphone, then speak.
  2. What you could not verify — that the avatar appears, speaks, and lip-syncs. Ask them to confirm.
  3. One customization pointer. Demo 1: prompt parts in 
    src/lib/ai-sales/brain/prompt-parts/
    . Demos 2/3: 
    instructions=
    in 
    src/agent.py
    .
  4. How to stop, and what's billing. The local dev server costs nothing. The billable thing is the avatar session — it ends when the browser tab closes or the process dies. Say which one applies.
Don't tour the codebase. They'll ask.
请准确告知以下内容，然后停止操作：
  1. 用户当前需完成的具体操作。演示1：打开http://localhost:3003，填写姓名和工作邮箱，点击**Chat with Wayne**。演示2/3：浏览器标签页会自动打开——允许麦克风权限，然后讲话。
  2. 无法验证的内容——虚拟人是否显示、发声并完成唇形同步。请用户确认。
  3. 一个自定义提示。演示1：
    src/lib/ai-sales/brain/prompt-parts/
    目录下的提示语片段。演示2/3：
    src/agent.py
    中的
    instructions=
    配置项。
  4. 停止方式及计费说明。本地开发服务器无费用。产生费用的是虚拟人会话——关闭浏览器标签页或终止进程后会话结束。请说明适用的终止方式。
无需引导用户浏览代码库，用户有需要会自行询问。

When Things Break

故障排查

Each reference has a gotchas section with the specific failure. General triage:
  1. Crash before any network call → an empty-but-present env var. Check 
    LOG_LEVEL
    (demos 2/3) first; it's the most common and its traceback names nothing relevant.
  2. Avatar connects but is silent → missing context (
    opening_text
    ), or an LLM configuration pointed at an unreachable URL. Silent failure, no error thrown.
  3. Crash on the user's first sentence (demos 2/3) → model weights never downloaded.
  4. 401 at session mint → bad or missing 
    LIVEAVATAR_API_KEY
    . This error is clear and quotes the request body; trust it.
  5. Session rejected at mint → 
    max_session_duration
    above the account tier's cap, or a production avatar ID in sandbox mode.
  6. Nothing in the browser → check the browser console before the server log. Usually mic permission.
If the symptom isn't in the reference's table, debug from the log, not the README.
每个参考文档的“注意事项”章节都列出了特定故障的排查方法。通用排查流程：
  1. 网络请求前崩溃 → 存在为空但已设置的环境变量。首先检查
    LOG_LEVEL
    （演示2/3）；这是最常见的情况，且其回溯信息未指向相关问题。
  2. 虚拟人已连接但无声音 → 缺少上下文（
    opening_text
    ），或LLM配置指向不可访问的URL。该故障无错误抛出，表现为静默失败。
  3. 用户首次讲话时崩溃（演示2/3） → 模型权重未下载。
  4. 会话创建时返回401 → 
    LIVEAVATAR_API_KEY
    无效或缺失。该错误信息明确并会引用请求体，请以此为准。
  5. 会话创建时被拒绝 → 
    max_session_duration
    超过账户层级限制，或在沙箱模式下使用生产环境虚拟人ID。
  6. 浏览器无内容显示 → 先检查浏览器控制台，再查看服务器日志。通常是麦克风权限问题。
若症状未出现在参考文档的表格中，请根据日志排查，而非依赖README。

Step 7: Collect Feedback

步骤7：收集反馈

Trigger once the demo is handed off, or if the user abandons after 3+ failed attempts at the same step. If you're blocked on credentials and nothing is running, skip it.
Follow the 
liveavatar-feedback
skill if it's available; if it isn't, skip silently rather than improvising a feedback channel. One line, and don't push if the user ignores it.
在演示交接完成后触发，或用户在同一步骤尝试3次以上失败后触发。若因缺少凭证导致无法运行，请跳过该步骤。
若
liveavatar-feedback
技能可用，请遵循该技能流程；若不可用，请静默跳过，不要自行创建反馈渠道。只需发送一条消息，若用户忽略则无需追问。

What to consult

参考资源

  • references/sales-agent.md — AI Sales Agent: interactive setup script, local vs. deployed, Vercel, env reference
  • references/livekit-agent.md — both LiveKit demos: common setup, hosted flow, BYO flow, worker deploy
  • references/sales-agent.md — AI Sales Agent：交互式安装脚本、本地 vs 部署、Vercel、环境变量参考
  • references/livekit-agent.md — 两个LiveKit演示：通用配置、托管流程、自定义流程、Worker部署