HumanLayer：开源 AI 智能体人类监督工具集，实现高风险操作管控与多场景协同

一、HumanLayer是什么

HumanLayer是一款开源的API与SDK工具集，旨在为AI智能体（Agent）提供人类监督能力，支持AI在执行高风险操作（如发送邮件、修改私人数据等）时触发人类审批、获取人类反馈或咨询建议。该工具兼容主流LLM（OpenAI/Llama/Claude）与AI框架（LangChain/CrewAI），通过多渠道通知（Slack/Email/Discord等）实现人类与AI的高效协同，解决LLM可靠性不足、 hallucination（幻觉）等问题，确保高风险操作的安全性与准确性，适用于客户沟通、数据管理、内容发布等多类业务场景。

在AI智能体（Agent）逐渐普及的背景下，工具调用成为AI实现复杂任务的核心能力——从查询数据、管理日程到操作数据库、发布内容，AI通过调用工具可大幅提升工作效率。但与此同时，高价值的工具往往伴随着高风险：例如让AI直接发送客户邮件可能因内容不当引发投诉，允许AI修改生产环境数据库可能导致数据丢失，这些“高风险操作”即便只有10%的失误率，也可能给个人或企业带来严重损失。

HumanLayer正是为解决这一痛点而生的开源工具：它是一套包含API与SDK的工具集，核心功能是在AI智能体与工具之间搭建“人类监督层”，让AI在执行关键操作时必须与人类交互（如获取审批、咨询建议），从而平衡AI的自动化能力与操作安全性。

简单来说，HumanLayer的定位可概括为：

• 不是替代AI：不改变AI的推理逻辑与工具调用能力，而是在AI与工具之间增加“安全闸门”；

• 不是独立框架：无需替换现有LLM或AI开发框架，可无缝集成到已有工作流中；

• 专注“人类在环”：核心价值是让人类参与AI的高风险决策环节，解决LLM可靠性不足的问题。

从AI智能体发展阶段来看，HumanLayer主要服务于“第二代Agentic Assistants（智能体助手）”与“第三代Autonomous Agents（自治智能体）”：

• 第二代智能体：由人类发起任务（如“发送欢迎邮件给新客户”），AI通过框架驱动工具调用完成任务，HumanLayer可在此阶段为工具调用增加审批环节；

• 第三代自治智能体：无需人类主动触发，AI自主规划任务、管理进度（如“每日检查LinkedIn收件箱并回复咨询”），HumanLayer可支持AI在需要时主动联系人类获取反馈，确保任务方向正确。

二、功能特色

HumanLayer的功能围绕“人类监督AI操作”展开，核心特色可通过下表清晰呈现，涵盖核心能力、兼容性、交互渠道等关键维度：

此外，HumanLayer还具备“风险分级适配”特性——针对不同风险等级的操作提供差异化监督策略，具体风险分级如下表：

三、技术细节

1. 核心工作原理

HumanLayer的工作逻辑基于“装饰器（Decorator）”与“工具注册”机制，核心流程可分为3步：

1. 初始化SDK：开发者通过代码初始化HumanLayer客户端，建立与服务的连接；

2. 标记监督函数：使用装饰器（如@hl.require_approval()）标记需要监督的函数，或注册“人类工具”（hl.human_as_tool()）；

3. 触发交互闭环：AI调用标记函数时，HumanLayer自动拦截请求，通过指定渠道通知人类；人类反馈后，结果同步给LLM，决定是否继续执行函数。

以“发送邮件”场景为例，具体流程如下图所示：

AI智能体 → 调用send_email()函数（已标记@hl.require_approval()） → HumanLayer拦截请求 → 向指定人类发送审批通知（含邮件内容） → 人类审批（通过/拒绝+反馈） → HumanLayer将结果同步给AI → AI执行函数（通过）或调整内容（拒绝）

2. 技术栈与架构

HumanLayer支持两种主流开发语言，技术栈清晰，架构轻量易集成：

其架构特点是“去中心化集成”——无需部署独立服务器（基础功能依赖HumanLayer公共服务，也支持未来自定义服务器部署），SDK直接嵌入AI工作流，不增加额外系统复杂度。

3. 关键功能技术实现

