# 제공자 호환성 (/docs/sdk/python/agent/providers)

> 커스텀 제공자를 직접 구현할 수도 있습니다. [커스텀 제공자 가이드](custom-providers)를 참고하세요.

## Realtime (Speech-to-Speech)

단일 API로 음성 입력부터 음성 출력까지 처리하는 end-to-end 방식입니다.

| 제공자                 | 클래스           | 기본 모델                       | Tool Calling | 환경변수         | Python | Node |     상태      | 검증일     |
| ---------------------- | ---------------- | ------------------------------- | :----------: | ---------------- | :----: | :--: | :-----------: | ---------- |
| OpenAI Realtime API    | `OpenAIRealtime` | `gpt-realtime-2`              |      ✅      | `OPENAI_API_KEY` |   ✅   |  ✅  | **검증 완료** | 2026-03-12 |
| Google Gemini Live API | `GeminiRealtime` | `gemini-3.1-flash-live-preview` |      ✅      | `GOOGLE_API_KEY` |   ✅   |  ✅  |    검증 중    | —          |

> **Vertex AI:** `GOOGLE_API_KEY` 대신 `GOOGLE_GENAI_USE_VERTEXAI=true`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` 환경변수를 설정하면 Google Cloud Vertex AI 백엔드를 사용할 수 있습니다. ADC(Application Default Credentials) 인증이 필요합니다.

## Pipeline 모드 제공자

STT → LLM → TTS를 개별 조합하는 방식입니다. `PipelineSession`에서 사용합니다.

### STT (Speech-to-Text)

| 제공자   | 클래스        | 프로토콜           | VAD | Barge-in | 환경변수           | Python | Node |  상태   | 검증일 |
| -------- | ------------- | ------------------ | :-: | :------: | ------------------ | :----: | :--: | :-----: | ------ |
| Deepgram | `DeepgramSTT` | WebSocket 스트리밍 |  —  |    —     | `DEEPGRAM_API_KEY` |   —    |  —   | 검증 전 | —      |

### LLM (Large Language Model)

| 제공자        | 클래스          | API 방식    | Tool Calling | Streaming | 환경변수             | Python | Node |  상태   | 검증일 |
| ------------- | --------------- | ----------- | :----------: | :-------: | -------------------- | :----: | :--: | :-----: | ------ |
| OpenAI        | `OpenAILLM`     | Native SDK  |      —       |     —     | `OPENAI_API_KEY`     |   —    |  —   | 검증 전 | —      |
| Anthropic     | `AnthropicLLM`  | Native SDK  |      —       |     —     | `ANTHROPIC_API_KEY`  |   —    |  —   | 검증 전 | —      |
| Google Gemini | `GeminiLLM`     | Native SDK  |      —       |     —     | `GOOGLE_API_KEY`     |   —    |  —   | 검증 전 | —      |

> **Vertex AI:** `GeminiLLM`도 Vertex AI 백엔드를 지원합니다. `GOOGLE_GENAI_USE_VERTEXAI=true`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` 환경변수를 설정하면 `GOOGLE_API_KEY` 없이 동작합니다.

| Ollama        | `OllamaLLM`     | OpenAI 호환 |      —       |     —     | `OLLAMA_BASE_URL`    |   —    |  —   | 검증 전 | —      |
| Mistral       | `MistralLLM`    | OpenAI 호환 |      —       |     —     | `MISTRAL_API_KEY`    |   —    |  —   | 검증 전 | —      |
| Groq          | `GroqLLM`       | OpenAI 호환 |      —       |     —     | `GROQ_API_KEY`       |   —    |  —   | 검증 전 | —      |
| Perplexity    | `PerplexityLLM` | OpenAI 호환 |      —       |     —     | `PERPLEXITY_API_KEY` |   —    |  —   | 검증 전 | —      |
| Together AI   | `TogetherLLM`   | OpenAI 호환 |      —       |     —     | `TOGETHER_API_KEY`   |   —    |  —   | 검증 전 | —      |
| Fireworks AI  | `FireworksLLM`  | OpenAI 호환 |      —       |     —     | `FIREWORKS_API_KEY`  |   —    |  —   | 검증 전 | —      |
| DeepSeek      | `DeepSeekLLM`   | OpenAI 호환 |      —       |     —     | `DEEPSEEK_API_KEY`   |   —    |  —   | 검증 전 | —      |
| xAI (Grok)    | `XaiLLM`        | OpenAI 호환 |      —       |     —     | `XAI_API_KEY`        |   —    |  —   | 검증 전 | —      |

