livekit/agents

LiveKit Agents – 실시간 AI 음성 에이전트를 위한 Python 프레임워크

개요 – 실시간으로 듣고, 말하고, 볼 수 있는 서버 측 에이전트를 구축할 수 있는 Python SDK입니다. 에이전트는 본질적으로 LiveKit 생태계 내에서 실행되며 WebRTC나 전화를 통해 사용자와 대화하는 LLM 기반 애플리케이션(예: 음성 어시스턴트)입니다.

핵심 개념

• Agent – LLM, 선택적 도구(함수 호출), 일련의 지침을 래핑하는 코드 조각입니다.
• AgentSession – 단일 사용자 또는 방에 대한 미디어 파이프라인(음성 인식, 턴 감지, 음성 합성)과 대화 상태를 관리합니다.
• AgentServer – 세션을 예약하고, 에이전트를 시작하며, LiveKit 방에 연결하는 프로세스입니다.
• Plugins – 주요 모델 제공업체(OpenAI, Deepgram, Cartesia, Google 등)를 위한 어댑터로, 통합된 inference.* API를 제공합니다.

주요 기능

• STT, LLM, TTS 서비스를 자유롭게 조합하여 사용 가능합니다.
• 다수의 사용자를 동시에 처리하기 위한 내장 작업 디스패치 기능이 있습니다.
• 완전한 WebRTC 클라이언트 지원(브라우저, 모바일, Unity 등) 및 LiveKit의 SIP 스택을 통한 전화 통합을 지원합니다.
• 화자가 언제 말을 마쳤는지 판단하는 턴 감지 트랜스포머를 포함합니다.
• 외부 도구 서버를 위한 한 줄 MCP 통합을 지원합니다.
• LLM의 동작을 검증하기 위한 '판정자(judges)'가 포함된 네이티브 테스트 프레임워크를 제공합니다.
• 오픈 소스이며, 자체 호스팅 LiveKit 서버에서 완전히 실행할 수 있습니다.

설치

pip install "livekit-agents[openai,deepgram,cartesia]"

대괄호 안의 옵션은 일반적인 모델 제공업체를 위한 플러그인을 설치합니다.

빠른 시작 (음성 어시스턴트)

from livekit.agents import Agent, AgentServer, AgentSession, JobContext, RunContext, cli, function_tool, inference

@function_tool
async def lookup_weather(context: RunContext, location: str):
    return {"weather": "sunny", "temperature": 70}

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=inference.VAD(),
        stt=inference.STT("deepgram/nova-3", language="multi"),
        llm=inference.LLM("google/gemma-4-31b-it"),
        tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    )
    agent = Agent(instructions="You are a friendly voice assistant.", tools=[lookup_weather])
    await session.start(agent=agent, room=ctx.room)
    await session.generate_reply(instructions="greet the user and ask about their day")

if __name__ == "__main__":
    cli.run_app(server)

프로세스가 LiveKit 방에 참여할 수 있도록 LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET을 설정하세요.

고급 패턴

• 멀티 에이전트 핸드오프 – 한 에이전트가 정보를 수집한 후 대화를 전문 에이전트(예: 스토리텔러)에게 넘깁니다. 핸드오프는 도구 호출에서 새로운 Agent 인스턴스를 반환하여 수행됩니다.
• 테스트 – SDK에는 pytest 호환 테스트 하네스가 포함되어 있어, 특정 사용자 발화가 예상되는 함수 호출이나 LLM 응답을 트리거하는지 검증할 수 있습니다.
• MCP 도구 – LiveKit Docs MCP 서버에 연결하여 에이전트가 최신 문서나 코드 검색을 쿼리할 수 있도록 합니다.

실행 및 개발

모드	명령어	내용
콘솔 (빠른 테스트)	python myagent.py console	마이크/오디오 I/O를 사용하여 로컬에서 실행 (서버 불필요)
개발	python myagent.py dev	핫 리로딩과 함께 AgentServer 시작; LiveKit Cloud 또는 자체 호스팅 서버에 연결
프로덕션	python myagent.py start	프로덕션 수준의 최적화 설정으로 실행

리소스

• 전체 문서: https://docs.livekit.io/agents/
• 예제 저장소: https://github.com/livekit-examples/python-agents-examples
• 커뮤니티 Slack, Twitter, Discord 링크는 README 배지에 있습니다.

라이선스 – 프레임워크는 Apache-2.0이며, 턴 감지 모델에는 별도의 LiveKit 모델 라이선스가 적용됩니다.

---

LiveKit Agents를 사용하면 개발자는 모든 LLM을 실시간 음성(또는 비디오) 참여자로 바꿀 수 있습니다. 이는 브라우저, 모바일 앱, 전화에서 호출할 수 있으며, 모두 LiveKit의 WebRTC 인프라를 기반으로 합니다.