（1）函数审批（@hl.require_approval()）

• 实现逻辑：装饰器通过包装目标函数，在函数执行前插入“请求审批”逻辑；若审批通过，执行原函数；若拒绝，抛出异常并将反馈传递给LLM。

• 参数配置：支持自定义审批接收人（如approvers=["team@example.com"]）、通知渠道（如channel="slack"）、审批超时时间（如timeout=3600秒）。

• 数据传递：审批请求会携带函数的完整参数（如send_email的to、subject、body），确保人类可全面评估操作合理性。

（2）人类作为工具（hl.human_as_tool()）

• 实现逻辑：将“人类”封装为AI可调用的工具（符合LangChain/CrewAI等框架的工具规范），AI调用时会生成“咨询请求”（含问题描述与上下文），人类回复后以“工具输出”形式返回给AI。

• 使用场景：支持自由文本咨询（如“这个客户需求的优先级如何”）、选项选择（如“邮件发送时间选上午10点还是下午2点”），满足不同交互需求。

（3）多渠道通知

• 实现逻辑：HumanLayer通过“渠道适配器”模块支持不同平台的通知，例如Slack通过Slack API发送消息，Email通过SMTP协议发送邮件，CLI通过命令行输出提示。

• 一致性体验：不同渠道的请求内容格式统一（含操作类型、参数、反馈入口），人类无需适应不同渠道的交互差异。

四、应用场景

HumanLayer的核心价值是“管控高风险操作、提升AI可靠性”，适用于各类需要AI与人类协同的业务场景，以下为典型场景示例：

1. 客户沟通自动化

场景描述：企业使用AI智能体自动处理客户沟通（如新客户欢迎邮件、售后问题回复、活动通知），但邮件内容需符合品牌调性，避免表述不当。
HumanLayer应用方式：

• 用@hl.require_approval()装饰send_email()函数，AI生成邮件后自动发送审批请求给客服团队；

• 客服通过Slack查看邮件内容，点击“通过”则AI发送邮件，或添加反馈（如“需补充售后联系方式”）让AI修改；

• 若客户回复邮件，AI可调用hl.human_as_tool()咨询客服：“客户提到的退款问题是否需要优先处理”。

价值：确保客户沟通内容准确，减少因AI生成低质量文本导致的客户投诉，同时降低客服团队的重复工作（仅需审批/反馈，无需手动写邮件）。

2. CRM数据管理

场景描述：AI智能体定期同步客户数据到CRM系统（如将网站注册用户添加到CRM、更新客户购买记录），但CRM数据错误可能影响销售决策，需避免AI误操作。
HumanLayer应用方式：

• 用@hl.require_approval()装饰update_crm_record()函数，AI修改数据前需经销售团队审批；

• 审批请求包含“原数据”“修改后数据”“修改原因”，销售通过Email确认是否允许修改；

• 若AI无法识别客户归属（如同一客户有两个账号），可调用hl.human_as_tool()向销售咨询：“客户A的两个账号是否需要合并”。

价值：防止AI因数据理解错误导致的CRM数据混乱，保障销售团队使用数据的准确性。

3. 社交媒体内容发布

场景描述：企业用AI智能体生成社交媒体内容（如LinkedIn产品动态、Twitter活动宣传），内容需符合合规要求（如不涉及虚假宣传），且需与品牌风格一致。
HumanLayer应用方式：

• 用@hl.require_approval()装饰post_social_media()函数，AI生成内容后发送给市场团队审批；

• 市场团队通过Discord查看内容，支持直接修改（如“将‘最先进’改为‘行业领先’”）并同步给AI；

• AI可调用hl.human_as_tool()咨询：“这个产品动态是否需要添加客户案例”，获取市场团队建议。

价值：降低社交媒体内容的合规风险，确保内容符合品牌调性，同时提升内容生成效率。

4. 内部流程自动化

场景描述：企业用AI智能体处理内部流程（如员工报销审核、加班申请反馈），流程需符合公司制度，避免AI误判。
HumanLayer应用方式：

• 用@hl.require_approval()装饰approve_expense()函数，AI初步审核报销单后，需财务团队最终审批；

