가이드

에이전트

View as Markdown

에이전트는 전화를 받고 실시간으로 대화하는 AI 음성 상담원입니다. 간단하게 이름만 입력해 시작하거나, 모델 내장 음성부터 STT·LLM·TTS 파이프라인까지 통화 처리 방식을 직접 구성할 수 있습니다.

빠르게 생성하기

새 에이전트를 만들 때 필요한 필드는 name 하나뿐입니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"name": "지원 에이전트"}'

생략된 필드에는 다음 기본값이 적용됩니다.

항목기본값
역할 지침범용 한국어 음성 에이전트 프롬프트
먼저 인사하기true
출력 방식external_tts
LLMOpenAI Realtime gpt-realtime-2.1-mini
TTSCartesia sonic-3.5
음성Minji - Modern Communicator
언어ko
지식 검색사용 안 함

응답의 agentId는 에이전트를 조회·수정하거나 전화번호에 연결할 때 사용합니다. 기본 생성으로 먼저 통화를 확인한 뒤 필요한 경우 아래의 상세 구성을 적용하세요.

음성 처리 방식 선택

ClawOps 에이전트는 세 가지 출력 방식을 지원합니다.

outputMode처리 구조언제 사용하나요?
realtime_voiceOpenAI Realtime 모델이 음성을 직접 인식하고 생성가장 낮은 지연이 중요할 때
external_ttsOpenAI Realtime → 외부 TTSRealtime 대화에 Cartesia 또는 xAI 음성을 사용할 때
pipelineOpenAI STT → OpenAI LLM → 외부 TTSSTT·LLM·VAD와 끼어들기를 각각 조정할 때

어떤 방식을 선택할지 확실하지 않다면 기본값인 external_tts를 유지하세요.

생성 요청

POST /v1/accounts/{accountId}/agents

공통 필드

필드타입설명
namestring필수. 에이전트 이름입니다. 최대 80자입니다.
instructionsstring역할, 말투와 업무 규칙을 지정하는 시스템 프롬프트입니다. 최대 16,000자입니다.
greetingboolean통화 연결 직후 에이전트가 먼저 인사할지 지정합니다. 기본값은 true입니다.
modelstring기본 Realtime 구성을 위한 단축 필드입니다.
voiceUUID기본 Cartesia 구성을 위한 음성 단축 필드입니다.
configurationobjectSTT·LLM·TTS·VAD와 세션 옵션을 포함하는 전체 실행 설정입니다.

configuration을 사용하면 model과 voice 단축 필드는 함께 보낼 수 없습니다.

모델 내장 음성

OpenAI Realtime 모델이 음성 인식과 음성 생성을 함께 처리합니다. 별도의 STT와 TTS가 없으므로 구성이 간단합니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "예약 안내 에이전트",
>    "instructions": "예약 가능 시간을 확인하고 간결하게 안내하세요.",
>    "configuration": {
>      "outputMode": "realtime_voice",
>      "llm": {
>        "provider": "openai-realtime",
>        "model": "gpt-realtime-2.1",
>        "voice": "marin"
>      }
>    }
>  }'

Realtime 모델

값용도
gpt-realtime-2.1-mini낮은 지연과 비용을 우선하는 일반적인 통화
gpt-realtime-2.1더 높은 품질이 필요한 복잡한 대화

OpenAI 내장 음성

marin, cedar, alloy, ash, ballad, coral, echo, sage, shimmer, verse를 사용할 수 있습니다.

Realtime과 외부 TTS

OpenAI Realtime 모델이 대화를 처리하고 외부 TTS가 최종 음성을 생성합니다. 기본 생성 방식이며, Cartesia 한국어 음성이나 xAI 음성을 사용할 수 있습니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "고객 지원 에이전트",
>    "instructions": "고객의 문제를 확인하고 해결 절차를 정중하게 안내하세요.",
>    "configuration": {
>      "outputMode": "external_tts",
>      "llm": {
>        "provider": "openai-realtime",
>        "model": "gpt-realtime-2.1-mini"
>      },
>      "tts": {
>        "provider": "cartesia",
>        "model": "sonic-3.5",
>        "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
>        "speed": 1.0,
>        "volume": 1.0
>      }
>    }
>  }'

