# ClawOps Agent (/docs/sdk/python/agent)

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

## 문서 목록

| 문서                                 | 내용                                  |
| ------------------------------------ | ------------------------------------- |
| [빠른 시작](quickstart)           | 설치, 환경변수, 기본 사용법           |
| [검증된 제공자](providers)        | SDK별 제공자 호환성 매트릭스          |
| [파이프라인 모드](pipeline)       | 커스텀 STT/LLM/TTS 조합               |
| [커스텀 제공자](custom-providers) | 나만의 STT/LLM/TTS 제공자 구현 가이드 |
| [Tool](tools)                     | AI 함수 호출 (`@agent.tool`)          |
| [이벤트 & CallSession](events)    | 통화 이벤트 핸들러, CallSession API   |
| [MCP 서버](mcp)                   | MCP 서버 연동                         |
| [녹음](recording)                 | 통화 녹음 설정                        |
| [Tracing](tracing)                | OpenTelemetry 연동                    |
| [아키텍처](architecture)          | 내부 구조, 보안 모델                  |
| [배포](deployment)                | 무중단 배포, 인스턴스 수              |
| [트러블슈팅](troubleshooting)     | 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` 파라미터로 세션 타입을 지정합니다.

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

### OpenAI Realtime

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

```python
from clawops.agent import ClawOpsAgent, OpenAIRealtime

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

### Gemini Realtime

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

```python
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 제공자를 직접 조합합니다. 제공자를 자유롭게 교체할 수 있습니다.

```python
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(),
    ),
)
```

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