• 财务团队通过CLI（命令行）查看报销明细（如“金额是否超标、发票是否合规”），快速确认审批结果；

• 若AI无法判断报销类目（如“团建费用是否属于福利支出”），可调用hl.human_as_tool()向HR咨询。

价值：规范内部流程执行，减少AI因不熟悉公司制度导致的误判，提升流程处理效率。

五、使用方法

HumanLayer支持Python与TypeScript/JS两种语言，以下为详细使用步骤，包含环境准备、核心功能调用、框架集成示例：

1. 环境准备

（1）Python SDK（推荐Python 3.8+）

1. 安装SDK：

   pip install humanlayer

2. 配置环境变量（可选，也可在代码中直接传入）：

• 创建.env文件，添加API密钥（需从HumanLayer官网获取）：

  HUMANLAYER_API_KEY=your_api_key

3. 初始化客户端：

   from humanlayer import HumanLayer
   import os
   from dotenv import load_dotenv
   
   # 加载环境变量
   load_dotenv()
   # 初始化HumanLayer
   hl = HumanLayer(api_key=os.getenv("HUMANLAYER_API_KEY"))

（2）TypeScript/JS SDK（推荐Node.js 16+）

1. 安装SDK：

   npm install @humanlayer/sdk

2. 配置环境变量：

• 创建.env文件：

  HUMANLAYER_API_KEY=your_api_key

3. 初始化客户端：

   import { HumanLayer } from "@humanlayer/sdk";
   import dotenv from "dotenv";
   
   // 加载环境变量
   dotenv.config();
   // 初始化HumanLayer
   const hl = new HumanLayer({ apiKey: process.env.HUMANLAYER_API_KEY });

2. 核心功能使用示例

（1）函数审批（@hl.require_approval()）

以“发送客户欢迎邮件”为例，Python代码如下：

from humanlayer import HumanLayer
import os
from dotenv import load_dotenv

load_dotenv()
hl = HumanLayer(api_key=os.getenv("HUMANLAYER_API_KEY"))

# 用装饰器标记需要审批的函数
@hl.require_approval(
  approvers=["customer_support@example.com"], # 审批人邮箱
  channel="slack" # 通知渠道（slack/email/cli）
)
def send_welcome_email(to: str, subject: str, body: str):
  """发送新客户欢迎邮件"""
  # 实际发送邮件的逻辑（如使用smtplib或邮件API）
  print(f"发送邮件给：{to}，主题：{subject}，内容：{body}")
  return {"status": "success", "message": "邮件已发送"}

# 模拟AI调用函数（使用任意工具调用框架）
def run_ai_task():
  # AI生成邮件内容
  email_to = "danny@example.com"
  email_subject = "欢迎加入我们的平台！"
  email_body = """
  亲爱的Danny：
  很高兴您完成了注册！您只需再邀请1位团队成员，即可解锁全部功能。
  如有疑问，可随时联系客服团队。
  祝您使用愉快！
  """
  # 调用需要审批的函数（会触发HumanLayer审批）
  result = send_welcome_email(
    to=email_to,
    subject=email_subject,
    body=email_body
  )
  print("函数执行结果：", result)

# 执行AI任务
if __name__ == "__main__":
  run_ai_task()

执行流程：

1. 运行代码后，HumanLayer会向customer_support@example.com的Slack账号发送审批通知；

2. 客服在Slack中查看邮件内容，点击“Approve”（通过）或“Reject”（拒绝）；

3. 若通过，send_welcome_email()函数执行，发送邮件；若拒绝，函数不执行，AI会收到拒绝反馈（如“邮件需添加客服电话”）。

（2）人类作为工具（hl.human_as_tool()）

以“AI咨询邮件内容是否合适”为例，Python代码如下：

from humanlayer import HumanLayer
import os
from dotenv import load_dotenv

load_dotenv()
hl = HumanLayer(api_key=os.getenv("HUMANLAYER_API_KEY"))

# 创建“人类工具”
contact_support = hl.human_as_tool(
  recipients=["customer_support@example.com"], # 接收咨询的人
  channel="email" # 咨询渠道
)

# 发送邮件函数（无需强制审批，但需AI咨询建议）
def send_promotion_email(to: str, subject: str, body: str):
  """发送促销活动邮件"""
  print(f"发送邮件给：{to}，主题：{subject}，内容：{body}")
  return {"status": "success"}

