# 시작하기 (/docs/getting-started)

## 시작하기

한국AI통신은 한국 전화/문자 API 플랫폼입니다.
전화번호 발급, 통화 발신/수신, SMS/MMS 발송, AI 음성 에이전트까지 Python SDK로 제어할 수 있습니다.

이 가이드에서는 대시보드에서 번호를 발급받고, AI 에이전트로 전화를 받고 거는 것까지 진행합니다.

  이 가이드는 SDK 기반의 **Voice Agent** 경로입니다. AI 봇이 아니라 *통화 흐름 자체* 를 IVR/분기/녹음
  등으로 직접 제어해야 한다면 [직접 만들기 (VoiceML)](/docs/build) 의 비교를 먼저 확인하세요.

## 1단계: 번호 발급

**회원가입 및 로그인**

[한국AI통신 대시보드](https://platform.claw-ops.com/)에서 회원가입 후 로그인합니다.

**전화번호 발급**

대시보드 > **전화번호** 메뉴에서 새 번호를 발급받습니다.
발급된 070 번호가 AI 에이전트의 수신/발신 번호가 됩니다.

**API Key 확인**

대시보드 > **개발자** > **API 키**에서 다음 두 값을 확인합니다.

| 항목         | 설명                   |
| ------------ | ---------------------- |
| `API Key`    | SDK 인증에 사용되는 키 |
| `Account ID` | 계정 고유 ID           |

## 2단계: 인바운드 에이전트

발급받은 번호로 걸려오는 전화를 AI가 받도록 설정합니다.

### SDK 설치

Python 또는 Node.js / TypeScript 중 선택:

```bash
# Python (3.10+)
pip install clawops[agent,openai]

# Node.js / TypeScript (18+)
npm install @teamlearners/clawops ws openai
```

Python은 가상환경(venv) 사용을 권장합니다. Node.js는 ESM 환경(`"type": "module"` 또는 `.mjs`)에서 실행하세요.

이 가이드는 현재 유일하게 검증 완료된 **OpenAI Realtime**을 사용합니다. 다른 제공자를 사용하려면 [제공자 호환성](/docs/voice-agent/providers)에서 검증 상태를 확인하세요.

### 환경변수 설정

```bash
export CLAWOPS_API_KEY="your-api-key"
export CLAWOPS_ACCOUNT_ID="your-account-id"
export OPENAI_API_KEY="your-openai-key"
```

### 에이전트 실행

**Python**

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

agent = ClawOpsAgent(
    from_="07012341234",  # 발급받은 번호
    session=OpenAIRealtime(
        system_prompt="친절한 고객 상담원입니다. 한국어로 응대합니다.",
        voice="marin",
        language="ko",
    ),
)

asyncio.run(agent.serve())
```

**Node.js / TypeScript**

```typescript
import { ClawOpsAgent, OpenAIRealtime } from '@teamlearners/clawops/agent';

const agent = new ClawOpsAgent({
  from: '07012341234', // 발급받은 번호
  session: new OpenAIRealtime({
    systemPrompt: '친절한 고객 상담원입니다. 한국어로 응대합니다.',
    voice: 'marin',
    language: 'ko',
  }),
});

await agent.serve();
```


  `from` (Python: `from_`) 에 1단계에서 발급받은 번호를 입력하세요. `agent.serve()`는 에이전트가 한국AI통신 서버에 직접
  연결하므로 ngrok 같은 터널링 도구가 필요 없습니다.

실행 후 발급받은 번호로 전화를 걸어보세요. AI가 전화를 받습니다.

## 3단계: 아웃바운드 전화

에이전트에서 직접 전화를 걸 수도 있습니다.

**Python**

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

agent = ClawOpsAgent(
    from_="07012341234",
    session=OpenAIRealtime(
        system_prompt="예약 확인 전화를 하는 도우미입니다.",
        language="ko",
    ),
)

async def main():
    session = await agent.call("01012345678", timeout=30)
    print(f"발신 중... (call_id: {session.call_id})")
    await session.wait()       # 통화 종료까지 대기
    await agent.disconnect()

asyncio.run(main())
```

**Node.js / TypeScript**

```typescript
import { ClawOpsAgent, OpenAIRealtime } from '@teamlearners/clawops/agent';

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({
    systemPrompt: '예약 확인 전화를 하는 도우미입니다.',
    language: 'ko',
  }),
});

const session = await agent.call('01012345678', { timeout: 30 });
console.log(`발신 중... (callId: ${session.callId})`);
await session.wait();
await agent.disconnect();
```

인바운드와 아웃바운드를 동시에 처리할 수도 있습니다 (Python):

```python
async def main():
    await agent.connect()                     # 인바운드 수신 시작
    session = await agent.call("01012345678") # 동시에 발신도 가능
    # Ctrl+C로 종료
```

## 다음 단계

- [제공자 호환성](/docs/voice-agent/providers) — 검증된 제공자 목록과 SDK별 지원 현황
- [Voice Agent](/docs/voice-agent) — Tool 등록, Call Transfer, Pipeline 모드, MCP 연동 등 에이전트 심화 기능
- [Python SDK](/docs/sdk/python) — REST API 전체 메서드 레퍼런스
- [Node.js SDK](/docs/sdk/node) — REST API 전체 메서드 레퍼런스
- [VoiceML](/docs/build/voiceml) — Webhook 기반 통화 제어 (Say, Gather, Dial 등)
- [Webhook](/docs/webhooks) — Status Callback, Message Webhook, 서명 검증
- [Stream](/docs/build/stream) — 실시간 음성 스트리밍 연동 가이드