**OpenAI 호환 API를 사용하는 다른 제공자**가 있다면 `OpenAICompatibleLLM` (Python) / `OpenAICompatLLM` (Node)으로 직접 연결할 수 있습니다.

### TTS (Text-to-Speech)

| 제공자     | 클래스          | 프로토콜           | Sample Rate  | 환경변수             | Python | Node |  상태   | 검증일 |
| ---------- | --------------- | ------------------ | ------------ | -------------------- | :----: | :--: | :-----: | ------ |
| ElevenLabs | `ElevenLabsTTS` | WebSocket 스트리밍 | 24kHz (기본) | `ELEVENLABS_API_KEY` |   —    |  —   | 검증 전 | —      |

## 설치

각 제공자는 선택적 의존성으로 분리되어 있습니다. 필요한 제공자만 설치하세요.

```bash
# Realtime (검증 완료)
pip install clawops[openai]         # OpenAI Realtime + OpenAI LLM

# Realtime (검증 전)
pip install clawops[gemini]     # Gemini Realtime + Gemini LLM

# Pipeline 개별 제공자 (검증 전)
pip install clawops[deepgram]       # Deepgram STT
pip install clawops[elevenlabs]     # ElevenLabs TTS
pip install clawops[anthropic-llm]  # Anthropic LLM
pip install clawops[ollama]         # Ollama LLM
pip install clawops[mistral]        # Mistral LLM
pip install clawops[groq]           # Groq LLM
pip install clawops[perplexity]     # Perplexity LLM
pip install clawops[together]       # Together AI LLM
pip install clawops[fireworks]      # Fireworks AI LLM
pip install clawops[deepseek]       # DeepSeek LLM
pip install clawops[xai]            # xAI LLM

# 전체 설치
pip install clawops[agent-all]
```

## 세션 타입별 비교

|                  |  OpenAI Realtime  | Gemini Realtime  |        Pipeline         |
| ---------------- | :---------------: | :--------------: | :---------------------: |
| **방식**         | Speech-to-Speech  | Speech-to-Speech |     STT → LLM → TTS     |
| **지연**         |       낮음        |       낮음       |          중간           |
| **Barge-in**     |     내장 VAD      |     내장 VAD     |      Deepgram VAD       |
| **LLM 선택**     |    OpenAI 전용    |   Gemini 전용    |  11개 제공자 자유 선택  |
| **음성 선택**    |    OpenAI 음성    |   Google 음성    | ElevenLabs 등 자유 선택 |
| **Tool Calling** |        ✅         |        —         |            —            |
| **비용**         | Realtime API 요금 | Gemini API 요금  |   각 제공자 개별 요금   |
| **상태**         |   **검증 완료**   |     검증 전      |         검증 전         |

## 범례

|     기호      | 의미                                             |
| :-----------: | ------------------------------------------------ |
|      ✅       | 기능 지원                                        |
|      ⚠️       | 알려진 이슈 있음, 조건부 동작                    |
|       —       | 미검증                                           |
| **검증 완료** | 실제 통화 환경에서 테스트 완료                   |
|    검증 전    | 구현은 완료되었으나 실제 통화 환경 테스트 미완료 |

---

_마지막 업데이트: 2026-03-12_