# 模拟AI调用工具（集成LangChain框架）
from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI

def run_langchain_agent():
  # 初始化LLM（OpenAI GPT-4o）
  llm = ChatOpenAI(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY"))
  # 注册工具（发送邮件+人类咨询）
  tools = [
    {
      "name": "send_promotion_email",
      "func": send_promotion_email,
      "description": "发送促销活动邮件给客户，参数包括to（邮箱）、subject（主题）、body（内容）"
    },
    {
      "name": "contact_support",
      "func": contact_support,
      "description": "咨询客服团队，获取邮件内容建议或操作指导"
    }
  ]
  # 初始化Agent
  agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
  )
  # 执行AI任务
  agent.run("生成一封促销邮件，内容为‘夏季活动全场8折’，发送给客户lisa@example.com。先咨询客服团队内容是否合适，再决定是否发送。")

if __name__ == "__main__":
  run_langchain_agent()

执行流程：

1. AI生成促销邮件内容后，会调用contact_support工具，向客服发送咨询请求（含邮件内容）；

2. 客服通过Email回复建议（如“需添加活动时间：6月1日-6月30日”）；

3. AI接收反馈后，修改邮件内容，再次调用contact_support确认（或直接发送，根据prompt逻辑）。

3. 框架集成示例（LangChain/CrewAI）

（1）LangChain集成

# 安装依赖
# pip install humanlayer langchain openai

from humanlayer import HumanLayer
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.chat_models import ChatOpenAI
from langchain.tools import StructuredTool
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
import os
from dotenv import load_dotenv

load_dotenv()
hl = HumanLayer(api_key=os.getenv("HUMANLAYER_API_KEY"))

# 1. 定义需要审批的工具函数
@hl.require_approval(approvers=["finance@example.com"], channel="email")
def process_refund(customer_id: str, amount: float, reason: str) -> dict:
  """处理客户退款请求，需财务团队审批"""
  return {
    "status": "approved",
    "customer_id": customer_id,
    "amount": amount,
    "message": f"退款{amount}元已处理，原因：{reason}"
  }

# 2. 注册LangChain工具
tools = [
  StructuredTool.from_function(process_refund)
]

# 3. 配置Prompt
prompt = ChatPromptTemplate.from_messages([
  ("system", "你是处理客户退款的AI助手，处理退款前必须通过财务团队审批。"),
  ("user", "{input}"),
  MessagesPlaceholder(variable_name="agent_scratchpad"),
])

