에이전트 생성

POST

https://api.claw-ops.com/v1/accounts/:accountId/agents

POST

/v1/accounts/:accountId/agents

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

{
  "agentId": "cmagent123",
  "name": "고객 지원 에이전트",
  "instructions": "당신은 친절하고 유능한 한국어 음성 에이전트입니다. 사용자의 요청을 주의 깊게 듣고 정확하고 간결하게 답하세요.",
  "greeting": true,
  "language": "ko",
  "maxDurationSeconds": null,
  "beginMessageDelayMs": 0,
  "liveEvents": {
    "events": [
      "transcript.final",
      "dtmf.received"
    ]
  },
  "idle": {
    "enabled": true,
    "timeout": 8,
    "prompt": "여보세요?",
    "maxNudges": 1
  },
  "model": "gpt-realtime-2.1-mini",
  "voice": "7706804e-ea85-443a-968a-b9bf363bdde8",
  "voiceProvider": "cartesia",
  "voiceModel": "sonic-3.5",
  "configuration": {
    "outputMode": "realtime_voice",
    "language": "string",
    "knowledge": {
      "enabled": true,
      "topK": 1
    },
    "stt": {
      "provider": "openai",
      "model": "gpt-4o-transcribe",
      "language": "string",
      "prompt": "string",
      "temperature": 0.5,
      "detect_language": true,
      "noise_reduction_type": "near_field",
      "use_realtime": true
    },
    "llm": {
      "provider": "string",
      "model": "string",
      "voice": "string"
    },
    "tts": {
      "provider": "cartesia",
      "model": "sonic-3.5",
      "voice": "string",
      "language": "string",
      "speed": 1.1,
      "volume": 1.1
    },
    "vad": {
      "provider": "silero",
      "min_silence_duration": 1.1,
      "min_speech_duration": 0.5,
      "prefix_padding_duration": 1.1,
      "max_buffered_speech": 1.1,
      "activation_threshold": 0.5,
      "sample_rate": 16000,
      "force_cpu": true
    },
    "session": {
      "turn_detection": "vad",
      "allow_interruptions": true,
      "min_endpointing_delay": 1.1,
      "max_endpointing_delay": 1.1,
      "min_interruption_duration": 1.1
    }
  },
  "phoneNumbers": [
    "07012340001"
  ],
  "dateCreated": "2024-01-15T09:30:00Z",
  "dateUpdated": "2024-01-15T09:30:00Z"
}

name만으로 바로 통화 가능한 한국어 실시간 음성 에이전트를 생성합니다. instructions, greeting, model, voice를 생략하면 한국AI통신 기본값이 적용됩니다. API 기본 출력은 GPT Realtime 2.1 mini + Cartesia sonic-3.5 + Minji 음성입니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.

namestringRequired1-80 characters

instructionsstringOptional<=16000 characters

생략하면 한국AI통신의 범용 한국어 음성 에이전트 프롬프트가 적용됩니다.

greetingbooleanOptionalDefaults to true

통화 연결 직후 에이전트가 먼저 인사할지 여부

maxDurationSecondsinteger or nullOptional10-7200

최대 통화 시간(초). 통화가 연결된 뒤 이 시간이 지나면 대화 중이어도 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. 끊기 전 안내 멘트는 나가지 않습니다. 생략하거나 null 이면 제한 없음입니다.

beginMessageDelayMsinteger or nullOptional0-5000

첫 인사 전 대기 시간(밀리초). 발신 통화에서 상대가 받은 뒤 이 시간만큼 기다렸다가 첫 인사를 시작합니다. greeting 이 true 일 때만 적용되며, 수신 통화에는 적용되지 않습니다. 생략하면 0(바로 인사)입니다.

liveEventsobjectOptional

통화 중 이벤트(실시간 전사·키패드) 설정. 받을 이벤트를 events 에 고르면 이 에이전트의 통화 이벤트를 GET /v1/accounts/{accountId}/calls/{callId}/live-events(·/stream) 로 받습니다. 추가 요금은 없습니다.

idleobjectOptional

무응답 처리 설정. 조회한 idle 을 그대로 보내도 되고, 바꿀 칸만 보내도 됩니다. 보내지 않은 칸은 기존 값을 유지합니다. 새 에이전트에서 보내지 않은 칸은 enabled false, timeout 8, prompt 「여보세요?」, maxNudges 1 입니다.

modelenumOptional

생략하면 gpt-realtime-2.1-mini가 적용됩니다.

Allowed values:

voicestringOptionalformat: "uuid"

Cartesia voice ID. 생략하면 Minji - Modern Communicator (7706804e-ea85-443a-968a-b9bf363bdde8)가 적용됩니다.

configurationobjectOptional

모델 내장 음성, Realtime + 외부 TTS, STT·LLM·TTS 파이프라인 또는 GPT-Live(전이중)의 전체 실행 설정입니다. 지정하면 model과 voice 단축 필드는 함께 사용할 수 없습니다.

Response

생성 성공

agentIdstring

에이전트 ID

namestring

instructionsstring

에이전트 시스템 프롬프트

greetingboolean

통화 연결 직후 에이전트가 먼저 인사할지 여부

languagestring

에이전트 기본 언어

maxDurationSecondsinteger or null10-7200

통화가 연결된 뒤 이 시간(초)이 지나면 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. null 이면 제한 없음입니다. 시간이 되면 대화 중이어도 끊으며, 끊기 전 안내 멘트는 나가지 않습니다.

beginMessageDelayMsinteger0-5000

발신 통화에서 상대가 받은 뒤 첫 인사를 시작하기 전에 기다리는 시간(밀리초)입니다. 0 이면 바로 인사합니다. greeting 이 true 일 때만 적용되며, 수신 통화에는 적용되지 않습니다.

liveEventsobject

idleobject

무응답 처리 설정. 양쪽 다 말이 없는 시간이 timeout 초 이어지면 에이전트가 대화 상태를 보고 다시 묻거나 통화를 끊습니다. 설정한 적 없는 에이전트는 기본값(enabled: false)으로 나옵니다.

modelstring

현재 에이전트가 사용하는 LLM 모델

voicestring or null

현재 음성 ID

voiceProviderstring or null

음성 출력 제공자

voiceModelstring or null

외부 TTS 모델. 모델 내장 음성에서는 null입니다.

configurationobject

phoneNumberslist of strings

이 에이전트에 착신 연결된 전화번호

dateCreateddatetime

dateUpdateddatetime

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error