TTS 제공자

제공자모델음성 값추가 설정
cartesiasonic-3.5Cartesia voice UUIDspeed, volume
xaitts-1xAI voice ID별도 튜닝 필드 없음

Cartesia 음성 튜닝

필드타입범위설명
speednumber0.6–1.5말 속도입니다. 1.0이 기본 속도입니다.
volumenumber0.5–1.5음량입니다. 1.0이 기본 음량입니다.
languagestring—생략하면 에이전트 언어를 사용합니다. 기본값은 ko입니다.

sonic-3.5에서 speed는 문자열 프리셋이 아닌 숫자로 입력해야 합니다.

에이전트 음성 조회

에이전트의 TTS 설정에 사용할 수 있는 음성을 조회합니다.

GET /v1/accounts/{accountId}/agents/voices
$curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/voices" \
>  -H "Authorization: Bearer YOUR_API_KEY"

응답의 data[].id를 configuration.tts.voice 또는 voice에 사용합니다. isCustom이 true이면 현재 계정에서 등록한 음성입니다. 다른 계정에서 복제한 음성은 사용할 수 없습니다.

Cartesia

ClawOps 기본 한국어 음성과 현재 계정에서 복제해 등록한 음성을 제공합니다. 아래 재생 버튼을 누르면 웹의 음성 선택 화면과 같은 기본 음성 샘플을 들어볼 수 있습니다.

이름Voice ID미리듣기
Haeun - Polished Presence4dd4630e-19e0-4243-bca0-676ff85119b7
Taehyun - Friendly Hoste1717dc3-b87b-4720-aa7f-b6db290e0609
Jaewon - Steady Advisor89f4372f-1f73-4b85-8e1e-5d24ed8bc826
Jihyun - Anchorwoman304fdbd8-65e6-40d6-ab78-f9d18b9efdf9
Seoyun - Warm Guidece9ca2b6-2bed-4452-99bb-052e1ec0b534
Subin - Elegant Speakera0fc16d3-01af-482b-910f-ed063c3d79d3
Minji - Modern Communicator7706804e-ea85-443a-968a-b9bf363bdde8
Soyeon - Bright Companion69c18e1d-fab0-4747-b9da-58617cd8b9e4
Hyerin - Graceful Host90dba946-774b-40ed-98d9-ac3835117827
Jiwoo - Service Specialist15628352-2ede-4f1b-89e6-ceda0c983fbc
Minho - Friendly Spirit537a82ae-4926-4bfb-9aec-aff0b80a12a5
Ryeowook - Easygoing Palf7755efb-1848-4321-aa22-5e5be5d32486
Soojin - Helpful Tonecd6c48a9-774b-4397-98b4-9948c0a790f0
Yuna - Kind Unniecac92886-4b7c-4bc1-a524-e0f79c0381be

계정에서 복제한 커스텀 음성의 샘플은 인증된 사용자만 접근할 수 있습니다. 커스텀 음성은 ClawOps 대시보드의 에이전트 음성 선택 화면에서 미리듣습니다.

STT·LLM·TTS 파이프라인

음성 인식, 대화 모델과 음성 합성을 각각 선택합니다. 발화 감지와 끼어들기 동작까지 조정해야 하는 고급 구성에 적합합니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "전문 상담 에이전트",
>    "instructions": "상품명과 고객 이름을 정확하게 확인하며 상담하세요.",
>    "configuration": {
>      "outputMode": "pipeline",
>      "language": "ko",
>      "stt": {
>        "provider": "openai",
>        "model": "gpt-4o-transcribe",
>        "prompt": "ClawOps, VoiceML",
>        "noise_reduction_type": "far_field",
>        "use_realtime": true
>      },
>      "llm": {
>        "provider": "openai",
>        "model": "gpt-5.6-terra",
>        "verbosity": "low",
>        "max_completion_tokens": 300
>      },
>      "tts": {
>        "provider": "cartesia",
>        "model": "sonic-3.5",
>        "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
>        "speed": 1.05
>      },
>      "vad": {
>        "provider": "silero",
>        "min_silence_duration": 0.55,
>        "activation_threshold": 0.5
>      },
>      "session": {
>        "turn_detection": "vad",
>        "allow_interruptions": true,
>        "min_endpointing_delay": 0.3
>      }
>    }
>  }'

