프로덕션 환경에 즉시 적용 가능한 실시간 음성 및 멀티모달 (Multimodal) AI 에이전트를 구축하기 위한 오픈 소스 Python 프레임워크입니다.

VideoSDK AI Agents 프레임워크는 VideoSDK 룸에 실시간 참가자로 참여하는 AI 에이전트를 구축하기 위한 Python SDK입니다. 이 프레임워크는 에이전트 워커(Worker), AI 모델, 사용자 기기를 하나의 저지연 (Low-latency) 파이프라인으로 연결합니다. 오디오 스트리밍, 발화 감지 (Turn detection), 중단 (Interruptions), 미디어 라우팅을 자동으로 처리하므로 사용자는 에이전트 로직에만 집중할 수 있습니다.

VideoSDK AI Agents는 VideoSDK 룸에 직접 참여하는 음성 및 멀티모달 (Multimodal) AI 에이전트를 구축할 수 있게 해주는 Python 프레임워크입니다. 이 프레임워크는 룸 참여 및 라이브 오디오 처리부터 STT → LLM → TTS 파이프라인 실행 또는 통합 실시간 모델 연결, 발화 감지 (Turn detection), VAD (Voice Activity Detection), 중단 처리, 그리고 깔끔한 종료(Teardown)에 이르기까지 에이전트의 전체 생명주기를 관리합니다.

v1.0.0에서는 기존의 CascadingPipeline과 RealtimePipeline을 대체하는 통합 Pipeline 클래스를 도입했습니다. STT, LLM, TTS, VAD, 발화 감지기 (Turn detector), 아바타 (Avatar) 등 어떤 구성 요소의 조합이든 전달하면, 프레임워크가 이들을 서로 연결하고 최적의 실행 모드를 자동으로 선택합니다. 데코레이터 기반의 훅 (Hooks) 시스템(@pipeline.on(...))을 사용하면 서브클래싱 (Subclassing) 없이도 어느 단계에서나 데이터를 가로채고 변환할 수 있습니다.

중요 사항

VideoSDK 저장소(Repositories) 스타(Star) 하기 ⭐️

새로운 릴리스 및 업데이트에 대한 즉각적인 알림을 받으세요. 여러분의 지원은 VideoSDK가 성장하고 개선되는 데 큰 도움이 됩니다!

모든 에이전트는 단일 Pipeline 클래스를 중심으로 구축됩니다.

구성 요소를 전달하기만 하면 SDK가 적절한 실행 모드를 자동으로 선택합니다.

각 단계마다 어떤 제공업체든 자유롭게 조합하여 사용할 수 있습니다. 커스텀 STT, 특정 LLM 동작 또는 특정 TTS 음성이 필요한 경우에 가장 효과적입니다.

