HITL 워크플로우

인간-중심(Human-In-The-Loop, HITL)은 인공지능과 인간 전문 지식을 결합하여 의사결정을 강화하고 작업 결과를 향상시키는 강력한 접근 방식입니다. 이 가이드는 CrewAI Enterprise 내에서 HITL을 구현하는 방법을 보여줍니다.

CrewAI의 HITL 접근 방식

CrewAI는 human-in-the-loop 워크플로우를 구현하기 위한 두 가지 접근 방식을 제공합니다:

접근 방식	적합한 용도	버전
Flow 기반 (`@human_feedback` 데코레이터)	Enterprise UI를 사용한 프로덕션, 이메일 우선 워크플로우, 전체 플랫폼 기능	1.8.0+
Webhook 기반	커스텀 통합, 외부 시스템 (Slack, Teams 등), 레거시 설정	모든 버전

Enterprise 플랫폼과 Flow 기반 HITL

Flow에서 @human_feedback 데코레이터를 사용하면, CrewAI Enterprise는 이메일 주소가 있는 누구나 검토 요청에 응답할 수 있는 이메일 우선 HITL 시스템을 제공합니다:

이메일 우선 설계

응답자가 이메일 알림을 받고 직접 회신할 수 있습니다—로그인이 필요 없습니다.

대시보드 검토

원할 때 Enterprise 대시보드에서 HITL 요청을 검토하고 응답하세요.

유연한 라우팅

메서드 패턴에 따라 특정 이메일로 요청을 라우팅하거나 Flow 상태에서 가져오세요.

자동 응답

타임아웃 내에 인간이 응답하지 않을 경우 자동 대체 응답을 구성하세요.

주요 이점

외부 응답자: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
동적 할당: Flow 상태에서 담당자 이메일 가져오기 (예: account_owner_email)
간단한 구성: 이메일 기반 라우팅은 사용자/역할 관리보다 설정이 쉬움
배포 생성자 대체: 라우팅 규칙이 일치하지 않으면 배포 생성자에게 알림

Webhook 기반 HITL 워크플로 설정

Slack, Microsoft Teams 또는 자체 애플리케이션과 같은 외부 시스템과의 커스텀 통합을 위해 webhook 기반 접근 방식을 사용할 수 있습니다:

작업 구성

사람 입력이 활성화된 상태로 작업을 설정하세요:
Webhook URL 제공

crew를 시작할 때 인간 입력을 위한 webhook URL을 포함하세요:
Webhook 알림 받기

crew가 사람 입력이 필요한 작업을 완료하면 다음 정보를 포함한 webhook 알림을 받게 됩니다:
- Execution ID
- Task ID
- Task output
작업 출력 검토

시스템이 Pending Human Input 상태에서 일시 중지됩니다. 작업 출력을 신중하게 검토하세요.
사람 피드백 제출

다음 정보를 포함하여 crew의 resume endpoint를 호출하세요:

Warning

중요: Webhook URL을 다시 제공해야 합니다: kickoff 호출에서 사용한 것과 동일한 webhook URL(taskWebhookUrl, stepWebhookUrl, crewWebhookUrl)을 resume 호출에서 반드시 제공해야 합니다. Webhook 설정은 kickoff에서 자동으로 전달되지 않으므로, 작업 완료, 에이전트 단계, crew 완료에 대한 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 합니다.

Webhook을 포함한 resume 호출 예시:
Terminal window
```
curl -X POST {BASE_URL}/resume \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "task_id": "research_task",
    "human_feedback": "훌륭한 작업입니다! 더 자세한 내용을 추가해주세요.",
    "is_approve": true,
    "taskWebhookUrl": "https://your-server.com/webhooks/task",
    "stepWebhookUrl": "https://your-server.com/webhooks/step",
    "crewWebhookUrl": "https://your-server.com/webhooks/crew"
  }'
```
Warning

피드백이 작업 실행에 미치는 영향: 피드백 전체 내용이 이후 작업 실행을 위한 추가 컨텍스트로 통합되므로 피드백 제공 시 신중함이 매우 중요합니다.

이는 다음을 의미합니다:
- 피드백에 입력한 모든 정보가 작업의 컨텍스트 일부가 됩니다.
- 관련 없는 상세 정보는 부정적인 영향을 줄 수 있습니다.
- 간결하고 관련성 높은 피드백이 작업의 집중도와 효율성을 유지하는 데 도움이 됩니다.
- 제출 전 항상 피드백을 신중히 검토하여 작업 실행을 긍정적으로 안내할 수 있는 관련 정보만 포함되어 있는지 확인하세요.
부정적 피드백 처리

부정적인 피드백을 제공하는 경우:
- crew가 귀하의 피드백에서 추가된 컨텍스트와 함께 작업을 재시도합니다.
- 추가 확인을 위한 다른 webhook 알림을 받게 됩니다.
- 만족할 때까지 4-6단계를 반복하세요.
작업 실행 계속 진행

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