Python AI 전화 SDK — 한국 070 번호로 voice agent 5분 만들기 (ngrok 없이)

ClawOps Python SDK를 처음 쓰는 사람을 위한 가이드입니다. 이 글을 따라 하면 10분 안에 AI가 전화를 받는 시스템을 만들 수 있습니다.

전체 구조

ClawOps Python SDK
├── clawops.ClawOps         ← REST 클라이언트 (번호·통화·메시지 관리)
│   ├── numbers.create()    ← 070 번호 발급
│   ├── calls.create()      ← 전화 발신
│   ├── messages.create()   ← SMS/LMS/MMS 발송
│   └── calls.get_transcript()  ← 통화 전사 조회
│
└── clawops.agent           ← AI 에이전트 (음성 대화)
    ├── ClawOpsAgent        ← 에이전트 컨트롤러
    ├── OpenAIRealtime      ← OpenAI Realtime 세션
    └── BuiltinTool         ← 통화 전환, 끊기 등

SDK는 두 부분으로 나뉩니다:

1. REST 클라이언트 (from clawops import ClawOps) — 번호 발급, 전화 걸기, 문자 보내기
2. AI 에이전트 (from clawops.agent import ClawOpsAgent) — AI가 실시간으로 전화를 받고 대화

Step 0: 사전 준비

필요한 것:

• Python 3.10+
• ClawOps 계정 — 무료 Trial로 시작 가능
• OpenAI API 키 — AI 에이전트용

ClawOps 대시보드(platform.claw-ops.com)에서:

1. 가입 및 본인인증
2. 전화번호 메뉴에서 070 번호 발급
3. 설정 > API 키에서 API Key와 Account ID 확인

Step 1: 설치

# REST 클라이언트만 쓸 경우
pip install clawops

# AI 에이전트도 쓸 경우 (OpenAI Realtime 포함)
pip install clawops[agent,openai]

가상환경(venv) 사용을 권장합니다:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install clawops[agent,openai]

Step 2: 환경변수 설정

export CLAWOPS_API_KEY="sk_live_..."
export CLAWOPS_ACCOUNT_ID="AC1a2b3c4d"
export OPENAI_API_KEY="sk-..."

환경변수를 설정하면 SDK가 자동으로 읽습니다:

from clawops import ClawOps

# 환경변수가 설정되어 있으면 인자 생략 가능
client = ClawOps()

# 또는 직접 지정
client = ClawOps(
    api_key="sk_live_...",
    account_id="AC1a2b3c4d",
)

Step 3: 070 번호 발급

대시보드에서 이미 발급받았다면 이 단계는 건너뛰세요.

from clawops import ClawOps

client = ClawOps()

# 번호 발급
number = client.numbers.create(
    webhook_url="https://my-server.com/voice"  # 생략 가능
)
print(f"발급된 번호: {number.phone_number}")
# 출력: 07052351234

발급된 번호는 즉시 사용 가능합니다. 통신사 심사 대기가 없습니다. 상세한 내용은 070 번호 API 퀵스타트를 참고하세요.

번호 목록 조회

numbers = client.numbers.list()
for n in numbers:
    print(f"{n.phone_number} → webhook: {n.webhook_url}")

번호 설정 변경

client.numbers.update(
    "07052351234",
    webhook_url="https://new-server.com/voice",
)

번호 삭제

client.numbers.delete("07052351234")

Step 4: AI 에이전트로 전화 받기

가장 기본적인 인바운드 에이전트입니다. 발급받은 번호로 전화가 오면 AI가 응대합니다.

from clawops.agent import ClawOpsAgent, OpenAIRealtime
import asyncio

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

asyncio.run(agent.serve())

이 스크립트를 실행한 상태에서 해당 번호로 전화를 걸어보세요. AI가 전화를 받습니다.

agent.serve()는 에이전트가 ClawOps 서버에 직접 연결하므로 ngrok 같은 터널링 도구가 필요 없습니다.

system_prompt 잘 쓰는 법

AI의 응대 품질은 system_prompt에 달려 있습니다. 좋은 프롬프트의 구조:

system_prompt="""당신은 [회사명]의 [역할]입니다.

정보:
- 영업시간: [시간]
- 주소: [주소]
- 주요 서비스/메뉴: [목록]

규칙:
- 항상 존댓말을 사용합니다
- [특정 질문]에는 [특정 응답]으로 답합니다
- 모르는 질문은 "[안내 메시지]"로 안내합니다
- 통화 시작 시 "[인사말]"로 인사합니다
"""

