휴먼-인-더-루프

휴먼-인-더-루프 (Human-in-the-Loop, HITL) 워크플로우

AI만으로는 판단이 애매하거나 높은 책임이 따르는 작업에서, 사람의 검토와 피드백을 중간에 끼워 넣는 방식이 휴먼-인-더-루프(HITL)예요. CrewAI는 필요에 따라 선택할 수 있는 여러 HITL 구현 방식을 제공하는데요, 흐름 기반(@human_feedback 데코레이터)과 웹훅 기반(Enterprise)이 대표적이에요. 이 중 웹훅 기반 방식은 프로덕션 배포나 외부 통합(Slack, Teams 등)에 잘 맞아요.

출처: 공식문서

본문

HITL 접근 방식 선택하기

CrewAI는 휴먼-인-더-루프 워크플로우를 구현하는 두 가지 주요 접근 방식을 제공해요.

접근 방식	가장 적합한 대상	통합	버전
Flow 기반 (`@human_feedback` 데코레이터)	로컬 개발, 콘솔 기반 검토, 동기 워크플로우	피드백 기반 라우팅	1.8.0+
Webhook 기반 (Enterprise)	프로덕션 배포, 비동기 워크플로우, 외부 통합(Slack, Teams 등)	이 가이드	-

플로우를 만들면서 피드백에 따라 라우팅되는 사람 검토 스텝을 추가하고 싶다면, @human_feedback 데코레이터를 쓰는 피드백 기반 라우팅 가이드를 확인해 보세요.

웹훅 기반 HITL 워크플로우 설정하기

1. 태스크 구성하기

사람 입력이 활성화된 태스크를 설정해요.

2. 웹훅 URL 제공하기

크루를 킥오프할 때 사람 입력용 웹훅 URL을 포함해요. Bearer 인증 예시는 다음과 같아요.

curl -X POST {BASE_URL}/kickoff \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "topic": "AI Research"
    },
    "humanInputWebhook": {
      "url": "https://your-webhook.com/hitl",
      "authentication": {
        "strategy": "bearer",
        "token": "your-webhook-secret-token"
      }
    }
  }'

또는 Basic 인증을 쓸 수도 있어요.

curl -X POST {BASE_URL}/kickoff \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "topic": "AI Research"
    },
    "humanInputWebhook": {
      "url": "https://your-webhook.com/hitl",
      "authentication": {
        "strategy": "basic",
        "username": "your-username",
        "password": "your-password"
      }
    }
  }'

3. 웹훅 알림 받기

크루가 사람 입력이 필요한 태스크를 완료하면, 다음을 포함한 웹훅 알림을 받아요.

Execution ID
Task ID
Task output

4. 태스크 출력 검토하기

시스템은 Pending Human Input 상태에서 일시 중지돼요. 태스크 출력을 신중히 검토해요.

5. 사람 피드백 제출하기

크루의 resume 엔드포인트를 다음 정보로 호출해요.

중요: 웹훅 URL을 다시 제공해야 함: resume 호출에서 kickoff 호출에 사용했던 것과 동일한 웹훅 URL(taskWebhookUrl, stepWebhookUrl, crewWebhookUrl)을 제공해야 해요. 웹훅 설정은 kickoff에서 자동으로 이어지지 않으므로, 태스크 완료·에이전트 스텝·크루 완료 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 해요.

웹훅이 포함된 resume 호출 예시:

curl -X POST {BASE_URL}/resume \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "task_id": "research_task",
    "human_feedback": "Great work! Please add more details.",
    "is_approve": true,
    "taskWebhookUrl": "https://your-server.com/webhooks/task",
    "stepWebhookUrl": "https://your-server.com/webhooks/step",
    "crewWebhookUrl": "https://your-server.com/webhooks/crew"
  }'

피드백이 태스크 실행에 미치는 영향: 피드백을 제공할 때는 주의해야 해요. 피드백 내용 전체가 이후 태스크 실행을 위한 추가 컨텍스트로 포함되기 때문이에요.

즉, 다음을 의미해요.

피드백의 모든 정보가 태스크의 컨텍스트 일부가 돼요.
관련 없는 세부 사항은 부정적으로 영향을 줄 수 있어요.
간결하고 관련 있는 피드백은 태스크의 집중도와 효율성을 유지하는 데 도움돼요.
제출 전에 피드백이 태스크 실행을 긍정적으로 안내할 관련 정보만 담고 있는지 신중히 검토해요.

6. 부정적 피드백 처리하기

부정적 피드백을 제공하면:

크루가 피드백에서 추가된 컨텍스트로 태스크를 재시도해요.
추가 검토를 위한 또 다른 웹훅 알림을 받아요.
만족할 때까지 4~6단계를 반복해요.

7. 실행 계속하기

긍정적 피드백을 제출하면 실행이 다음 단계로 진행돼요.

모범 사례

구체적으로(Be Specific): 태스크를 직접 지시하는 명확하고 실행 가능한 피드백을 제공해요.
관련성 유지(Stay Relevant): 태스크 실행을 개선하는 데 도움이 되는 정보만 포함해요.
시의적절하게(Be Timely): 워크플로우 지연을 피하려면 HITL 프롬프트에 신속히 응답해요.
신중히 검토(Review Carefully): 정확성을 보장하려면 제출 전에 피드백을 다시 확인해요.

일반적인 사용 사례

HITL 워크플로우는 특히 다음에 유용해요.

품질 보증과 검증
복잡한 의사결정 시나리오
민감하거나 고위험 운영
사람의 판단이 필요한 창의적 태스크
규정 준수 및 규제 검토

휴먼-인-더-루프