Flow HITL 管理

Note

Flow HITL Management 功能需要 @human_feedback 装饰器，该装饰器在 CrewAI version 1.8.0 或更高 中可用。这些功能专门适用于 Flows，不适用于 Crews。

CrewAI Enterprise 为 Flows 提供了一套完整的 Human-in-the-Loop（HITL）管理系统，可将 AI 工作流转变为人机协作流程。该平台采用 email-first architecture，让任何拥有电子邮件地址的人都能回复审核请求 - 无需平台账户。

概览

Email-First 设计

回复者可以直接回复通知邮件来提供反馈

灵活路由

根据 method patterns 或 flow state，把请求路由到特定邮箱

自动响应

当没人及时回复时，配置自动 fallback response

主要优势

• 简单的心智模型：电子邮件地址是通用的；无需管理平台用户或 roles
• 外部回复者：任何拥有邮箱的人都能回复，即使不是平台用户
• 动态分配：直接从 flow state 中提取 assignee email（例如 sales_rep_email）
• 更少配置：需要配置的设置更少，上手更快
• 以电子邮件为主渠道：大多数用户更愿意通过邮件回复，而不是登录仪表板

在 Flows 中设置人工审核点

使用 @human_feedback 装饰器在你的 Flows 中配置人工审核 checkpoint。当执行到达审核点时，系统会暂停，通过电子邮件通知 assignee，并等待回复。

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 "Generated marketing copy for Q1 campaign..."

    @human_feedback(
        message="Please review this content for brand compliance:",
        emit=["approved", "rejected", "needs_revision"],
    )
    @listen(or_("generate_content", "needs_revision"))
    def review_content(self):
        return "Marketing copy for review..."

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"Publishing approved content. Reviewer notes: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"Content rejected. Reason: {result.feedback}")

完整实现细节请参见 Human Feedback in Flows 指南。

装饰器参数

Parameter	Type	Description
message	str	显示给人工审核者的信息
emit	list[str]	有效的响应选项（在 UI 中显示为按钮）

平台配置

从这里访问 HITL 配置：Deployment → Settings → Human in the Loop Configuration

电子邮件通知

切换以启用或禁用 HITL 请求的电子邮件通知。

Setting	Default	Description
Email Notifications	Enabled	在请求反馈时发送电子邮件

Note

如果禁用，回复者必须使用 dashboard UI，或者你必须配置 webhook 以对接自定义通知系统。

SLA Target

设置目标响应时间，用于跟踪和指标。

Setting	Description
SLA Target (minutes)	目标响应时间。用于 dashboard metrics 和 SLA tracking

留空即可禁用 SLA tracking。

电子邮件通知与回复

HITL system 使用 email-first architecture，回复者可以直接回复通知邮件。

电子邮件回复如何工作

1. 发送通知

   当创建 HITL 请求时，系统会向指定回复者发送一封包含审核内容和上下文的电子邮件。

2. Reply-To 地址

   邮件中包含一个带有签名 token 的特殊 reply-to 地址，用于认证。

3. 用户回复

   回复者只需回复电子邮件并提供反馈 - 无需登录。

4. Token 验证

   平台接收回复，验证签名 token，并匹配发件人邮箱。

5. Flow 继续执行

   反馈会被记录，flow 会携带人工输入继续执行。

响应格式

回复者可以通过以下方式回复：

• Emit option：如果回复匹配某个 emit option（例如 “approved”），则直接采用
• Free-form text：任何文本回复都会作为反馈传给 flow
• Plain text：回复正文的第一行会被用作反馈

确认邮件

处理回复后，回复者会收到一封确认邮件，说明反馈是否成功提交，或者是否发生错误。

Email Token 安全性

• Token 采用加密签名，确保安全
• Token 7 天后过期
• 发件人邮箱必须与 token 授权邮箱匹配
• 处理完成后会发送确认/错误邮件

路由规则

根据 method patterns 将 HITL 请求路由到特定电子邮件地址。

规则结构

{
  "name": "Approvals to Finance",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "[email protected]",
  "assign_from_input": "manager_email"
}

匹配模式