STT 설정

현재 파이프라인 STT 제공자는 openai입니다.

필드타입값·범위설명
modelstringgpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1음성 인식 모델
languagestring기본 ko인식 언어
promptstring선택이름, 상품명과 같은 인식 힌트
temperaturenumber0–1인식 샘플링 온도
detect_languageboolean선택언어 자동 감지
noise_reduction_typestringnear_field, far_field마이크 거리에 맞춘 노이즈 억제
use_realtimeboolean선택스트리밍 STT 사용 여부

파이프라인 LLM

사용 가능한 모델은 다음과 같습니다.

  • GPT-5.6: gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra
  • GPT-5 계열: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano
  • GPT-4.1 계열: gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
  • GPT-4o 계열: gpt-4o, gpt-4o-mini
필드타입값·범위설명
temperaturenumber0–2응답의 무작위성
top_pnumber0–1Nucleus sampling 범위
verbositystringlow, medium, highGPT-5 계열 응답 상세도
max_completion_tokensinteger1 이상최대 생성 토큰
frequency_penaltynumber-2–2반복 억제
presence_penaltynumber-2–2새로운 주제 유도
service_tierstringauto, default, flex, scale, priority처리 티어
parallel_tool_callsboolean선택병렬 도구 호출 허용
seedinteger선택결정적 샘플링용 시드

GPT-5 계열 파이프라인 모델은 통화 도구와 함께 안정적으로 동작하도록 reasoning_effort: "none"이 자동 적용됩니다.

VAD 설정

현재 VAD 제공자는 silero입니다. vad를 생략하면 런타임 기본값을 사용합니다.

필드타입범위설명
min_silence_durationnumber0–3초이만큼 침묵하면 발화가 끝난 것으로 판단합니다.
min_speech_durationnumber0–1초이보다 짧은 소리를 발화에서 제외합니다.
prefix_padding_durationnumber0–2초감지된 발화 앞에 포함할 여유 구간입니다.
max_buffered_speechnumber1–120초버퍼링할 최대 발화 길이입니다.
activation_thresholdnumber0–1음성으로 판단하는 확률 임계값입니다.
sample_rateinteger16000, 8000VAD 입력 샘플레이트입니다.
force_cpuboolean선택CPU에서 VAD를 실행합니다.

대화 세션 설정

필드타입값·범위설명
turn_detectionstringvad, stt발화 종료 판단 방식
allow_interruptionsboolean선택사용자가 에이전트의 말을 끊을 수 있는지 지정
min_endpointing_delaynumber0–5초발화 종료 전 최소 대기
max_endpointing_delaynumber0–15초발화 종료 전 최대 대기
min_interruption_durationnumber0–2초끼어들기로 인정할 최소 발화 길이

지식 등록과 검색

회사 소개, 상품 안내와 운영 정책처럼 에이전트가 정확하게 참고해야 할 자료를 등록할 수 있습니다. 지식 문서 등록과 지식 검색 활성화가 모두 완료되어야 통화 중 문서를 검색합니다.

지식 문서 등록

먼저 에이전트를 생성해 {agentId}를 준비합니다. 텍스트를 바로 등록하거나 파일을 업로드할 수 있습니다.

텍스트 등록

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}/knowledge" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"title": "환불 정책", "text": "환불은 결제일로부터 7일 이내에 요청할 수 있습니다."}'

파일 등록

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}/knowledge" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -F "title=환불 정책" \
>  -F "file=@./refund-policy.pdf"

