lampgo-livekit-agent-sdk 0.3.0

Business-facing Lampgo LiveKit Agent SDK.

Lampgo LiveKit Agent SDK

Business-facing SDK for the Lampgo LiveKit RTC + Agent stack.

Full Chinese usage guide in this repository: ../docs/xiaomi-livekit-agent-sdk/usage.md.

It wraps:

• LiveKit token generation with internal RoomAgentDispatch.
• voice_agents[].name -> agent_name mapping.
• FastAPI /rtc/token and /healthz routes.
• Parent process supervision for one HTTP token process plus one Agent Worker process per voice agent.
• LiveKit Agents runtime with Silero VAD, OpenAI-compatible LLM, and Volcengine STT/TTS.

Install

From public PyPI:

pip install lampgo-livekit-agent-sdk

For local development from the repository root:

pip install -e ./xiaomi-livekit-agent-sdk

The Volcengine STT/TTS plugin is bundled in this SDK wheel, so business users do not install livekit-plugins-volcengine separately.

Both local mode (livekit.api_key + livekit.api_secret) and cloud mode (platform.* + agent.registration_token) work on the public PyPI install. For cloud mode on the public livekit-agents, the SDK adds external agent-token support at runtime, so no internal index or patched framework is required.

Single Config File

The SDK uses one YAML file by default: roles.yaml.

The file now describes concrete voice agents. Each voice agent directly configures how it listens (stt), thinks (llm), and speaks (tts):

version: 1

livekit:
  url: ${LIVEKIT_URL}
  api_key: ${LIVEKIT_API_KEY}
  api_secret: ${LIVEKIT_API_SECRET}

token_api:
  shared_secret: ${TOKEN_API_SHARED_SECRET:-}
  ttl_seconds: 600
  min_ttl_seconds: 60
  max_ttl_seconds: 3600

agent:
  name_prefix: lampgo-agent

providers:
  openai_internal:
    type: openai
    api_key: ${OPENAI_API_KEY}
    base_url: ${OPENAI_BASE_URL}

  volc_main:
    type: volcengine
    app_id: ${VOLCENGINE_APP_ID}
    access_token: ${VOLCENGINE_ACCESS_TOKEN}

defaults:
  stt:
    provider: volc_main
    options:
      resource_id: volc.bigasr.sauc.duration
      sample_rate: 16000
      result_type: single

  llm:
    provider: openai_internal
    options:
      model: xiaomi/mimo-v2-flash
      temperature: 0.3
      max_tokens: 512

  tts:
    provider: volc_main
    options:
      cluster: volcano_tts
      voice: BV700_streaming
      sample_rate: 24000
      streaming: true

voice_agents:
  - name: customer-service
    display_name: "小米客服助手"
    llm:
      system_prompt: "你是小米客服助手，用中文简短回答用户问题，不要使用 Markdown 或表情符号。"

llm.system_prompt is the model system prompt. For longer prompts, use:

voice_agents:
  - name: customer-service
    llm:
      system_prompt_file: ./prompts/customer-service.md

If token_api.shared_secret is set, /rtc/token requires:

Authorization: Bearer <shared bearer secret>

An empty token_api.shared_secret disables token API bearer auth for local/LAN testing. If a token request sends ttl_seconds, the server clamps it to the configured min/max range.

Environment variables are only used when the YAML explicitly references them, for example ${OPENAI_API_KEY} or ${TOKEN_API_SHARED_SECRET:-}.

Voice Agents

The SDK maps each configured voice agent to an internal LiveKit agent_name.

Default generated agent name:

{agent.name_prefix or "lampgo-agent"}-{voice_agent_name_slug}

The public token API never returns agent_name.

Run

lampgo-livekit-agent --config-file roles.yaml --host 0.0.0.0 --port 8080

Equivalent Python entry point:

from lampgo_livekit_agent import LiveKitAgentConfig, start_service

start_service(config=LiveKitAgentConfig.from_env(config_file="roles.yaml"))

Token API

For compatibility, the request field is still named role; it selects voice_agents[].name.

Request:

curl -X POST http://127.0.0.1:8080/rtc/token \
  -H 'Content-Type: application/json' \
  -d '{
    "room_name": "room-001",
    "user_identity": "user-001",
    "role": "customer-service",
    "metadata": {"tenant_id": "business-a"}
  }'

The new voice_agent field is also accepted:

{
  "room_name": "room-001",
  "user_identity": "user-001",
  "voice_agent": "customer-service"
}

Response:

{
  "token": "...",
  "serverUrl": "ws://192.168.31.116:7880",
  "roomName": "room-001",
  "identity": "user-001",
  "role": "customer-service"
}

The JWT contains:

RoomConfiguration(
    agents=[RoomAgentDispatch(agent_name="<internal voice agent agent_name>")]
)

FastAPI Integration

For an existing business FastAPI application:

from fastapi import FastAPI
from lampgo_livekit_agent import LiveKitAgentConfig
from lampgo_livekit_agent.fastapi import mount_livekit_routes

app = FastAPI()
config = LiveKitAgentConfig.from_env(config_file="roles.yaml")

mount_livekit_routes(app, config=config)

Business services remain responsible for user authentication and room/tenant authorization.