Flow HITL 관리

CrewAI Enterprise는 AI 워크플로우를 협업적인 인간-AI 프로세스로 전환하는 Flow용 포괄적인 Human-in-the-Loop(HITL) 관리 시스템을 제공합니다. 플랫폼은 이메일 우선 아키텍처를 사용하여 이메일 주소가 있는 누구나 플랫폼 계정 없이도 검토 요청에 응답할 수 있습니다.

개요

이메일 우선 설계

응답자가 알림 이메일에 직접 회신하여 피드백 제공 가능

유연한 라우팅

메서드 패턴 또는 Flow 상태에 따라 특정 이메일로 요청 라우팅

자동 응답

시간 내에 인간이 응답하지 않을 경우 자동 대체 응답 구성

주요 이점

간단한 멘탈 모델: 이메일 주소는 보편적이며 플랫폼 사용자나 역할을 관리할 필요 없음
외부 응답자: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
동적 할당: Flow 상태에서 직접 담당자 이메일 가져오기 (예: sales_rep_email)
간소화된 구성: 설정할 항목이 적어 더 빠르게 가치 실현
이메일이 주요 채널: 대부분의 사용자는 대시보드 로그인보다 이메일로 응답하는 것을 선호

Flow에서 인간 검토 포인트 설정

@human_feedback 데코레이터를 사용하여 Flow 내에 인간 검토 체크포인트를 구성합니다. 실행이 검토 포인트에 도달하면 시스템이 일시 중지되고, 담당자에게 이메일로 알리며, 응답을 기다립니다.

from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        return "Q1 캠페인용 마케팅 카피 생성..."

    @human_feedback(
        message="브랜드 준수를 위해 이 콘텐츠를 검토해 주세요:",
        emit=["approved", "rejected", "needs_revision"],
    )
    @listen(or_("generate_content", "needs_revision"))
    def review_content(self):
        return "검토용 마케팅 카피..."

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"승인된 콘텐츠 게시 중. 검토자 노트: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"콘텐츠 거부됨. 사유: {result.feedback}")

완전한 구현 세부 사항은 Flow에서 인간 피드백 가이드를 참조하세요.

데코레이터 파라미터

파라미터	유형	설명
`message`	`str`	인간 검토자에게 표시되는 메시지
`emit`	`list[str]`	유효한 응답 옵션 (UI에서 버튼으로 표시)

플랫폼 구성

HITL 구성에 접근: 배포 → 설정 → Human in the Loop 구성

이메일 알림

HITL 요청에 대한 이메일 알림을 활성화하거나 비활성화하는 토글입니다.

설정	기본값	설명
이메일 알림	활성화됨	피드백 요청 시 이메일 전송

SLA 목표

추적 및 메트릭 목적으로 목표 응답 시간을 설정합니다.

설정	설명
SLA 목표 (분)	목표 응답 시간. 대시보드 메트릭 및 SLA 추적에 사용

SLA 추적을 비활성화하려면 비워 두세요.

이메일 알림 및 응답

HITL 시스템은 응답자가 알림 이메일에 직접 회신할 수 있는 이메일 우선 아키텍처를 사용합니다.

이메일 응답 작동 방식

알림 전송

HITL 요청이 생성되면 검토 콘텐츠와 컨텍스트가 포함된 이메일이 할당된 응답자에게 전송됩니다.
Reply-To 주소

이메일에는 인증을 위한 서명된 토큰이 포함된 특별한 reply-to 주소가 있습니다.
사용자 회신

응답자는 이메일에 피드백으로 회신하면 됩니다—로그인 필요 없음.
토큰 검증

플랫폼이 회신을 받고, 서명된 토큰을 확인하고, 발신자 이메일을 매칭합니다.
Flow 재개

피드백이 기록되고 인간의 입력으로 Flow가 계속됩니다.

응답 형식

응답자는 다음과 같이 회신할 수 있습니다:

Emit 옵션: 회신이 emit 옵션과 일치하면 (예: “approved”) 직접 사용됨
자유 형식 텍스트: 모든 텍스트 응답이 피드백으로 Flow에 전달됨
일반 텍스트: 회신 본문의 첫 번째 줄이 피드백으로 사용됨

