soultrace-ai/soultrace-skill

SoulTrace 성격 평가

soultrace API를 통해 적응형 성격 평가를 진행합니다. 1~7점 Likert 척도로 24개의 질문에 답하고 5가지 색상 심리 모델을 기반으로 한 성격 원형을 받아보세요.

API 엔드포인트

POST https://soultrace.app/api/agent

인증이 필요하지 않습니다. IP당 시간당 100회 요청으로 제한됩니다.

작동 방식

API는 무상태(stateless) 방식입니다. 모든 요청에 누적된 답변을 전달하면 서버가 베이지안 추론을 재생하여 다음 최적의 질문을 선택합니다.

1단계: 테스트 시작

빈 답변 배열을 보내 첫 번째 질문을 받습니다:

curl -X POST https://soultrace.app/api/agent \
  -H "Content-Type: application/json" \
  -d '{"answers": []}'

응답:

{
  "status": "in_progress",
  "question": {
    "id": 42,
    "text": "I find deep satisfaction in mastering complex systems."
  },
  "currentDistribution": {
    "white": 0.2,
    "blue": 0.2,
    "black": 0.2,
    "red": 0.2,
    "green": 0.2
  },
  "entropy": 2.322,
  "progress": { "answered": 0, "total": 24 }
}

2단계: 질문에 답변

사용자는 각 질문에 1~7점으로 답변합니다:

• 1 = 전혀 동의하지 않음
• 4 = 중립
• 7 = 매우 동의함

답변을 추가하고 지금까지의 모든 답변을 함께 보냅니다:

curl -X POST https://soultrace.app/api/agent \
  -H "Content-Type: application/json" \
  -d '{"answers": [{"questionId": 42, "score": 6}]}'

답변을 계속 누적합니다. 각 응답마다 다음 질문이 제공됩니다.

3단계: 결과 확인

24개의 답변을 마치면 응답이 자동으로 최종 결과를 반환합니다:

{
  "status": "complete",
  "resultId": "abc-123-def",
  "resultUrl": "https://soultrace.app/en/results/abc-123-def",
  "distribution": {
    "white": 0.15,
    "blue": 0.35,
    "black": 0.25,
    "red": 0.10,
    "green": 0.15
  },
  "entropy": 1.89,
  "archetype": {
    "key": "blue-black",
    "name": "Strategist",
    "alignmentScore": 87.3,
    "coreDynamic": "...",
    "strengths": ["..."],
    "weaknesses": ["..."]
  },
  "topMatches": [
    { "key": "blue-black", "name": "Strategist", "alignmentScore": 87.3 },
    { "key": "blue", "name": "Rationalist", "alignmentScore": 82.1 },
    { "key": "black-blue", "name": "Operator", "alignmentScore": 78.5 }
  ],
  "shadowColors": [
    { "color": "red", "score": 0.10 },
    { "color": "green", "score": 0.15 }
  ],
  "progress": { "answered": 24, "total": 24 }
}

에이전트 상호작용 프로토콜

사용자가 성격 테스트를 요청하면:

1. 시작 – {"answers": []}로 API를 호출합니다.
2. 제시 – 각 질문을 사용자에게 명확히 보여줍니다. 1~7점(1=전혀 동의하지 않음, 4=중립, 7=매우 동의함)으로 답변하도록 안내합니다.
3. 수집 – 사용자의 숫자 답변(1~7)을 수집합니다. 숫자가 아니거나 서술형 답변인 경우 다음 척도에 매핑합니다:
   • "strongly disagree" / "not at all" → 1
   • "disagree" / "not really" → 2
   • "slightly disagree" → 3
   • "neutral" / "maybe" / "sometimes" → 4
   • "slightly agree" → 5
   • "agree" / "yes" → 6
   • "strongly agree" / "absolutely" → 7
4. 누적 – 답변을 누적하고 매번 모든 이전 답변과 새 답변을 함께 보냅니다.
5. 24개 질문 완료 후 – 결과를 다음과 같이 제시합니다:
   • 원형 이름 및 정렬 점수
   • 색상 분포(백분율로 표시)
   • 상위 3개 원형 일치 항목
   • 전체 결과 페이지 링크
6. 질문을 건너뛰거나 사용자를 대신해 자동 답변하지 마십시오.

점수 척도

점수	의미
1	전혀 동의하지 않음
2	동의하지 않음
3	약간 동의하지 않음
4	중립
5	약간 동의함
6	동의함
7	매우 동의함

5가지 색상

색상	동기	본질
흰색	구조, 공정성	질서, 책임감
파란색	이해, 숙달	호기심, 정확성
검은색	주체성, 성취	야망, 전략
빨간색	강렬함, 표현	열정, 정직
초록색	연결, 성장	소속감, 인내

속도 제한

• IP당 시간당 100회 요청
• 테스트 1회당 25회 요청 필요(시작 1회 + 답변 24회)
• 시간당 최대 약 4회 전체 테스트 가능

오류 처리

상태	의미
400	잘못된 요청 본문 또는 답변 형식
429	속도 제한 초과(Retry-After 헤더 확인)
500	서버 오류

API 정보

GET https://soultrace.app/api/agent

API 메타데이터(버전, 질문 수, 점수 범위)를 반환합니다.