---
title: "HITL 워크플로우"
description: "CrewAI에서 의사결정 향상을 위한 Human-In-The-Loop 워크플로우 구현 방법을 알아보세요"
icon: "user-check"
mode: "wide"
---

인간-중심(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

<Note>
`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다.
</Note>

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

<CardGroup cols={2}>
  <Card title="이메일 우선 설계" icon="envelope">
    응답자가 이메일 알림을 받고 직접 회신할 수 있습니다—로그인이 필요 없습니다.
  </Card>
  <Card title="대시보드 검토" icon="desktop">
    원할 때 Enterprise 대시보드에서 HITL 요청을 검토하고 응답하세요.
  </Card>
  <Card title="유연한 라우팅" icon="route">
    메서드 패턴에 따라 특정 이메일로 요청을 라우팅하거나 Flow 상태에서 가져오세요.
  </Card>
  <Card title="자동 응답" icon="clock">
    타임아웃 내에 인간이 응답하지 않을 경우 자동 대체 응답을 구성하세요.
  </Card>
</CardGroup>

### 주요 이점

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

<Tip>
`@human_feedback` 데코레이터의 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요.
</Tip>

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

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

<Steps>
    <Step title="작업 구성">
        사람 입력이 활성화된 상태로 작업을 설정하세요:
        <Frame>
            <img src="/images/enterprise/crew-human-input.png" alt="Crew Human Input" />
        </Frame>
    </Step>

    <Step title="Webhook URL 제공">
        crew를 시작할 때 인간 입력을 위한 webhook URL을 포함하세요:
        <Frame>
            <img src="/images/enterprise/crew-webhook-url.png" alt="Crew Webhook URL" />
        </Frame>
    </Step>

    <Step title="Webhook 알림 받기">
        crew가 사람 입력이 필요한 작업을 완료하면 다음 정보를 포함한 webhook 알림을 받게 됩니다:
            - **Execution ID**
            - **Task ID**
            - **Task output**
    </Step>

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

    <Step title="사람 피드백 제출">
        다음 정보를 포함하여 crew의 resume endpoint를 호출하세요:
        <Frame>
            <img src="/images/enterprise/crew-resume-endpoint.png" alt="Crew Resume Endpoint" />
        </Frame>

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

        Webhook을 포함한 resume 호출 예시:
        ```bash
        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 워크플로우는 특히 다음과 같은 경우에 유용합니다:
- 품질 보증 및 검증
- 복잡한 의사 결정 시나리오
- 민감하거나 위험도가 높은 작업
- 인간의 판단이 필요한 창의적 작업
- 준수 및 규제 검토

## 자세히 알아보기

<CardGroup cols={2}>
  <Card title="Flow HITL 관리" icon="users-gear" href="/ko/enterprise/features/flow-hitl-management">
    이메일 알림, 라우팅 규칙, 자동 응답 및 분석을 포함한 전체 Enterprise Flow HITL 플랫폼 기능을 살펴보세요.
  </Card>
  <Card title="Flow에서 인간 피드백" icon="code" href="/ko/learn/human-feedback-in-flows">
    Flow에서 `@human_feedback` 데코레이터 구현 가이드.
  </Card>
</CardGroup>