확인 이메일

회신을 처리한 후 응답자는 피드백이 성공적으로 제출되었는지 또는 오류가 발생했는지 나타내는 확인 이메일을 받습니다.

이메일 토큰 보안

토큰은 보안을 위해 암호화 서명됨
토큰은 7일 후 만료됨
발신자 이메일은 토큰의 인증된 이메일과 일치해야 함
처리 후 확인/오류 이메일 전송됨

라우팅 규칙

메서드 패턴에 따라 HITL 요청을 특정 이메일 주소로 라우팅합니다.

규칙 구조

{
  "name": "재무팀으로 승인",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "[email protected]",
  "assign_from_input": "manager_email"
}

매칭 패턴

패턴	설명	매칭 예시
`approve_*`	와일드카드 (모든 문자)	`approve_payment`, `approve_vendor`
`review_?`	단일 문자	`review_a`, `review_1`
`validate_payment`	정확히 일치	`validate_payment`만

할당 우선순위

동적 할당 (assign_from_input): 구성된 경우 Flow 상태에서 이메일 가져옴
정적 이메일 (assign_to_email): 구성된 이메일로 대체
배포 생성자: 규칙이 일치하지 않으면 배포 생성자의 이메일이 사용됨

동적 할당 예제

Flow 상태에 {"sales_rep_email": "[email protected]"}이 포함된 경우:

{
  "name": "영업 담당자에게 라우팅",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}

요청이 자동으로 [email protected]에 할당됩니다.

자동 응답

시간 내에 인간이 응답하지 않으면 HITL 요청에 자동으로 응답합니다. 이를 통해 Flow가 무한정 중단되지 않도록 합니다.

구성

설정	설명
활성화됨	자동 응답 활성화 토글
타임아웃 (분)	자동 응답 전 대기 시간
기본 결과	응답 값 (`emit` 옵션과 일치해야 함)

사용 사례

SLA 준수: Flow가 무한정 중단되지 않도록 보장
기본 승인: 타임아웃 후 저위험 요청 자동 승인
우아한 저하: 검토자가 없을 때 안전한 기본값으로 계속

검토 프로세스

대시보드 인터페이스

HITL 검토 인터페이스는 검토자에게 깔끔하고 집중된 경험을 제공합니다:

마크다운 렌더링: 구문 강조가 포함된 풍부한 형식의 검토 콘텐츠
컨텍스트 패널: Flow 상태, 실행 기록 및 관련 정보 보기
피드백 입력: 결정과 함께 상세한 피드백 및 코멘트 제공
빠른 작업: 선택적 코멘트가 있는 원클릭 emit 옵션 버튼

응답 방법

검토자는 세 가지 채널을 통해 응답할 수 있습니다:

방법	설명
이메일 회신	알림 이메일에 직접 회신
대시보드	Enterprise 대시보드 UI 사용
API/Webhook	API를 통한 프로그래밍 방식 응답

기록 및 감사 추적

모든 HITL 상호작용은 완전한 타임라인으로 추적됩니다:

결정 기록 (승인/거부/수정)
검토자 신원 및 타임스탬프
제공된 피드백 및 코멘트
응답 방법 (이메일/대시보드/API)
응답 시간 메트릭

분석 및 모니터링

포괄적인 분석으로 HITL 성능을 추적합니다.

성능 대시보드

응답 시간

검토자 또는 Flow별 평균 및 중앙값 응답 시간 모니터링.

볼륨 트렌드

팀 용량 최적화를 위한 검토 볼륨 패턴 분석.

결정 분포

다양한 검토 유형에 대한 승인/거부 비율 보기.

SLA 추적

SLA 목표 내에 완료된 검토 비율 추적.

감사 및 규정 준수

규제 요구 사항을 위한 엔터프라이즈급 감사 기능:

타임스탬프가 있는 완전한 결정 기록
검토자 신원 확인
불변 감사 로그
규정 준수 보고를 위한 내보내기 기능