Pattern	Description	Example Match
approve_*	通配符（任意字符）	approve_payment, approve_vendor
review_?	单个字符	review_a, review_1
validate_payment	精确匹配	仅 validate_payment

分配优先级

1. 动态分配 (assign_from_input)：如果已配置，则从 flow state 中提取邮箱
2. 静态邮箱 (assign_to_email)：回退到配置的邮箱
3. 部署创建者：如果没有规则匹配，则使用 deployment creator 的邮箱

动态分配示例

如果你的 flow state 包含 {"sales_rep_email": "[email protected]"}，请配置：

{
  "name": "Route to Sales Rep",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}

请求会自动分配给 [email protected]。

Tip

Use Case：从 CRM、数据库或前一个 flow step 中提取 assignee，用于把审核动态路由给合适的人。

自动响应

如果在超时内没有人回复，系统会自动响应 HITL 请求。这样可确保 flows 不会无限期挂起。

配置

Setting	Description
Enabled	切换以启用自动响应
Timeout (minutes)	自动响应前等待的时间
Default Outcome	响应值（必须匹配某个 emit option）

使用场景

• SLA compliance：确保 flows 不会无限期挂起
• 默认批准：在超时后自动批准低风险请求
• 优雅降级：当审核者不可用时，使用安全默认值继续执行

Warning

使用自动响应时请谨慎。只应在默认回复可接受的非关键审核场景中启用它。

审核流程

Dashboard 界面

HITL 审核界面为审核者提供了简洁、聚焦的体验：

• Markdown Rendering：用于审核内容的富文本格式和语法高亮
• Context Panel：查看 flow state、执行历史和相关信息
• Feedback Input：提供详细反馈和评论，并作出决定
• Quick Actions：一键 emit option 按钮，可附加可选评论

回复方式

审核者可以通过三种渠道回复：

Method	Description
Email Reply	直接回复通知邮件
Dashboard	使用 Enterprise dashboard UI
API/Webhook	通过 API 程序化回复

历史与审计轨迹

每次 HITL 交互都会被完整记录：

• 决策历史（approve/reject/revise）
• 审核者身份和时间戳
• 提供的反馈和评论
• 回复方式（email/dashboard/API）
• 响应时间指标

分析与监控

通过全面分析跟踪 HITL 性能。

性能仪表板

响应时间

按审核者或 flow 监控平均和中位响应时间。

量趋势

分析审核量模式，以优化团队容量。

决策分布

查看不同审核类型中的批准/拒绝率。

SLA Tracking

跟踪在 SLA 目标内完成的审核比例。

审计与合规

面向企业的审计能力，适用于监管要求：

• 带时间戳的完整决策历史
• 审核者身份验证
• 不可变审计日志
• 用于合规报告的导出能力

常见用例

Security Reviews

Use Case：带人工验证的内部安全问卷自动化

• AI 生成安全问卷的回复
• 安全团队通过电子邮件审查并验证准确性
• 通过批准的回复会汇总到最终提交中
• 为合规提供完整审计轨迹

Content Approval

Use Case：需要法务/品牌审核的营销内容

• AI 生成营销文案或社交媒体内容
• 路由到品牌团队邮箱进行语气/风格审核
• 批准后自动发布

Financial Approvals

Use Case：报销单、合同条款、预算分配

• AI 对财务请求进行预处理和分类
• 根据金额阈值使用动态分配进行路由
• 为财务合规维护完整审计轨迹

Dynamic Assignment from CRM

Use Case：把审核路由给 CRM 中的账户所有者

• Flow 从 CRM 中获取账户所有者邮箱
• 将邮箱存入 flow state（例如 account_owner_email）
• 使用 assign_from_input 自动将请求路由给合适的人

Quality Assurance

Use Case：在交付给客户之前验证 AI 输出

• AI 生成面向客户的内容或回复
• QA 团队通过电子邮件通知进行审核
• 反馈循环随着时间推移改进 AI 性能

Webhooks API

当你的 Flows 因人工反馈而暂停时，你可以配置 webhooks，把请求数据发送到你自己的应用。这可以实现：

• 构建自定义审批 UI
• 与内部工具集成（Jira、ServiceNow、自定义仪表板）
• 将审批路由到第三方系统
• 移动应用通知
• 自动决策系统

