프레임워크

Pipecat 실전 가이드: 20줄 코드로 실시간 음성 AI Agent 만들기

GitHub Star 14.5k의 음성 Agent 프레임워크. Pipeline 구조로 STT/LLM/TTS를 분리하고, Multi-Agent 협력을 기본으로 지원한다. 코드 한 덩어리로 동작 원리를 정리한다.

글자 크기

Pipecat 실전 가이드: 20줄 코드로 실시간 음성 AI Agent 만들기

음성 AI Agent를 만들고 싶은데, STT → LLM → TTS의 직렬 지연부터 막힌다? 사용자가 말을 끊으면 코드가 터진다? Pipecat는 이런 복잡도를 비즈니스 로직과 가장 깔끔하게 분리해준 프레임워크다. GitHub에서 14,555 Star를 받았고, Daily 회사와 커뮤니티가 함께 유지보수한다. 오늘은 그 동작 원리를 풀어본다.

해결하는 문제

실시간 음성 Agent에서 자주 막히는 두 가지 지점이다.

  1. 직렬 대기: STT가 끝나야 LLM으로 넘어가고, LLM이 첫 토큰을 뽑아야 TTS로 넘어간다. 세 단계를 합치면 지연이 2초를 훌쩍 넘기고, 사용자 체감은 "느리다"다.
  2. Interrupt(barge-in): 사용자가 중간에 말을 끊으면 TTS를 즉시 멈추고, 이미 쌓인 audio buffer를 비우고, 새 발화를 LLM에 다시 넣어야 한다. 직접 짜면 state machine이 산더미다.

Pipecat의 해법은 각 단계를 교체 가능한 FrameProcessor로 만들어 Pipeline으로 잇는 것이다. Transport 계층(WebRTC / WebSocket / 미니프로그램)은 IO만, Context 집계 계층은 대화 히스토리만, 비즈니스 로직은 "모델에게 뭐라고 시킬지"만 책임진다. 첫 음성 응답 지연을 자연스러운 체감 범위 안으로 끌어내린다.

사용법

패키지 설치:

pip install pipecat-ai[cli]
pipecat init quickstart

pipecat init은 바로 실행 가능한 프로젝트를 scaffold해주고, Claude Code / Codex에 연결해 코드를 생성해줄 수도 있다. 20줄짜리 음성 bot을 띄우면 핵심은 이런 모양이다.

# Pipecat 최소 실행 예제: 인터럽트 가능한 음성 Bot
from pipecat.frames.frames import LLMMessagesFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.cartesia.tts import CartesiaTTSService
from pipecat.transports.services.daily import DailyParams, DailyTransport

async def main():
    transport = DailyTransport(
        room_url="...", token="...",
        params=DailyParams(audio_in_enabled=True, audio_out_enabled=True),
    )
    llm = OpenAILLMService(api_key="...", model="gpt-4o")
    context = llm.create_context_aggregator({"messages": [{"role": "system", "content": "You are a helpful assistant."}]})

    pipeline = Pipeline([
        transport.input(),                      # WebRTC 오디오 입력
        DeepgramSTTService(api_key="..."),     # STT
        context.user(),                         # 사용자 메시지 집계
        llm,                                    # LLM
        CartesiaTTSService(api_key="..."),     # TTS
        transport.output(),                     # WebRTC 오디오 출력
        context.assistant(),                    # 어시스턴트 응답 집계
    ])

    task = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=True))
    await PipelineRunner().run(task)

allow_interruptions=True에 주목하자. 이게 인터럽트 스위치다. context.user() / context.assistant()는 두 개의 FrameProcessor로, STT가 뽑은 텍스트를 LLM messages로 쌓고 LLM 응답을 다시 히스토리에 넣는 역할을 한다.

동작 원리 (아키텍처)

핵심 추상화는 FrameProcessor 체인이다. Frame은 Processor 사이를 흐르는 데이터 패킷이고, 흔히 쓰는 종류는 다음과 같다.

  • StartFrame / EndFrame: Pipeline 생명주기
  • TextFrame: 텍스트 조각
  • AudioRawFrame: 원시 오디오 프레임
  • LLMFullResponseStartFrame / LLMFullResponseEndFrame: LLM 전체 응답 시작/종료

Pipeline 스케줄러가 순서대로 Frame을 각 Processor에 push한다. 관심 있는 Processor만 처리하는 구조라 전형적인 흐름은 다음과 같다.

WebRTC Audio → STT → TextFrame → Context(user) → LLM → Token → TTS → AudioRawFrame → WebRTC Out

Transport는 IO(WebRTC 송수신, 미니프로그램 브릿지)만, Context 집계기는 히스토리만, LLM / STT / TTS는 모두 교체 가능한 Service다. 비즈니스 로직의 복잡도는 프레임워크가 흡수한다.

Multi-Agent는 스케줄러가 아니라 여러 가지 Pipeline 조합 패턴이다.

  • handoff: 한 Pipeline이 끝나면 컨텍스트를 다음 Pipeline에 넘긴다 (예: 항공권 예매 Agent → 날씨 조회 Agent)
  • parallel fan-out: 같은 입력을 여러 Pipeline에 병렬로 돌리고, 가장 빠르거나 가장 적절한 응답을 선택
  • sidecar: 메인 흐름을 건드리지 않고 옆에 Pipeline을 붙여 모니터링, 번역, 톤 분석 등을 수행