일반적인 사용 사례

보안 검토

사용 사례: 인간 검증이 포함된 내부 보안 설문지 자동화

AI가 보안 설문지에 대한 응답 생성
보안팀이 이메일로 정확성 검토 및 검증
승인된 응답이 최종 제출물로 편집
규정 준수를 위한 완전한 감사 추적

콘텐츠 승인

사용 사례: 법무/브랜드 검토가 필요한 마케팅 콘텐츠

AI가 마케팅 카피 또는 소셜 미디어 콘텐츠 생성
브랜드팀 이메일로 목소리/톤 검토를 위해 라우팅
승인 시 자동 게시

재무 승인

사용 사례: 경비 보고서, 계약 조건, 예산 배분

AI가 재무 요청을 사전 처리하고 분류
동적 할당을 사용하여 금액 임계값에 따라 라우팅
재무 규정 준수를 위한 완전한 감사 추적 유지

CRM에서 동적 할당

사용 사례: CRM에서 계정 담당자에게 검토 라우팅

Flow가 CRM에서 계정 담당자 이메일 가져옴
이메일을 Flow 상태에 저장 (예: account_owner_email)
assign_from_input을 사용하여 적합한 사람에게 자동 라우팅

품질 보증

사용 사례: 고객 전달 전 AI 출력 검증

AI가 고객 대면 콘텐츠 또는 응답 생성
QA팀이 이메일 알림을 통해 검토
피드백 루프가 시간이 지남에 따라 AI 성능 개선

Webhook API

Flow가 인간 피드백을 위해 일시 중지되면, 요청 데이터를 자체 애플리케이션으로 보내도록 webhook을 구성할 수 있습니다. 이를 통해 다음이 가능합니다:

커스텀 승인 UI 구축
내부 도구와 통합 (Jira, ServiceNow, 커스텀 대시보드)
타사 시스템으로 승인 라우팅
모바일 앱 알림
자동화된 결정 시스템

Webhook 구성

설정으로 이동

배포 → 설정 → Human in the Loop으로 이동
Webhook 섹션 확장

Webhooks 구성을 클릭하여 확장
Webhook URL 추가

webhook URL 입력 (프로덕션에서는 HTTPS 필수)
구성 저장

구성 저장을 클릭하여 활성화

여러 webhook을 구성할 수 있습니다. 각 활성 webhook은 모든 HITL 이벤트를 수신합니다.

Webhook 이벤트

엔드포인트는 다음 이벤트에 대해 HTTP POST 요청을 수신합니다:

이벤트 유형	트리거 시점
`new_request`	Flow가 일시 중지되고 인간 피드백을 요청할 때

Webhook 페이로드

모든 webhook은 다음 구조의 JSON 페이로드를 수신합니다:

{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "이 기사의 게시를 검토해 주세요.",
    "emit_options": ["approved", "rejected", "request_changes"],
    "state": {
      "article_id": 12345,
      "author": "[email protected]",
      "category": "technology"
    },
    "metadata": {},
    "created_at": "2026-01-14T12:00:00Z"
  },
  "deployment": {
    "id": 456,
    "name": "Content Review Flow",
    "organization_id": 789
  },
  "callback_url": "https://api.crewai.com/...",
  "assigned_to_email": "[email protected]"
}

요청에 응답하기

피드백을 제출하려면 webhook 페이로드에 포함된 callback_url로 POST합니다.

POST {callback_url}
Content-Type: application/json

{
  "feedback": "승인됨. 훌륭한 기사입니다!",
  "source": "my_custom_app"
}

보안

Webhook 보안

HMAC-SHA256 서명: 모든 webhook에 암호화 서명이 포함됨
Webhook별 시크릿: 각 webhook은 고유한 서명 시크릿을 가짐
저장 시 암호화: 서명 시크릿은 데이터베이스에서 암호화됨
타임스탬프 검증: 리플레이 공격 방지

서명 헤더

각 webhook 요청에는 다음 헤더가 포함됩니다:

헤더	설명
`X-Signature`	HMAC-SHA256 서명: `sha256=<hex_digest>`
`X-Timestamp`	요청이 서명된 Unix 타임스탬프

검증

다음과 같이 계산하여 검증합니다:

import hmac
import hashlib

expected = hmac.new(
    signing_secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, signature):
    # 유효한 서명

오류 처리

webhook 엔드포인트는 수신 확인을 위해 2xx 상태 코드를 반환해야 합니다:

응답	동작
2xx	Webhook 성공적으로 전달됨
4xx/5xx	실패로 기록됨, 재시도 없음
타임아웃 (30초)	실패로 기록됨, 재시도 없음

보안 및 RBAC

대시보드 접근

HITL 접근은 배포 수준에서 제어됩니다:

권한	기능
`manage_human_feedback`	HITL 설정 구성, 모든 요청 보기
`respond_to_human_feedback`	요청에 응답, 할당된 요청 보기

이메일 응답 인증

이메일 회신의 경우:

reply-to 토큰이 인증된 이메일을 인코딩
발신자 이메일이 토큰의 이메일과 일치해야 함
토큰이 만료되지 않아야 함 (기본 7일)
요청이 여전히 대기 중이어야 함

감사 추적

모든 HITL 작업이 기록됩니다:

요청 생성
할당 변경
응답 제출 (소스: 대시보드/이메일/API)
Flow 재개 상태

문제 해결

이메일이 전송되지 않음

구성에서 “이메일 알림”이 활성화되어 있는지 확인
라우팅 규칙이 메서드 이름과 일치하는지 확인
담당자 이메일이 유효한지 확인
라우팅 규칙이 일치하지 않는 경우 배포 생성자 대체 확인

이메일 회신이 처리되지 않음

토큰이 만료되지 않았는지 확인 (기본 7일)
발신자 이메일이 할당된 이메일과 일치하는지 확인
요청이 여전히 대기 중인지 확인 (아직 응답되지 않음)

Flow가 재개되지 않음

대시보드에서 요청 상태 확인
콜백 URL에 접근 가능한지 확인
배포가 여전히 실행 중인지 확인

모범 사례

동적 할당 사용: 유연한 라우팅을 위해 Flow 상태에서 담당자 이메일을 가져오세요.
자동 응답 구성: 중요하지 않은 검토에 대해 Flow가 중단되지 않도록 대체를 설정하세요.
응답 시간 모니터링: 분석을 사용하여 병목 현상을 식별하고 검토 프로세스를 최적화하세요.
검토 메시지를 명확하게 유지: @human_feedback 데코레이터에 명확하고 실행 가능한 메시지를 작성하세요.
이메일 흐름 테스트: 프로덕션에 가기 전에 테스트 요청을 보내 이메일 전달을 확인하세요.

Flow HITL 관리

개요

이메일 우선 설계

유연한 라우팅

자동 응답

주요 이점

Flow에서 인간 검토 포인트 설정

데코레이터 파라미터

플랫폼 구성

이메일 알림

SLA 목표

이메일 알림 및 응답

이메일 응답 작동 방식

응답 형식

확인 이메일

이메일 토큰 보안

라우팅 규칙

규칙 구조

매칭 패턴

할당 우선순위

동적 할당 예제

자동 응답

구성

사용 사례

검토 프로세스

대시보드 인터페이스

응답 방법

기록 및 감사 추적

분석 및 모니터링

성능 대시보드

응답 시간

볼륨 트렌드

결정 분포

SLA 추적

감사 및 규정 준수

일반적인 사용 사례

Webhook API

Webhook 구성

Webhook 이벤트

Webhook 페이로드

요청에 응답하기

보안

Webhook 보안

서명 헤더

검증

오류 처리

보안 및 RBAC

대시보드 접근

이메일 응답 인증

감사 추적

문제 해결

이메일이 전송되지 않음

이메일 회신이 처리되지 않음

Flow가 재개되지 않음

모범 사례

관련 리소스

Flow에서 인간 피드백

Flow HITL 워크플로우 가이드

RBAC 구성

Webhook 스트리밍