配置 Webhooks

1. 进入 Settings

   打开你的 Deployment → Settings → Human in the Loop

2. 展开 Webhooks 区域

   点击展开 Webhooks 配置

3. 添加你的 Webhook URL

   输入你的 webhook URL（生产环境必须使用 HTTPS）

4. 保存配置

   点击 Save Configuration 以启用

你可以配置多个 webhooks。每个激活的 webhook 都会接收所有 HITL events。

Webhook 事件

你的 endpoint 会接收到这些事件的 HTTP POST 请求：

Event Type	触发时机
new_request	flow 暂停并请求人工反馈时

Webhook Payload

所有 webhooks 都会接收如下结构的 JSON payload：

{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "Please review this article for publication.",
    "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]"
}

响应请求

要提交反馈，请 POST 到 webhook payload 中包含的 callback_url。

POST {callback_url}
Content-Type: application/json

{
  "feedback": "Approved. Great article!",
  "source": "my_custom_app"
}

安全

Info

所有 webhook 请求都会使用 HMAC-SHA256 进行加密签名，以确保真实性并防止篡改。

Webhook 安全性

• HMAC-SHA256 signatures：每个 webhook 都包含加密签名
• Per-webhook secrets：每个 webhook 都有自己的唯一 signing secret
• Encrypted at rest：签名 secret 会在数据库中加密存储
• Timestamp verification：防止重放攻击

Signature Headers

每个 webhook 请求都会包含以下 headers：

Header	Description
X-Signature	HMAC-SHA256 signature：sha256=<hex_digest>
X-Timestamp	请求签名时的 Unix timestamp

验证

通过计算以下内容进行验证：

import hmac
import hashlib

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

if hmac.compare_digest(expected, signature):
    # Valid signature

错误处理

你的 webhook endpoint 应返回 2xx status code 以确认收到请求：

Your Response	Our Behavior
2xx	webhook 成功送达
4xx/5xx	记录为失败，不重试
Timeout (30s)	记录为失败，不重试

安全与 RBAC

Dashboard Access

HITL access 由部署级别控制：

Permission	Capability
manage_human_feedback	配置 HITL 设置，查看所有请求
respond_to_human_feedback	回复请求，查看分配给自己的请求

Email Response Authorization

对于电子邮件回复：

1. reply-to token 会编码授权邮箱
2. 发件人邮箱必须与 token 中的邮箱匹配
3. token 不能过期（默认 7 天）
4. 请求必须仍然处于 pending 状态

审计轨迹

所有 HITL 操作都会被记录：

• 请求创建
• 分配更改
• 回复提交（包含来源：dashboard/email/API）
• flow 恢复状态

故障排查

电子邮件未发送

1. 检查配置中是否启用了 “Email Notifications”
2. 验证路由规则是否匹配 method name
3. 验证 assignee email 是否有效
4. 如果没有规则匹配，检查 deployment creator fallback

邮件回复未被处理

1. 检查 token 是否过期（默认 7 天）
2. 验证发件人邮箱是否与分配邮箱匹配
3. 确保请求仍处于 pending（尚未被回复）

Flow 未继续执行

1. 在 dashboard 中检查请求状态
2. 验证 callback URL 是否可访问
3. 确认 deployment 仍在运行

最佳实践

Tip

从简单开始：先对 deployment creator 启用电子邮件通知，然后随着工作流成熟再添加路由规则。

1. 使用动态分配：从 flow state 中提取 assignee emails，以获得灵活路由。

2. 配置自动响应：为非关键审核设置 fallback，避免 flows 挂起。

3. 监控响应时间：使用分析功能找出瓶颈并优化审核流程。

4. 让审核消息保持清晰：在 @human_feedback 装饰器中编写清晰、可执行的消息。

5. 测试邮件流程：在进入生产之前发送测试请求，确认邮件投递正常。

相关资源

Flows 中的 Human Feedback

@human_feedback 装饰器的实现指南

Flow HITL Workflow Guide

配置 HITL 工作流的分步指南

RBAC 配置

为你的组织配置基于角色的访问控制

Webhook Streaming

设置实时事件通知