에이전트 수정

PATCH

agents

{agent_id}

curl --request PATCH \
  --url https://client-api.tryvox.co/v3/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated support agent",
  "expected_head_revision": 42
}
'

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "single_prompt",
  "created_at": 123,
  "updated_at": 123,
  "evaluate": false,
  "production_version": "<string>",
  "data": {
    "runtime": {
      "type": "pipeline"
    },
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1,
      "reasoningEffort": "none",
      "thinkingBudget": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "isAllowInterruption": true,
      "responsiveness": 1,
      "boostedKeywords": "<string>",
      "isAllowTurnDetection": true,
      "vadMinSilenceDuration": 0.5
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfInterruptible": false,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3,
      "callScreening": {
        "promptType": "static",
        "staticSentence": "<string>",
        "prompt": "<string>",
        "endCallAfterResponse": false
      }
    },
    "chatSettings": {
      "silenceChatTimeoutInSeconds": 3600
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "type": "string",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": [
          "recording"
        ]
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "webhookVersion": "v1",
      "enableAlimtalkOnCallEnd": false,
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "takeoverTranscription": true,
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "end_call",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": true,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ],
    "manuals": {}
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "data": {
          "name": "<string>",
          "globalNodeSettings": {
            "isGlobalNode": false,
            "transitionCondition": "<string>"
          },
          "transitions": [
            {
              "id": "<string>",
              "condition": "<string>",
              "isSkipUserResponse": true,
              "isFallback": true,
              "isGlobalTransition": true
            }
          ],
          "firstLineType": "aiFirst",
          "pauseBeforeSpeakingSeconds": 2.5
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "type": "custom",
        "sourceHandle": "<string>"
      }
    ]
  },
  "flow": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "position": {
          "x": 123,
          "y": 123
        },
        "data": {
          "first_line_type": "aiFirst",
          "name": "<string>",
          "pause_before_speaking_seconds": 2.5
        }
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "ai",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "v1",
    "is_production": true,
    "created_at": 123,
    "description": "<string>",
    "manuals_captured_at": 123,
    "manuals_capture_kind": "<string>"
  },
  "head_revision": 123,
  "flow_revision": 123,
  "restored_from_version": "<string>",
  "validation_message": "",
  "validation_issues": [
    {
      "message": "<string>",
      "field": "<string>",
      "code": "<string>",
      "rule": "<string>",
      "node_id": "<string>",
      "impact": "node",
      "suggestion": {},
      "doc": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Path Parameters

agent_id

string<uuid>

required

agent_id로 반환되는 에이전트 UUID입니다.

Body

application/json

에이전트 수정 요청 본문입니다. 변경할 필드만 보냅니다. flow 그래프는 권장 경로인 flow로 작성하고, 기존 flow_data는 호환용입니다.

에이전트 수정 요청입니다.

최소 1개 필드를 보내야 합니다.
필드를 생략하면 기존 값을 유지합니다.
type은 생성 시에만 정할 수 있습니다.
flow를 보내면 플로우 에이전트의 그래프를 교체합니다. flow_data는 호환용 deprecated builder shape입니다.
data.builtInTools를 보내면 기본 도구 목록 전체를 교체합니다.

expected_head_revision

integer

선택 사항입니다. 마지막으로 조회한 에이전트 head_revision입니다. 보내면 그 뒤 에이전트가 바뀌었을 때 409 REVISION_CONFLICT로 거부합니다. 생략하면 현재 리비전 기준으로 저장합니다.

Required range: x >= 0

evaluate

boolean

에이전트 평가 설정입니다. 생략하면 기존 값을 유지합니다.

expected_flow_revision

integer | null

선택 사항입니다. 마지막으로 조회한 Flow flow_revision입니다. 생략하면 현재 Flow 기준으로 저장합니다.

Required range: x >= 0

name

string

새 에이전트 이름입니다. 현재 이름을 유지하려면 필드를 생략합니다. null은 거부됩니다.

Required string length: 1 - 255

data

AgentDataUpdate · object

에이전트 설정 수정 요청입니다. 구조는 agent-schema/agent-data-update에 공개되어 있습니다. 생략한 상위 설정은 유지됩니다. builtInTools를 보내면 도구 목록 전체를 교체하므로, 기존 도구 객체에서 보존할 값을 유지한 전체 목록을 보내야 합니다.

Show child attributes

flow_data

FlowData · object

deprecated

지원 종료 예정 필드입니다. 플로우 그래프 PATCH 페이로드를 예전 형식으로 담으며, 기존 호환을 위해 유지됩니다. 새 통합은 flow를 사용하세요. 전체 그래프를 교체하며, 생략하면 현재 그래프가 유지됩니다.

Show child attributes

flow

Flow · object

플로우 그래프 PATCH 페이로드입니다. 지원 종료 예정인 flow_data 대신 이 필드를 사용하세요. 전체 그래프를 교체하며, 생략하면 현재 그래프가 유지됩니다. null을 보내면 거부됩니다(의미 없는 no-op이 되기 때문). 필드를 생략하세요. flow와 flow_data를 함께 보내면 flow가 사용되고 flow_data는 무시됩니다. 정확한 형태는 flow-schema/flow-data 스키마 엔드포인트에 공개됩니다.

Show child attributes

Response

성공 응답

에이전트 생성·수정 응답입니다. AgentResponse에 저장 시 검증 결과인 validation_message와 validation_issues를 포함합니다.

agent_id

string<uuid>

required

에이전트 UUID입니다.

name

string

required

에이전트 이름입니다. 버전 스냅샷을 조회하더라도 현재 최상위 이름을 반환합니다.

type

enum<string>

required

선택한 구성의 타입입니다. single_prompt 또는 flow입니다.

Available options:

single_prompt,

flow

created_at

integer

required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

updated_at

integer

required

리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다.

evaluate

boolean

default:false

현재 평가 설정입니다. 버전 스냅샷에는 포함되지 않습니다.

production_version

string | null

현재 게시된 production 버전입니다. 없으면 null입니다.

data

AgentDataResponse · object

선택된 에이전트 설정 스냅샷입니다. 구조는 agent-schema/agent-data-response에 공개되어 있습니다.

Show child attributes

flow_data

FlowData · object | null

deprecated

지원 종료 예정 필드입니다. 에이전트의 플로우 그래프를 예전 형식으로 담고 있으며, 기존 호환을 위해 유지됩니다. 읽기 전용이고, flow 에이전트에서는 값이 있고 single_prompt 에이전트에서는 null입니다. 새 통합은 flow를 사용하세요. 이 필드는 지원 종료 기간 이후 제거됩니다.

Show child attributes

flow

Flow · object | null

에이전트의 플로우 그래프입니다. nodes를 edges로 연결하고, 각 edge가 분기 조건을 가집니다. flow 에이전트에서는 값이 있고 single_prompt 에이전트에서는 null입니다. 지원 종료 예정인 flow_data 대신 이 필드를 사용하세요. 정확한 형태는 flow-schema/flow-data 스키마 엔드포인트에 공개됩니다.

Show child attributes

version

AgentVersionMeta · object | null

스냅샷 조회 시에만 populated (version=v{n} 또는 production).

Show child attributes

head_revision

integer | null

현재 편집본의 리비전입니다. 고정 버전을 조회하면 null입니다.

flow_revision

integer | null

현재 Flow 리비전입니다. 프롬프트 에이전트이거나 고정 버전을 조회하면 null입니다.

restored_from_version

string | null

validation_message

string

default:""

저장 시 발생한 플로우 경고를 줄바꿈으로 구분한 요약입니다. 경고가 없으면 빈 문자열입니다. 생성·수정 응답에만 포함되며, GET 응답은 이 필드가 없는 AgentResponse를 사용합니다.

validation_issues

FlowValidationErrorItem · object[]

저장 시 검증 결과입니다. 규칙, 노드 ID, 영향 범위와 세부 정보를 포함합니다.

Show child attributes

curl --request PATCH \
  --url https://client-api.tryvox.co/v3/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated support agent",
  "expected_head_revision": 42
}
'

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "single_prompt",
  "created_at": 123,
  "updated_at": 123,
  "evaluate": false,
  "production_version": "<string>",
  "data": {
    "runtime": {
      "type": "pipeline"
    },
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1,
      "reasoningEffort": "none",
      "thinkingBudget": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "isAllowInterruption": true,
      "responsiveness": 1,
      "boostedKeywords": "<string>",
      "isAllowTurnDetection": true,
      "vadMinSilenceDuration": 0.5
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfInterruptible": false,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3,
      "callScreening": {
        "promptType": "static",
        "staticSentence": "<string>",
        "prompt": "<string>",
        "endCallAfterResponse": false
      }
    },
    "chatSettings": {
      "silenceChatTimeoutInSeconds": 3600
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "type": "string",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": [
          "recording"
        ]
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "webhookVersion": "v1",
      "enableAlimtalkOnCallEnd": false,
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "takeoverTranscription": true,
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "end_call",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": true,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ],
    "manuals": {}
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "data": {
          "name": "<string>",
          "globalNodeSettings": {
            "isGlobalNode": false,
            "transitionCondition": "<string>"
          },
          "transitions": [
            {
              "id": "<string>",
              "condition": "<string>",
              "isSkipUserResponse": true,
              "isFallback": true,
              "isGlobalTransition": true
            }
          ],
          "firstLineType": "aiFirst",
          "pauseBeforeSpeakingSeconds": 2.5
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "type": "custom",
        "sourceHandle": "<string>"
      }
    ]
  },
  "flow": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "position": {
          "x": 123,
          "y": 123
        },
        "data": {
          "first_line_type": "aiFirst",
          "name": "<string>",
          "pause_before_speaking_seconds": 2.5
        }
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "ai",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "v1",
    "is_production": true,
    "created_at": 123,
    "description": "<string>",
    "manuals_captured_at": 123,
    "manuals_capture_kind": "<string>"
  },
  "head_revision": 123,
  "flow_revision": 123,
  "restored_from_version": "<string>",
  "validation_message": "",
  "validation_issues": [
    {
      "message": "<string>",
      "field": "<string>",
      "code": "<string>",
      "rule": "<string>",
      "node_id": "<string>",
      "impact": "node",
      "suggestion": {},
      "doc": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

통화

상담사 통화

에이전트

에이전트 버전

도구

지식 베이스

메뉴얼

모델

스키마

보유 전화번호

전화번호 자원

발신표기번호

차단 번호

대량 발신

시트

위젯

SMS

파일

고객

고객 속성 정의

메모리

알림

워크스페이스

하위 워크스페이스 API 키

워크스페이스 인증

네이버톡톡

Authorizations

Path Parameters

Body

Response