async def start_session(context: JobContext):
    pipeline = Pipeline(
        stt=DeepgramSTT(),
        ...

전체 음성 파이프라인(voice pipeline)에 단일 실시간 모델(realtime model)을 사용합니다. 500ms 미만의 응답 지연 시간(latency)을 달성하는 데 가장 적합합니다.

async def start_session(context: JobContext):
    pipeline = Pipeline(
        llm=GeminiRealtime(
        ...

실시간 LLM(Realtime LLM)과 외부 STT를 함께 사용하거나, 실시간 모델과 커스텀 TTS를 함께 사용합니다:

# 외부 STT → 실시간 LLM (Realtime LLM)
pipeline = Pipeline(stt=DeepgramSTT(), llm=OpenAIRealtime(...))
# 실시간 LLM (Realtime LLM) → 외부 TTS
...

@pipeline.on("stt")
async def clean_transcript(text: str) -> str:
    return text.strip()
...

사용 가능한 훅 포인트(hook points):

· stt

· tts

· llm

· vision_frame

· user_turn_start

· user_turn_end

· agent_turn_start

· agent_turn_end

시작하기 전에 다음 사항을 준비했는지 확인하세요:

• VideoSDK 인증 토큰 (app.videosdk.live에서 생성)

• VideoSDK 미팅 ID (Create Room API 또는 VideoSDK 대시보드를 통해 생성 가능)

• Python 3.12 이상

• 제3자 API 키 (Third-Party API Keys):

• 사용하려는 서비스의 API 키 (예: LLM/STT/TTS를 위한 OpenAI, TTS를 위한 ElevenLabs, Gemini를 위한 Google 등).

UV는 가상 환경(virtual environments)과 의존성 관리(dependency management)를 자동으로 처리하는 빠른 Python 패키지 매니저(package manager)입니다.

UV가 설치되어 있지 않다면, UV 설치 가이드를 참조하세요.

핵심 VideoSDK AI Agent 패키지를 설치합니다:

uv add videosdk-agents

선택적 플러그인(Optional Plugins)을 설치합니다:

uv add videosdk-plugins-openai uv add videosdk-plugins-deepgram

에이전트를 실행합니다:

uv run python main.py

Python 3.12 이상의 가상 환경을 생성하고 활성화합니다.

macOS / Linux
python3 -m venv venv source venv/bin/activate

Windows
python -m venv venv venv\Scripts\activate

핵심 VideoSDK AI Agent 패키지를 설치합니다.

pip install videosdk-agents

선택적 플러그인을 설치합니다. 플러그인은 실시간(Realtime), STT, LLM, TTS 등을 위한 다양한 제공업체를 통합하는 데 도움을 줍니다. 사용 사례에 필요한 것을 설치하세요:

# 예시: Turn Detector 플러그인 설치 pip install videosdk-plugins-turn-detector

👉 지원되는 플러그인 (Realtime, LLM, STT, TTS, VAD, Avatar, SIP)은 아래의 Supported Libraries 섹션에 나열되어 있습니다.

프로젝트를 로컬에 설정하려면, 저장소(repo)를 클론(clone)하고 모든 패키지(core + 모든 플러그인)를 편집 가능한 설치(editable installs) 방식으로 설치하세요:

UV 사용 시 (권장):

git clone https://github.com/videosdk-live/agents.git
cd agents
uv sync
...

pip 사용 시:

git clone https://github.com/videosdk-live/agents.git
cd agents
bash setup.sh
...

AI 에이전트가 회의에 참여하기 전에, 회의 ID(meeting ID)를 생성해야 합니다. VideoSDK의 Create Room API를 사용하여 생성할 수 있습니다:

curl -X POST https://api.videosdk.live/v2/rooms \
-H "Authorization: YOUR_JWT_TOKEN_HERE" \
-H "Content-Type: application/json"

Create Room API에 대한 자세한 내용은 VideoSDK 문서를 참조하세요.

필요한 패키지를 모두 설치했으므로, 이제 구축할 준비가 되었습니다!

먼저, 기본 Agent 클래스를 상속받아 커스텀 음성 에이전트를 만들어 보겠습니다:

from videosdk.agents import Agent, function_tool
# 외부 도구 (External Tool)
# async def get_weather(self, latitude: str, longitude: str):
...

이 코드는 다음과 같은 기능을 가진 기본적인 음성 에이전트를 정의합니다:

• 에이전트의 성격과 능력을 정의하는 커스텀 지침 (Custom instructions)
• 회의 참여 시의 시작 메시지 (Entry message)
• 에이전트의 현재 활동을 추적하기 위한 상태 변경 처리 (State change handling)

함수 도구 (Function tools)를 사용하면 에이전트가 대화를 넘어선 동작을 수행할 수 있습니다. 도구를 정의하는 방법에는 두 가지가 있습니다:

외부 도구 (External Tools): 에이전트 클래스 외부에서 독립적인 함수로 정의되며, 에이전트 생성자의 tools 인자를 통해 등록됩니다.
내부 도구 (Internal Tools): 에이전트 클래스 내부에서 메서드로 정의되며, @function_tool 데코레이터가 붙습니다.

다음은 두 가지 방식의 예시입니다:

import aiohttp
# 외부 함수 도구 (External Function Tools)
@function_tool
...

• 재사용 가능한 독립적 함수에는 외부 도구를 사용하세요 (tools=[...]를 통해 등록)

). - 에이전트 전용 로직의 경우 클래스 메서드(class methods)로서 내부 도구(internal tools)를 사용하세요.

• 에이전트가 이를 인식하고 사용할 수 있도록 두 경우 모두 @function_tool 데코레이터(decorator)를 지정해야 합니다.

통합된 Pipeline 클래스를 사용하여 에이전트를 AI 모델에 연결하세요. 필요한 구성 요소를 전달하기만 하면 나머지는 SDK가 처리합니다.

실시간 모드 (Realtime mode) (단일 모델, 최저 지연 시간):

async def start_session(context: JobContext):
pipeline = Pipeline(
llm=GeminiRealtime(
...

캐스케이드 모드 (Cascade mode) (STT → LLM → TTS, 전체 제공업체 제어):

async def start_session(context: JobContext):
pipeline = Pipeline(
stt=DeepgramSTT(),
...

from videosdk.agents import AgentSession, WorkerJob, RoomOptions, JobContext
async def start_session(context: JobContext):
session = AgentSession(
...

AI 에이전트(AI Agent) 설정을 마친 후에는 에이전트와 연결할 클라이언트 애플리케이션(client application)이 필요합니다. VideoSDK의 퀵스타트(quickstart) 예제 중 아무거나 사용하여 동일한 회의에 참여하는 클라이언트를 만들 수 있습니다:

클라이언트 애플리케이션을 설정할 때, AI 에이전트가 사용 중인 것과 동일한 회의 ID(meeting ID)를 사용해야 합니다.

설정을 완료하면 Python을 사용하여 AI 음성 에이전트(AI Voice Agent) 프로젝트를 실행할 수 있습니다. .env 파일이 적절히 구성되었고 모든 종속성(dependencies)이 설치되었는지 확인하세요.

python main.py

팁(Tip)

콘솔 모드 (Console Mode) — 회의실 없이 로컬에서 에이전트를 테스트하세요.
RoomOptions에서 playground=True로 설정하고 python main.py를 실행하면 터미널에서 마이크와 스피커를 통해 직접 상호작용할 수 있습니다.

배포 옵션 및 가이드는 여기의 공식 문서에서 확인하세요: Deployment

VideoSDK Inference는 개별 제공업체의 API 키를 관리할 필요 없이 STT, LLM, TTS, Denoise 및 Realtime 모델에 액세스할 수 있는 **통합 게이트웨이 (unified gateway)**를 제공합니다. 인증은 VIDEOSDK_AUTH_TOKEN을 통해 처리되며, 사용량은 VideoSDK 계정 잔액에서 청구됩니다.

from videosdk.agents.inference import STT, LLM, TTS, Denoise, Realtime

VideoSDK Inference를 사용한 캐스케이드 모드 (Cascade Mode with VideoSDK Inference):

async def start_session(context: JobContext):
    pipeline = Pipeline(
        stt=STT.sarvam(model_id="saarika:v2.5", language="en-IN"),
        ...

VideoSDK Inference를 사용한 실시간 모드 (Realtime Mode with VideoSDK Inference):

async def start_session(context: JobContext):
    pipeline = Pipeline(
        llm=Realtime.gemini(
            ...

제공자별 과금 상세 정보는 Inference Pricing (추론 가격 책정)을 참조하세요.

이 프레임워크는 여러 카테고리에 걸쳐 다양한 AI 모델 및 도구와의 통합을 지원합니다:

팁

설치 예시 (Installation Examples)

# 특정 플러그인과 함께 설치
pip install videosdk-agents[openai,elevenlabs,silero]
# 개별 플러그인 설치
...

프레임워크의 작동 방식을 확인하려면 다음 예시들을 살펴보세요:

| Model Context Protocol (MCP)을 통해 실시간 시장 데이터에 접근하는 주식 시장 분석 에이전트 (Stock Market Analyst Agent). |
멀티 에이전트 워크플로우 (Multi-agent workflow): 대출 문의를 대출 전문가 에이전트 (Loan Specialist Agent)로 전달하는 고객 에이전트. |
| VideoSDK 에이전트 프레임워크 내에서 LangChain 도구 및 에이전트 사용. |
LangGraph 상태 머신 (state machines)을 사용하여 다단계 에이전트 워크플로우 오케스트레이션 (Orchestrate). |
| 장기적인 문맥 유지를 위해 Mem0를 사용하여 세션 간 지속적인 메모리 (Persistent memory) 제공. |
계층적 (cascading) 또는 실시간 파이프라인 (realtime pipelines)을 사용하여 음성과 함께 비디오 프레임을 처리하는 멀티모달 (Multimodal) 에이전트. |
| 웹훅 (webhooks)을 사용하여 에이전트 내부에서 n8n 자동화 워크플로우 트리거. |
Discord 또는 기타 채널을 통해 대화 도중 상담원 (human agent)에게 연결. |

| 음성 지원 전화 에이전트 (telephony agent)를 통한 병원 예약. |
이동 중에 이용 가능한 호텔 객실을 문의하고 예약. |
| 문서 지식 (documentation knowledge)을 기반으로 질문에 답변하는 에이전트. |
일기 예보를 발표하는 가상 아바타 에이전트 (Virtual Avatar Agent). |
| 클리닉 예약을 위한 의료 프런트 데스크 접수원. |
공지 사항을 방송하는 능동형 아웃바운드 (outbound) 에이전트. |
| 에스컬레이션 (escalation) 및 지식 베이스 (knowledge base)를 갖춘 AI 기반 고객 지원 에이전트. |
콜 센터, IVR, 의료 트리아지 (medical triage), 언어 튜터, 회의록 작성 등. |

종합 가이드 및 API 참조를 보려면: