메인 콘텐츠로 건너뛰기
인간-중심(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

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

이메일 우선 설계

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

대시보드 검토

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

유연한 라우팅

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

자동 응답

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

​
주요 이점

  • 외부 응답자: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
  • 동적 할당: Flow 상태에서 담당자 이메일 가져오기 (예: account_owner_email)
  • 간단한 구성: 이메일 기반 라우팅은 사용자/역할 관리보다 설정이 쉬움
  • 배포 생성자 대체: 라우팅 규칙이 일치하지 않으면 배포 생성자에게 알림
@human_feedback 데코레이터의 구현 세부 사항은 Flow에서 인간 피드백 가이드를 참조하세요.

​
Webhook 기반 HITL 워크플로 설정

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

작업 구성

사람 입력이 활성화된 상태로 작업을 설정하세요:
Crew Human Input
2

Webhook URL 제공

crew를 시작할 때 인간 입력을 위한 webhook URL을 포함하세요:
Crew Webhook URL
3

Webhook 알림 받기

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

작업 출력 검토

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

사람 피드백 제출

다음 정보를 포함하여 crew의 resume endpoint를 호출하세요:
Crew Resume Endpoint
중요: Webhook URL을 다시 제공해야 합니다: kickoff 호출에서 사용한 것과 동일한 webhook URL(taskWebhookUrl, stepWebhookUrl, crewWebhookUrl)을 resume 호출에서 반드시 제공해야 합니다. Webhook 설정은 kickoff에서 자동으로 전달되지 않으므로, 작업 완료, 에이전트 단계, crew 완료에 대한 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 합니다.
Webhook을 포함한 resume 호출 예시:
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"
  }'
피드백이 작업 실행에 미치는 영향: 피드백 전체 내용이 이후 작업 실행을 위한 추가 컨텍스트로 통합되므로 피드백 제공 시 신중함이 매우 중요합니다.
이는 다음을 의미합니다:
  • 피드백에 입력한 모든 정보가 작업의 컨텍스트 일부가 됩니다.
  • 관련 없는 상세 정보는 부정적인 영향을 줄 수 있습니다.
  • 간결하고 관련성 높은 피드백이 작업의 집중도와 효율성을 유지하는 데 도움이 됩니다.
  • 제출 전 항상 피드백을 신중히 검토하여 작업 실행을 긍정적으로 안내할 수 있는 관련 정보만 포함되어 있는지 확인하세요.
6

부정적 피드백 처리

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

작업 실행 계속 진행

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

​
모범 사례

  • 구체적으로 작성하세요: 해당 작업에 직접적으로 관련된 명확하고 실행 가능한 피드백을 제공하세요
  • 관련성 유지: 작업 수행 개선에 도움이 되는 정보만 포함하세요
  • 적시에 응답하세요: 워크플로우 지연을 피하기 위해 HITL 프롬프트에 신속하게 응답하세요
  • 꼼꼼하게 검토하세요: 제출 전에 피드백을 다시 확인하여 정확성을 보장하세요

​
일반적인 사용 사례

HITL 워크플로우는 특히 다음과 같은 경우에 유용합니다:
  • 품질 보증 및 검증
  • 복잡한 의사 결정 시나리오
  • 민감하거나 위험도가 높은 작업
  • 인간의 판단이 필요한 창의적 작업
  • 준수 및 규제 검토

​
자세히 알아보기

Flow HITL 관리

이메일 알림, 라우팅 규칙, 자동 응답 및 분석을 포함한 전체 Enterprise Flow HITL 플랫폼 기능을 살펴보세요.

Flow에서 인간 피드백

Flow에서 @human_feedback 데코레이터 구현 가이드.