.txt, .text, .md, .markdown과 텍스트 기반 .pdf 파일을 지원합니다. 파일은 한 번에 한 개씩, 최대 10MB까지 업로드할 수 있으며 추출된 텍스트는 최대 200,000자여야 합니다. 스캔 PDF와 이미지의 OCR은 지원하지 않습니다.

등록 요청 안에서 텍스트 추출, 문서 분할과 검색용 임베딩 생성을 완료합니다. 201 Created 응답의 documentId를 재색인하거나 삭제할 때 사용합니다.

지식 문서 목록

$curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}/knowledge" \
>  -H "Authorization: Bearer YOUR_API_KEY"

각 문서의 status, charCount, chunkCount와 embeddingModel을 확인할 수 있습니다.

지식 문서 재색인

저장된 원문을 현재 분할 규칙과 임베딩 모델로 다시 색인합니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}/knowledge/{documentId}/reindex" \
>  -H "Authorization: Bearer YOUR_API_KEY"

지식 문서 삭제

문서와 해당 문서에서 생성된 검색용 문서 조각을 함께 삭제합니다.

$curl -X DELETE "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}/knowledge/{documentId}" \
>  -H "Authorization: Bearer YOUR_API_KEY"

지식 검색 활성화

모든 출력 방식에서 configuration.knowledge로 지식 검색 사용 여부와 한 번에 참고할 문서 조각 수를 설정할 수 있습니다.

1{
2  "knowledge": {
3    "enabled": true,
4    "topK": 5
5  }
6}
필드타입설명
enabledbooleantrue이면 통화 중 필요한 순간에 등록된 지식을 검색합니다. 기본값은 false입니다.
topKinteger질문마다 참고할 문서 조각 수입니다. 1–10, 기본값은 5입니다.

topK가 크면 더 넓은 내용을 참고하지만 응답이 느려지고 관련성이 낮은 내용이 포함될 수 있습니다. 먼저 기본값 5로 테스트한 뒤 조정하세요.

응답 구성

생성·조회·수정 응답에는 간단한 요약 필드와 전체 configuration이 함께 반환됩니다.

1{
2  "agentId": "cmagent123",
3  "name": "지원 에이전트",
4  "instructions": "고객 문의를 친절하게 안내하세요.",
5  "greeting": true,
6  "language": "ko",
7  "model": "gpt-realtime-2.1-mini",
8  "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
9  "voiceProvider": "cartesia",
10  "voiceModel": "sonic-3.5",
11  "configuration": {
12    "outputMode": "external_tts",
13    "language": "ko",
14    "knowledge": {
15      "enabled": false,
16      "topK": 5
17    },
18    "stt": null,
19    "llm": {
20      "provider": "openai-realtime",
21      "model": "gpt-realtime-2.1-mini"
22    },
23    "tts": {
24      "provider": "cartesia",
25      "model": "sonic-3.5",
26      "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
27      "language": "ko"
28    },
29    "vad": null,
30    "session": null
31  },
32  "phoneNumbers": [],
33  "dateCreated": "2026-07-30T04:00:00.000Z",
34  "dateUpdated": "2026-07-30T04:00:00.000Z"
35}

model, voice, voiceProvider, voiceModel은 목록 화면과 단순 연동을 위한 요약입니다. 세부 설정을 읽을 때는 configuration을 사용하세요.

에이전트로 전화 걸기

생성 응답의 agentId를 발신 API의 AgentId로 보내면, 전화번호 라우팅 설정과 관계없이 해당 매니지드 에이전트가 통화를 처리합니다.

$export CLAWOPS_ACCOUNT_ID="YOUR_ACCOUNT_ID"
$export CLAWOPS_API_KEY="YOUR_API_KEY"
$export CLAWOPS_FROM="07012345678"
$export CLAWOPS_TO="01012345678"
$export CLAWOPS_AGENT_ID="YOUR_AGENT_ID"
$
$curl -X POST "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/calls" \
>  -H "Authorization: Bearer ${CLAWOPS_API_KEY}" \
>  -H "Content-Type: application/json" \
>  -d "{
>    \"To\": \"${CLAWOPS_TO}\",
>    \"From\": \"${CLAWOPS_FROM}\",
>    \"AgentId\": \"${CLAWOPS_AGENT_ID}\",
>    \"Timeout\": 60
>  }"