자세한 프롬프트 설계법은 AI 전화 에이전트 프롬프트 엔지니어링을 참고하세요.

Step 5: AI 에이전트로 전화 걸기

에이전트가 먼저 전화를 거는 아웃바운드도 가능합니다:

from clawops.agent import ClawOpsAgent, OpenAIRealtime
import asyncio

agent = ClawOpsAgent(
    from_="07052351234",
    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())

인바운드 + 아웃바운드 동시 처리

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

asyncio.run(main())

Step 6: REST API로 전화 걸기 (에이전트 없이)

AI 에이전트 없이 REST API만으로 전화를 걸 수도 있습니다. 이 경우 VoiceML 웹훅으로 통화 흐름을 제어합니다.

from clawops import ClawOps

client = ClawOps()

# 전화 발신
call = client.calls.create(
    to="01012345678",
    from_="07052351234",
    url="https://my-server.com/voice-scenario",  # VoiceML 웹훅
    status_callback="https://my-server.com/status",
    status_callback_event="initiated ringing answered completed",
)

print(f"Call ID: {call.call_id}")
print(f"Status: {call.status}")

통화 목록 조회

page = client.calls.list(status="completed", page=0, page_size=10)
for call in page.data:
    print(f"{call.call_id} | {call.direction} | {call.duration}초")

통화 전사(트랜스크립트) 조회

state = client.calls.get_transcript("CA1a2b3c4d5e6f7890")

if state.status == "completed":
    for seg in state.segments or []:
        print(f"[{seg.speaker}] {seg.start:.2f}s  {seg.text}")
elif state.status == "pending":
    print("전사 진행 중...")

통화 요약 조회

summary = client.calls.get_summary("CA1a2b3c4d5e6f7890")

if summary.status == "completed":
    data = summary.result_json or {}
    print(data.get("coreSummary"))

Step 7: 문자 보내기

같은 070 번호로 SMS/LMS/MMS를 보낼 수 있습니다.

from clawops import ClawOps

client = ClawOps()

# SMS (단문)
msg = client.messages.create(
    to="01012345678",
    from_="07052351234",
    body="안녕하세요, ClawOps 테스트입니다.",
)
print(f"Message ID: {msg.message_id}")

LMS/MMS는 한국 SMS API 가이드에서 자세히 다룹니다.

비동기 클라이언트

대규모 처리가 필요하면 비동기 클라이언트를 사용합니다:

from clawops import AsyncClawOps
import asyncio

async def main():
    async with AsyncClawOps() as client:
        # 비동기로 전화 발신
        call = await client.calls.create(
            to="01012345678",
            from_="07052351234",
            url="https://my-server.com/voice",
        )
        print(f"Call: {call.call_id}")

        # 비동기로 문자 발송
        msg = await client.messages.create(
            to="01012345678",
            from_="07052351234",
            body="비동기 발송 테스트",
        )
        print(f"Message: {msg.message_id}")

asyncio.run(main())

에러 처리

from clawops import ClawOps, ConflictError
import httpx

client = ClawOps()

try:
    call = client.calls.create(
        to="01012345678",
        from_="07052351234",
        url="https://my-server.com/voice",
    )
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("API 키를 확인하세요")
    elif e.response.status_code == 400:
        print(f"요청 오류: {e.response.json()}")
    else:
        print(f"서버 오류: {e.response.status_code}")
except ConflictError:
    print("이미 처리된 요청입니다")

타임아웃 설정

from clawops import ClawOps

# 전체 타임아웃 (초)
client = ClawOps(timeout=30.0)

전체 요약

작업	코드
클라이언트 초기화	client = ClawOps()
번호 발급	client.numbers.create()
AI 에이전트 (인바운드)	asyncio.run(agent.serve())
AI 에이전트 (아웃바운드)	await agent.call("010...")
REST 전화 발신	client.calls.create(to=, from_=, url=)
SMS 발송	client.messages.create(to=, from_=, body=)
전사 조회	client.calls.get_transcript(call_id)

다음 단계

• Voice Agent — Tool 등록, Call Transfer, Pipeline 모드 등 에이전트 심화
• Python SDK 레퍼런스 — 전체 메서드 레퍼런스
• Node.js SDK — Node.js/TypeScript 사용자
• VoiceML — 웹훅 기반 통화 제어
• AI 전화 에이전트 프롬프트 엔지니어링

---

10분이면 AI 전화 에이전트를 만들 수 있습니다. 지금 시작하세요.