AI 에이전트

워크스페이스의 AI 에이전트 설정을 읽는 조회 API입니다. AI가 켜져 있는지, AI가 답하지 못할 때 상담원에게 넘기기까지 얼마나 기다리는지 확인할 수 있습니다.

목록 조회

GET /ai-agents — 워크스페이스의 AI 에이전트 설정을 조회합니다.

• Scope: ai-agents:read
• 쿼리: limit(기본 50, 최대 100)

AI 에이전트 설정은 워크스페이스당 1개이므로 목록은 항상 0개 또는 1개 항목을 반환합니다. 정상적으로 만든 워크스페이스에는 기본 설정이 들어 있어 1개를 반환하고, 0개(빈 배열)는 설정이 {}로 수동 초기화된 예외적인 경우에만 나옵니다. 항목의 id는 워크스페이스 ID와 같습니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/ai-agents" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "5f3e8c10-...",
      "enabled": true,
      "failover_timeout": 60,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

응답 필드

필드	타입	설명
id	string	워크스페이스 ID와 같은 값
enabled	boolean	AI 응답이 켜져 있는지 여부. 기본값은 false이며, 운영자가 AI를 직접 켜야 true가 됩니다. 위 예시의 true는 AI를 켠 워크스페이스의 경우입니다.
failover_timeout	integer	AI 응답을 기다린 뒤 상담원에게 넘기기까지의 시간(초). AI가 켜져 있으면 10~300 범위입니다. AI가 꺼져 있거나 설정에 값이 없으면 0이 올 수 있으니 0을 오류로 처리하지 마세요.
created_at	string	생성 시각(RFC3339)
updated_at	string	마지막 수정 시각(RFC3339)

항목이 하나뿐이므로 meta.has_more는 항상 false이고 next_cursor는 반환하지 않습니다.

프롬프트 본문(prompt_template)과 LLM API 키(model_api_key)는 민감 정보라서 응답에 포함하지 않습니다.

오류

HTTP	code	발생 조건
400	INVALID_QUERY	limit이 1~100 범위를 벗어남(값을 보정하지 않습니다)

공통 오류는 에러 문서를 참고하세요.