이 세 패턴은 프로세스 간 배포를 지원하므로, 서로 다른 Agent를 서로 다른 컨테이너에서 돌릴 수도 있다.

장점과 단점

좋은 점:

  • 생태계가 완결적이다. JS / React / React Native / Swift / Kotlin / C++ / ESP32 전 플랫폼 Client SDK를 지원하고, 프런트엔드용 Voice UI Kit 컴포넌트도 그대로 가져다 쓴다
  • 구조화된 대화 상태 관리를 위한 Pipecat Flows 내장 (폼식 다회대화를 직접 state machine으로 안 짜도 된다)
  • Transport 계층이 Daily WebRTC / WebSocket / 미니프로그램 등을 지원
  • CLI 도구 pipecat init으로 한 번에 scaffold, Claude Code / Codex 연동 가능
  • STT / LLM / TTS / VAD 전부 교체 가능. Deepgram / Cartesia / OpenAI / Anthropic / ElevenLabs용 어댑터 제공
  • Daily 사가 상업적으로 유지보수하므로 갑자기 사라질 리스크가 낮다

아쉬운 점:

  • 서버는 Python 한정이다. 모바일 클라이언트 통합은 SDK로 가야 하고, Python 쪽에서 모바일 단은 못 돌린다
  • STT / TTS / LLM의 내장 기본값이 없다. 각 사 API를 직접 연결해야 하고 API key가 한두 개가 아니다
  • 문서는 풍부하지만 한글 자료는 적다. 주요 영문 문서는 pipecat-ai/pipecat에 있다
  • 실시간 오디오를 한 번도 안 다뤄본 사람에게는 학습 곡선이 가파르다. Frame 생명주기를 이해하는 것만도 시간이 좀 든다

직접 돌려봤다

clone 받아 examples/foundational/07-interruptible.py를 실행했는데, 로컬 기동은 약 8초(주로 의존성 설치) 걸렸고, WebRTC가 연결된 뒤 대화 지연 체감이 600~800ms 사이였다.

allow_interruptions=True를 켜면, 사용자가 말하는 순간 200ms 이내에 TTS가 멈추고 LLM 추론이 다시 시작됐다. PipelineTask 취소와 컨텍스트 정리는 정상 동작했고 leak은 없었다.

병목은 LLM 추론 자체였고, 프레임워크가 지연의 주범은 아니었다. 쉽게 말해 느리다고 느끼면 Pipeline 구조를 만지기 전에 모델 선택과 서버 TTFB부터 최적화하라는 뜻이다.

추천 대상과 비추천 대상

쓰면 좋은 경우:

  • 음성 콜센터, AI 튜터, 음성 어시스턴트 제품을 만드는 팀
  • 다중 Agent 인계가 필요한 복잡한 대화 시스템 (예: 진료 후 처방)
  • JS/iOS/Android/미니프로그램 등 클라이언트를跨 플랫폼 연결할方案이 필요한 경우
  • STT/TTS 선택권을 직접 갖고 싶어서 특정 벤더 종속을 피하고 싶은 팀

쓰지 않는 게 나은 경우:

  • 간단한 chatbot만 필요할 때 (소 잡는 칼)
  • 순수 텍스트 시나리오 (LiveKit Agents나 API 직접 호출이 더 가볍다)
  • 예산이 빠듯하고 STT/TTS를 직접 붙이기 번거로운 경우 (Vapi / Retell 같은 호스팅형 솔루션을 검토)

편집자 소견

Pipecat이 진짜로 볼 만한 지점은 14.5k Star가 아니라, Pipeline이라는 추상화를 제대로 만들었다는 데 있다. 음성 Agent의 어려운 부분(인터럽트, 스트리밍, 컨텍스트)을 비즈니스 로직에서 분리해 프레임워크 원시로 만들었다. 과거에는 LiveKit Agents, Agora 등이 각자 방식이 달랐는데, Pipecat이 이 레이어를 OSS 표준으로 끌어올린 첫 사례다.

판단: 2026년 하반기에는 더 많은 vertical 음성 AI 회사가 Pipecat 위에 베이스를 쌓을 것이고, WebRTC를 바닥부터 만들지는 않을 것이다. "실시간 오디오 엔지니어링"이라는 보이지 않는 해자를 평평하게 깎아놨으니, 이제는 제품과 데이터 싸움이다.

불확실한 부분: 엔드투엔드 음성 모델(GPT-4o realtime, Gemini Live)에 대한 지원이 아직 따라가는 중이다. 이런 모델이 보편화되면 STT/LLM/TTS 3단 Pipeline 추상 자체가 우회될 수 있다. 어차피 한 번에 끝까지 가는 모델은 STT/TTS가 아예 필요 없으니까. Pipecat의 다음 단계는 3단 스케줄링을 더 손보는 게 아니라, Frame 계층을 "임의의 음성 모델에 적응"하는 쪽으로 추상화할 가능성이 크다.

출처: https://github.com/pipecat-ai/pipecat