From은 같은 계정에 등록되고 통신사 발신 등록까지 끝난 번호여야 합니다. To와 From에 같은 번호를 넣는 자체 발신은 통신망에서 실패할 수 있으므로 서로 다른 번호를 사용하세요. To도 ClawOps 번호라면 routingType에 맞는 agentId, callFlowId, SIP 대상 또는 유효한 webhookUrl이 설정되어 있어야 합니다.

Url, AgentId, CallFlowId는 서로 배타적입니다. 셋을 모두 생략하면 From 번호에 연결된 Agent SDK 모드로 동작하며, 연결된 SDK가 없으면 409가 반환됩니다. Variables는 CallFlowId 모드에서만 사용할 수 있습니다.

201 Created와 응답의 queued는 발신 요청이 접수됐다는 뜻이며 통화 연결 성공을 보장하지 않습니다. 반환된 callId를 조회해 ringing, in-progress 또는 최종 상태를 확인하세요. completed만 실제 연결 후 정상 종료를 의미하며, failed는 시스템 또는 통신망 오류입니다.

$curl "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/calls/{callId}" \
>  -H "Authorization: Bearer ${CLAWOPS_API_KEY}"

진행 중인 통화를 종료할 때는 Status에 completed를 보냅니다. canceled는 제어 API의 허용 값이 아닙니다.

$curl -X POST "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/calls/{callId}" \
>  -H "Authorization: Bearer ${CLAWOPS_API_KEY}" \
>  -H "Content-Type: application/json" \
>  -d '{"Status": "completed"}'

에이전트 목록 조회

계정에 속한 에이전트를 최신 생성 순으로 조회합니다.

$curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents" \
>  -H "Authorization: Bearer YOUR_API_KEY"

응답의 data 배열에 에이전트가 반환됩니다.

에이전트 조회

에이전트 한 개의 전체 설정과 연결된 전화번호를 조회합니다.

$curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}" \
>  -H "Authorization: Bearer YOUR_API_KEY"

에이전트 수정

이름, 지침과 기본 Realtime·Cartesia 설정은 필요한 필드만 보낼 수 있습니다.

$curl -X PATCH "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"instructions": "예약 요청을 확인하고 필요한 정보를 정중하게 안내하세요."}'

출력 방식이나 STT·LLM·TTS 구성을 변경할 때는 configuration 전체를 전송합니다. 이 경우 기존 configuration을 부분 병합하지 않고 새 설정으로 교체합니다. 같은 요청에 포함한 instructions와 greeting은 새 구성에도 반영됩니다.

$curl -X PATCH "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "configuration": {
>      "outputMode": "external_tts",
>      "knowledge": {
>        "enabled": true,
>        "topK": 5
>      },
>      "llm": {
>        "provider": "openai-realtime",
>        "model": "gpt-realtime-2.1-mini"
>      },
>      "tts": {
>        "provider": "cartesia",
>        "model": "sonic-3.5",
>        "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
>        "speed": 0.9,
>        "volume": 1.1
>      }
>    }
>  }'

전화번호에 연결

발급한 전화번호의 라우팅을 agent로 변경하면 인바운드 전화를 에이전트가 받습니다.

$curl -X PUT "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/numbers/{number}" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"routingType": "agent", "agentId": "{agentId}"}'

전화번호와 에이전트는 같은 ClawOps 계정에 속해야 합니다. 연결된 번호는 에이전트 응답의 phoneNumbers에서 확인할 수 있습니다.

에이전트 삭제

$curl -X DELETE "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/agents/{agentId}" \
>  -H "Authorization: Bearer YOUR_API_KEY"

착신 번호에 연결된 에이전트는 삭제할 수 없습니다. 먼저 해당 번호의 라우팅을 다른 대상으로 변경해야 합니다. 삭제에 성공하면 204 No Content가 반환됩니다.