> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Human-in-the-Loop (HITL) 워크플로우

> CrewAI에서 Human-in-the-Loop 워크플로우를 구현하여 의사결정을 향상시키는 방법을 알아보세요

휴먼 인 더 루프(HITL, Human-in-the-Loop)는 인공지능과 인간의 전문 지식을 결합하여 의사결정을 강화하고 작업 결과를 향상시키는 강력한 접근 방식입니다. CrewAI는 필요에 따라 HITL을 구현하는 여러 가지 방법을 제공합니다.

## HITL 접근 방식 선택

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

| 접근 방식                                 | 적합한 용도                                     | 통합                                                 | 버전         |
| ------------------------------------- | ------------------------------------------ | -------------------------------------------------- | ---------- |
| **Flow 기반** (`@human_feedback` 데코레이터) | 로컬 개발, 콘솔 기반 검토, 동기식 워크플로우                 | [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) | **1.8.0+** |
| **Webhook 기반** (Enterprise)           | 프로덕션 배포, 비동기 워크플로우, 외부 통합 (Slack, Teams 등) | 이 가이드                                              | -          |

<Tip>
  Flow를 구축하면서 피드백을 기반으로 라우팅하는 인간 검토 단계를 추가하려면 `@human_feedback` 데코레이터에 대한 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요.
</Tip>

## Webhook 기반 HITL 워크플로우 설정

<Steps>
  <Step title="작업 구성">
    human input이 활성화된 상태로 작업을 설정하세요:

    <Frame>
      <img src="https://mintcdn.com/crewai/5SZbe87tsCWZY09V/images/enterprise/crew-human-input.png?fit=max&auto=format&n=5SZbe87tsCWZY09V&q=85&s=cb2e2bab131e9eff86b0c51dceb16e11" alt="Crew Human Input" width="624" height="165" data-path="images/enterprise/crew-human-input.png" />
    </Frame>
  </Step>

  <Step title="Webhook URL 제공">
    crew를 시작할 때, human input을 위한 webhook URL을 포함하세요:

    <Frame>
      <img src="https://mintcdn.com/crewai/5SZbe87tsCWZY09V/images/enterprise/crew-webhook-url.png?fit=max&auto=format&n=5SZbe87tsCWZY09V&q=85&s=f2d298c0b4c7b3a62e1dee4e2e6f1bb3" alt="Crew Webhook URL" width="624" height="259" data-path="images/enterprise/crew-webhook-url.png" />
    </Frame>
  </Step>

  <Step title="Webhook 알림 수신">
    crew가 human input이 필요한 작업을 완료하면, 다음 내용을 포함하는 webhook 알림을 받게 됩니다:

    * 실행 ID
    * 작업 ID
    * 작업 출력
  </Step>

  <Step title="작업 출력 검토">
    시스템이 `Pending Human Input` 상태에서 일시정지됩니다. 작업 출력을 신중하게 검토하세요.
  </Step>

  <Step title="Human Feedback 제출">
    다음 정보를 포함하여 crew의 resume endpoint를 호출하세요:

    <Frame>
      <img src="https://mintcdn.com/crewai/5SZbe87tsCWZY09V/images/enterprise/crew-resume-endpoint.png?fit=max&auto=format&n=5SZbe87tsCWZY09V&q=85&s=1e1c2ca22a2d674426f8e663fed33eca" alt="Crew Resume Endpoint" width="624" height="261" data-path="images/enterprise/crew-resume-endpoint.png" />
    </Frame>

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

    Webhook을 포함한 resume 호출 예시:

    ```bash theme={null}
    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>
      **피드백이 작업 실행에 미치는 영향**:
      피드백의 전체 내용이 추가 컨텍스트로서 이후 작업 실행에 통합되므로, 피드백 제공 시 신중을 기하는 것이 매우 중요합니다.
    </Warning>

    즉:

    * 피드백에 포함된 모든 정보가 작업의 컨텍스트의 일부가 됩니다.
    * 관련 없는 세부 정보는 작업에 부정적인 영향을 미칠 수 있습니다.
    * 간결하고 관련성 높은 피드백이 작업의 집중력과 효율성을 유지하는 데 도움이 됩니다.
    * 제출 전에 피드백을 항상 꼼꼼히 검토하여 작업 실행을 긍정적으로 이끌 수 있는 정보만 포함되어 있는지 확인하세요.
  </Step>

  <Step title="부정적 피드백 처리">
    부정적인 피드백을 제공할 경우:

    * crew는 피드백에서 얻은 추가 컨텍스트로 작업을 재시도합니다.
    * 추가 검토를 위한 또 다른 webhook 알림을 받게 됩니다.
    * 만족할 때까지 4-6단계를 반복하세요.
  </Step>

  <Step title="실행 계속">
    긍정적인 피드백을 제출하면 실행이 다음 단계로 진행됩니다.
  </Step>
</Steps>

## 모범 사례

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

## 일반적인 사용 사례

HITL 워크플로우는 다음과 같은 경우에 특히 유용합니다:

* 품질 보증 및 검증
* 복잡한 의사결정 시나리오
* 민감하거나 고위험 작업
* 인간의 판단이 필요한 창의적 과제
* 컴플라이언스 및 규제 검토

## Enterprise 기능

<Card title="Flow HITL 관리 플랫폼" icon="users-gear" href="/ko/enterprise/features/flow-hitl-management">
  CrewAI Enterprise는 플랫폼 내 검토, 응답자 할당, 권한, 에스컬레이션 정책, SLA 관리, 동적 라우팅 및 전체 분석을 갖춘 Flow용 포괄적인 HITL 관리 시스템을 제공합니다. [자세히 알아보기 →](/ko/enterprise/features/flow-hitl-management)
</Card>