에이전트 수정

PATCH

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

PATCH

/v1/accounts/:accountId/agents/:agentId

curl -X PATCH https://api.claw-ops.com/v1/accounts/accountId/agents/agentId \
     -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"
}

에이전트 이름과 주요 실시간 음성 설정을 수정합니다. model은 OpenAI Realtime 에이전트, voice는 Cartesia 외부 TTS 에이전트에서 변경할 수 있습니다. 그 외 구성은 대시보드에서 변경합니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

agentIdstringRequired

에이전트 ID

Request

This endpoint expects an object.

namestringOptional1-80 characters

instructionsstringOptional<=16000 characters

greetingbooleanOptional

maxDurationSecondsinteger or nullOptional10-7200

최대 통화 시간(초). 통화가 연결된 뒤 이 시간이 지나면 대화 중이어도 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. null 이면 제한을 끄고, 생략하면 기존 값을 그대로 둡니다.

beginMessageDelayMsinteger or nullOptional0-5000

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

liveEventsobjectOptional

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

idleobjectOptional

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

modelenumOptional

Allowed values:

voicestringOptionalformat: "uuid"

Cartesia voice ID

configurationobjectOptional

에이전트 실행 설정 전체를 교체합니다. 지정하면 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

404

Not Found Error

409

Conflict Error