Skip to content

agent

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

agent

README.md

ClawOps Agent

AI 음성 에이전트 프레임워크. 인바운드/아웃바운드 전화를 AI로 자동 처리합니다.

WebSocket 역방향 연결 방식으로 ngrok 없이 로컬에서 바로 실행할 수 있습니다.

문서 목록

문서 내용
빠른 시작 설치, 환경변수, 기본 사용법
검증된 제공자 SDK별 제공자 호환성 매트릭스
파이프라인 모드 커스텀 STT/LLM/TTS 조합
커스텀 제공자 나만의 STT/LLM/TTS 제공자 구현 가이드
Tool AI 함수 호출 (@agent.tool)
이벤트 & CallSession 통화 이벤트 핸들러, CallSession API
MCP 서버 MCP 서버 연동
녹음 통화 녹음 설정
Tracing OpenTelemetry 연동
아키텍처 내부 구조, 보안 모델
트러블슈팅 SSL 인증서, 연결 실패 등 문제 해결

동작 원리

┌──────────────┐    Control WS     ┌──────────────┐
│  ClawOpsAgent │◄─────────────────►│ ClawOps 서버  │
│  (로컬 실행)  │    Media WS (콜별) │              │
│              │◄─────────────────►│              │
└──────┬───────┘                   └──────────────┘
       │
       ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ OpenAI       │  │ Gemini       │  │ Pipeline     │
│ Realtime API │  │ Live API     │  │ STT→LLM→TTS  │
└──────────────┘  └──────────────┘  └──────────────┘
  1. Agent가 서버에 연결 — Control WebSocket으로 역방향 연결
  2. 전화 수신 알림 — 서버가 call.incoming 이벤트 전송
  3. 미디어 스트림 연결 — 콜별 Media WebSocket으로 오디오 스트리밍
  4. AI 처리 — 선택한 세션 타입으로 음성 대화
  5. Tool 호출 — AI가 필요 시 등록된 함수 자동 호출

시작 방법

메서드 용도
agent.serve() 인바운드 서버 모드 (SIGINT/SIGTERM까지 대기, 자동 disconnect)
agent.connect() Control WS 연결만 (논블로킹, 아웃바운드/혼합 모드용)
agent.disconnect() 연결 해제
agent.call(to) 발신 전화 (미연결 시 자동 connect)
session.wait() 통화 종료까지 대기

세션 타입

ClawOpsAgent의 session 파라미터로 세션 타입을 지정합니다.

각 제공자의 검증 상태와 지원 현황은 제공자 호환성 문서를 반드시 확인하세요.

OpenAI Realtime

OpenAI Realtime API를 사용한 Speech-to-Speech 방식.

from clawops.agent import ClawOpsAgent, OpenAIRealtime

agent = ClawOpsAgent(
    from_="07012341234",
    session=OpenAIRealtime(
        system_prompt="친절한 상담원입니다.",
    ),
)

Gemini Realtime

Google Gemini Live API를 사용한 Speech-to-Speech 방식.

from clawops.agent import ClawOpsAgent, GeminiRealtime

agent = ClawOpsAgent(
    from_="07012341234",
    session=GeminiRealtime(
        system_prompt="친절한 상담원입니다.",
        voice="Kore",
    ),
)

Note: 기본 모델이 gemini-3.1-flash-live-preview로 업데이트되었습니다. 이전 gemini-2.5-flash-native-audio-preview-12-2025 모델은 더 이상 지원되지 않습니다.

Pipeline 모드

STT, LLM, TTS 제공자를 직접 조합합니다. 제공자를 자유롭게 교체할 수 있습니다.

from clawops.agent import ClawOpsAgent
from clawops.agent.pipeline import PipelineSession, DeepgramSTT, OpenAILLM, ElevenLabsTTS

agent = ClawOpsAgent(
    from_="07012341234",
    session=PipelineSession(
        system_prompt="친절한 상담원입니다.",
        stt=DeepgramSTT(),
        llm=OpenAILLM(model="gpt-4o-mini"),
        tts=ElevenLabsTTS(),
    ),
)

자세한 내용은 파이프라인 모드 문서를 참고하세요.