# 4. 初始化Agent
llm = ChatOpenAI(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY"))
agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 5. 执行任务
if __name__ == "__main__":
  agent_executor.invoke({
    "input": "处理客户ID为C12345的退款请求，金额500元，原因是产品质量问题。"
  })

（2）CrewAI集成

# 安装依赖
# pip install humanlayer crewai openai

from humanlayer import HumanLayer
from crewai import Agent, Task, Crew
from crewai_tools import tool
import os
from dotenv import load_dotenv

load_dotenv()
hl = HumanLayer(api_key=os.getenv("HUMANLAYER_API_KEY"))

# 1. 定义带审批的工具
@tool
@hl.require_approval(approvers=["marketing@example.com"], channel="slack")
def publish_blog_post(title: str, content: str, author: str) -> dict:
  """发布博客文章，需市场团队审批内容合规性"""
  return {
    "status": "published",
    "title": title,
    "author": author,
    "message": "博客已发布到官网"
  }

# 2. 定义Agent
content_writer = Agent(
  role="内容 writer",
  goal="生成高质量的产品博客文章，突出产品优势",
  backstory="你是经验丰富的科技产品博客作者，擅长用通俗易懂的语言描述技术功能。",
  llm=ChatOpenAI(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY")),
  tools=[publish_blog_post]
)

# 3. 定义Task
task = Task(
  description="生成一篇关于HumanLayer的博客文章，标题包含‘AI监督工具’，内容介绍核心功能与应用场景。生成后调用publish_blog_post工具发布，作者为‘技术团队’。",
  agent=content_writer,
  expected_output="博客文章发布成功的反馈结果"
)

# 4. 执行Crew
if __name__ == "__main__":
  crew = Crew(agents=[content_writer], tasks=[task], verbose=True)
  result = crew.kickoff()
  print("任务结果：", result)

六、常见问题解答（FAQ）

1. HumanLayer需要部署服务器吗？

不需要。当前版本的HumanLayer SDK通过调用官方公共服务实现通知与审批管理，开发者无需部署独立服务器；未来将支持“自定义服务器”（Open Protocol for BYO server，见Roadmap），企业可部署私有服务以满足数据隐私需求。

2. 审批请求会过期吗？如果人类长时间不回复怎么办？

支持设置审批超时时间（通过timeout参数，单位：秒），例如@hl.require_approval(timeout=3600)表示1小时内未审批则自动拒绝。超时后，AI会收到“审批超时”反馈，可根据prompt逻辑重新发起请求或终止任务。

3. 如何自定义审批通知的内容格式？

当前支持通过message_template参数自定义通知内容，例如：

@hl.require_approval(
  message_template="需要您审批【{function_name}】操作：\n参数：{parameters}\n请在1小时内处理。"
)
def send_email(to: str, subject: str, body: str):
  ...

其中{function_name}会自动替换为函数名（如send_email），{parameters}会自动替换为函数参数（如to: danny@example.com）。

4. HumanLayer支持多轮审批吗？（如“先部门审批，再公司审批”）

当前版本（Beta）暂不支持多轮审批，仅支持单级审批；未来将通过“Composite Contact Channels”（见Roadmap，当前Work in Progress）支持多轮审批，可配置“部门→公司”“初级审核→高级审核”等流程。

5. 免费使用有额度限制吗？

HumanLayer作为开源项目，SDK本身免费使用；官方公共服务的免费额度需参考官网说明（当前未公开具体额度），企业可通过部署自定义服务器（未来功能）实现无额度限制使用。

6. 如何查看审批历史记录？

当前可通过CLI命令查看审批记录（CLI功能已支持Beta），例如：

# Python CLI
hl list_approvals --status approved

# TypeScript CLI
npx humanlayer list-approvals --status rejected

未来将支持Web控制台查看历史记录，方便团队追溯审批流程。

7. 若LLM生成的函数参数有误（如邮箱格式错误），HumanLayer能检测吗？

HumanLayer不直接检测参数格式错误，需开发者在函数内部添加参数校验逻辑，例如：

import re
from humanlayer import HumanLayer

hl = HumanLayer()

def is_valid_email(email: str) -> bool:
  """校验邮箱格式"""
  pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
  return re.match(pattern, email) is not None

@hl.require_approval()
def send_email(to: str, subject: str, body: str):
  if not is_valid_email(to):
    raise ValueError(f"邮箱格式错误：{to}")
  # 发送邮件逻辑
  ...

参数校验失败时，函数会直接抛出异常，不触发审批请求。

8. 支持哪些编程语言之外的扩展？

当前仅支持Python与TypeScript/JS；未来计划通过社区贡献扩展其他语言（如Go、Java），开发者也可基于开源代码自行实现其他语言的SDK（遵循Apache 2 License）。

七、相关链接

• 开源地址：https://github.com/humanlayer/humanlayer

• 官网地址：https://www.humanlayer.dev/

八、总结

HumanLayer作为一款开源的AI智能体人类监督工具集，核心价值在于通过“审批拦截”与“人类工具”机制，解决LLM在高风险操作中的可靠性问题，实现AI与人类的高效协同；其支持主流LLM与框架，兼容多渠道交互，可无缝集成到现有AI工作流中，无需重构技术栈，降低企业使用门槛。从功能上看，当前Beta版本已覆盖“函数审批”“人类工具”“多渠道通知”等核心需求，同时通过Roadmap规划了多轮审批、自定义服务器等扩展功能，社区贡献可进一步丰富生态；从应用上看，其适用于客户沟通、数据管理、内容发布等多类场景，能帮助企业在享受AI自动化效率的同时，规避操作风险。整体而言，HumanLayer为“AI+人类”协同模式提供了轻量、灵活的解决方案，是企业落地AI智能体的重要安全工具。