1. 从一条“爆款分享”说起HumanLayer 到底是什么最近在技术社区里一条关于“HumanLayer 智能体构建”的分享视频在三周内获得了 20 万观看。评论区讨论最多的不是某个炫酷 UI也不是某个大模型 API而是一个很实际的问题当 AI 智能体真正开始执行任务时我们如何确保它不会在错误的时间、错误的地点调用一个不该调的接口HumanLayer 恰好就是解决这个问题的工具。它不是一个大模型也不是一个完整的智能体平台而是一层专门为“智能体与外部世界交互”设计的权限确认与人工审批层。为了便于理解我们可以把它类比成现实生活中的“审批流”智能体本身是一个实习生能力很强但容易冲动。HumanLayer 是那个“需要领导审批”的门禁系统。当智能体想发送邮件、支付订单、调用生产环境接口、删除数据时HumanLayer 会先拦截请求向人类发送一条确认消息。人类点击“允许”或“拒绝”后智能体才能继续往下走。这种机制在工业界被称为 Human-in-the-loop人在回路也是当前 AI 智能体从“演示玩具”走向“生产力工具”的关键一步。1.1 为什么“智能体构建分享”能获得高关注这期分享之所以能火背后其实是开发者群体需求的集中爆发大模型本身已经不再是瓶颈各种 API 随意调用真正难的是把智能体接入真实系统比如发送邮件、创建工单、查询数据库、调用内部 API一旦智能体出错轻则发错消息重则影响线上数据所以“怎么让智能体在受控的情况下干活”就成了刚需。HumanLayer 就是在这种背景下被越来越多开发者关注的。它提供了一套轻量、可嵌入的权限确认机制让智能体开发者在构建 agent 时不用自己从零实现审批系统直接把“人工确认”变成一个普通函数调用即可。1.2 本文适合谁阅读本文内容覆盖三个层次读者可以根据自己的基础选择性吸收完全没接触过智能体开发的新手建议先通读第 2、3 节理解智能体和 HumanLayer 的基本概念。正在做 agent 项目的开发者可以直接跳到第 4、5 节查看实战代码和工程方案。技术博主/内容创作者可以重点关注第 8 节分析为什么这期智能体构建分享能火以及如何规划自己的智能体教程内容。2. 智能体开发背景为什么需要 HumanLayer在进入代码之前先花一点时间把概念梳理清楚。因为很多人在看这类分享时会被“智能体”“Agent”“工作流”“多智能体”等词汇绕晕。2.1 智能体Agent通俗解释智能体是一个能自主感知环境、做出决策并执行动作的 AI 程序。它和普通聊天机器人的核心区别在于聊天机器人你问我答对话结束。智能体你给它一个目标它会自己拆分任务、调用工具、逐步完成然后在适当时候返回结果。举个例子普通聊天机器人“请帮我查一下今天下午是否有空闲会议室。”智能体调用日历 API - 查询会议室状态 - 对比参会人数 - 推荐合适时间 - 直接帮你预订并发送会议邀请。在实现上智能体通常由一个或多个大模型LLM驱动配合工具调用Function Calling / Tool Use来完成具体操作。2.2 智能体开发的主要痛点2.2.1 工具权限难以控制当智能体调用工具时它本质上是让大模型来决定“什么时候调用哪个函数”。但大模型并不完美可能会出现参数传错比如把“发送给自己”写成“发送给所有人”时间判断失误比如在非工作时间推送通知上下文理解偏差比如用户只是“想看一下”某个订单智能体却直接执行了“删除订单”操作。2.2.2 缺少人工拦截机制很多智能体框架默认是“全自动执行”的。一旦触发条件成立智能体会连续调用多个工具。如果中间任何一个环节出错可能酿成较大问题。2.2.3 审计和追溯困难在真实业务中我们需要知道“哪一次调用是谁批准的”“智能体当时为什么这么做”。如果缺少记录事故发生后很难排查。2.3 HumanLayer 的定位HumanLayer 正是针对这些痛点设计的。它的核心机制很简单用户下发任务 ↓ AI 智能体规划任务 ↓ 调用外部工具前触发 HumanLayer ↓ HumanLayer 向人类发送确认请求 ↓ 人工批准/拒绝 ↓ 智能体继续执行或放弃这一层可以接在任意工具调用之前比如发送邮件、执行 SQL、调用支付接口、修改生产配置等。HummanLayer 还内置了上下文消息传递机制让智能体可以向人类解释“我为什么要做这件事”让审批人有足够信息做出判断。注意HumanLayer 是较新的开源/第三方工具其 API 和包名可能会随版本迭代调整。本文展示的是核心设计思路和示例代码你在实际使用时请以官方最新文档为准。3. 环境准备与版本说明开始动手之前先准备好开发环境。本文示例以 Python 为主因为这是目前智能体开发最主流的语言。3.1 基础环境清单依赖项建议版本/方案说明操作系统Windows / macOS / Linux 均可无特殊限制Python3.10需要支持新版类型语法pip最新版用于安装依赖大模型 APIOpenAI / Anthropic / 国内大模型 API需要能访问模型接口HumanLayer SDK使用最新稳定版通过 pip 安装IDEVS Code / PyCharm推荐支持 Python 类型检查的 IDE3.2 安装 HumanLayer SDK假设项目名称是hl-agent-demo我们先初始化一个虚拟环境mkdir hl-agent-demo cd hl-agent-demo python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate然后安装依赖pip install humanlayer python-dotenv openai提示python-dotenv用于读取.env文件openai是演示用的模型 SDK。如果你使用其他模型服务相应替换即可。3.3 准备 API Key在项目根目录创建.env文件# 模型 API Key按你实际使用的服务填写 OPENAI_API_KEYsk-xxxx # HumanLayer API Key可选本地模式可暂不配置 HUMANLAYER_API_KEYhl-xxxx如果你是本地测试HumanLayer 可以运行在local mode也就是直接把审批消息打印到终端适合开发和调试。后面第 4 节的示例就基于 local mode。4. 核心概念拆解HumanLayer 的工作机制这一节是整篇文章的技术核心。理解清楚后面写代码才会顺畅。4.1 核心对象HumanLayer 生态中最核心的是三个对象对象作用HumanLayer主客户端负责初始化配置是所有功能的入口HumanContact联系人封装表示“需要接收确认消息的人”FunctionCall函数调用封装代表“智能体想要执行的工具调用”其中 HumanContact 又分为两种SlackContact通过 Slack 联系人类TelegramContact通过 Telegram 联系人类本地模式下可以简化为直接打印到终端。4.2 核心方法HumanLayer 提供了两个核心方法使用时需要区分human_layer.call_human()发送一条消息给人类等待人类回复。适合需要人类提供额外信息的场景。human_layer.approve_function_call()发送一个函数调用请求等待人类批准或拒绝。适合需要授权执行的场景。二者的区别在于call_human是获取信息比如“请提供退款订单号”approve_function_call是请求授权比如“用户要求删除订单 10086是否允许”4.3 一次函数调用的完整生命周期在 HumanLayer 的机制下智能体调用一次函数需要经历以下阶段大模型判断需要调用某个工具智能体包装调用参数生成一个 FunctionCall 对象调用human_layer.approve_function_call()HumanLayer 将请求发送给指定联系人人类查看请求点击允许或拒绝HumanLayer 返回审批结果智能体根据结果决定是否真正执行函数。这里最重要的设计是HumanLayer 只是审批门禁而不是执行器。智能体在收到“批准”结果后仍然需要自己调用目标函数在收到“拒绝”结果后也可以执行自己的兜底逻辑。4.4 权限确认的常见误区很多初学者容易混淆“权限确认”和“业务执行”。举几个例子误区错误理解正确理解HumanLayer 会帮我发送邮件错误它只负责审批发送邮件的代码仍由你自己写HumanLayer 是防火墙错误它是人机交互层它不做网络层面的拦截等到审批后就不用管了错误还要处理审批结果需要根据 approve/reject 分支处理5. 完整实战案例构建一个带人工确认的 Email 发送智能体下面我们通过一个真实场景来把 HumanLayer 串起来。假设我们要开发一个“邮件发送助手”智能体用户告诉智能体“给张三发一封会议提醒邮件。”智能体解析出收件人、主题、正文。在真正调用邮件 API 之前智能体先请求人类确认。人类点击“允许”邮件才真正发送。5.1 项目结构hl-agent-demo ├── .env # API Key 配置 ├── requirements.txt # 依赖清单 ├── agent.py # 智能体主入口 ├── tools.py # 自定义工具函数 └── humanlayer_config.py # HumanLayer 配置5.2 编写工具函数先创建一个简单的工具函数模拟发送邮件。为了安全起见这里不接入真实邮件服务而是打印日志并返回成功状态。# 文件路径tools.py def send_email(recipient: str, subject: str, body: str) - str: 模拟发送邮件。 实际项目中这里可以替换为 SMTP、SendGrid、阿里云邮件推送等。 # 在实际项目中你应该把邮件发送逻辑放在这里 # 这里使用打印模拟方便本地演示 print(f 模拟发送邮件 ) print(f收件人: {recipient}) print(f主题: {subject}) print(f正文: {body}) print(f) return 邮件发送成功这个函数很简单但它代表任何“有副作用的操作”。在真实项目中发送邮件、修改数据库、调用支付接口都属于这类操作需要被保护。5.3 初始化 HumanLayer接下来创建一个配置文件用于初始化 HumanLayer 客户端。# 文件路径humanlayer_config.py from humanlayer import HumanLayer, HumanContact def create_humanlayer(contact: HumanContact) - HumanLayer: 创建 HumanLayer 客户端。 默认使用 local mode审批消息会直接打印到终端。 如果配置了 HUMANLAYER_API_KEY则使用云端模式。 hl HumanLayer( contactcontact, # 默认是 local mode便于开发调试 # 生产环境请配置真实 API Key ) return hl5.4 编写智能体主逻辑现在编写核心的agent.py。这里的关键点在于使用 OpenAI 的函数调用Function Calling能力让大模型决定何时调用send_email。在真正调用send_email之前先通过approve_function_call请求人工审批。只有审批通过后才执行send_email。# 文件路径agent.py import json import os from dotenv import load_dotenv from openai import OpenAI from humanlayer import HumanContact from humanlayer_config import create_humanlayer from tools import send_email load_dotenv() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) # 使用 local mode审批消息会打印到终端 contact HumanContact( emaildeveloperexample.com, slack_handledeveloper, telegram_handledeveloper, ) hl create_humanlayer(contact) # 定义可供大模型调用的工具 tools [ { type: function, function: { name: send_email, description: 发送一封电子邮件给指定收件人, parameters: { type: object, properties: { recipient: {type: string, description: 收件人邮箱地址}, subject: {type: string, description: 邮件主题}, body: {type: string, description: 邮件正文}, }, required: [recipient, subject, body], }, }, } ] def run_agent(user_message: str): 运行智能体主流程 messages [ {role: system, content: 你是一个邮件助手帮用户发送邮件。发送前需要获得授权。}, {role: user, content: user_message}, ] response client.chat.completions.create( modelgpt-4o, # 根据你实际可用的模型调整 messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message # 如果大模型没有要求调用工具直接返回文本 if not message.tool_calls: print(fAI 回复{message.content}) return message.content # 如果有工具调用遍历处理并请求人工审批 for tool_call in message.tool_calls: function_name tool_call.function.name function_args json.loads(tool_call.function.arguments) if function_name send_email: # 构造一个描述本次调用的文本方便人类判断 call_desc ( f智能体请求发送邮件\n f收件人{function_args[recipient]}\n f主题{function_args[subject]}\n f正文{function_args[body]}\n ) print(\n 等待人工审批 ) print(call_desc) # 调用 HumanLayer 请求审批 approval hl.approve_function_call( call_desccall_desc, fn_namefunction_name, fn_argsfunction_args, ) if approval.status approved: print(人工已批准开始执行发送邮件...) result send_email(**function_args) return result else: print(人工已拒绝邮件未发送。) return 用户拒绝了邮件发送请求。 return 没有可执行的操作。 if __name__ __main__: # 测试示例 run_agent(请给 zhangsanexample.com 发一封邮件主题是项目进度会议提醒正文是明天下午3点会议室A开会请准时参加。)5.5 运行与验证在终端运行python agent.py预期输出大致如下 等待人工审批 智能体请求发送邮件 收件人zhangsanexample.com 主题项目进度会议提醒 正文明天下午3点会议室A开会请准时参加。 HumanLayer local mode: 请在终端输入 allow / deny在 local 模式下HumanLayer 会在终端提示你输入allow或deny。输入allow之后你会看到人工已批准开始执行发送邮件... 模拟发送邮件 收件人: zhangsanexample.com 主题: 项目进度会议提醒 正文: 明天下午3点会议室A开会请准时参加。 邮件发送成功如果输入deny则输出人工已拒绝邮件未发送。这样一个最简单的“带人工审批的智能体”就跑通了。6. 向真实业务延伸接入 Slack/Telegram 审批本地模式适合开发但真实业务中审批人不可能一直盯着终端。所以 HumanLayer 支持把审批消息推送到 Slack、Telegram 等即时通讯工具。6.1 Slack 审批接入方式在配置 HumanLayer 时将联系人和审批通道绑定即可。下面是典型配置思路from humanlayer import HumanLayer, HumanContact, SlackContact slack_contact SlackContact( channelC12345678, # Slack 频道 ID slack_tokenxoxb-xxxx, # Bot Token ) contact HumanContact( slackslack_contact, ) hl HumanLayer( api_keyos.getenv(HUMANLAYER_API_KEY), contactcontact, )配置完成后开发者可以把审批请求直接发送到指定的 Slack 频道。审批人不仅可以点击“允许/拒绝”还能和智能体对话询问更多上下文。6.2 审批消息上下文在实际业务中我们需要避免“一刀切”的机械审批。HumanLayer 提供了双向消息机制智能体可以在审批请求中附带上下文说明审批人可以向智能体追问智能体可以基于追问调整自己的计划然后再发起第二次审批。这就形成了一个“人机协商”的闭环。比如审批人为什么要给所有人群发邮件 智能体因为用户指令是通知所有项目成员这是项目成员列表请确认。 审批人先不要发改为只发送给核心成员。 智能体好的我重新构造收件人列表再次请求审批。这种设计可以大幅降低误操作风险同时避免打断智能体的自主工作流程。7. 智能体开发常见问题与排查思路在实际开发中很多人第一次把智能体接入 HumanLayer 时都会遇到一些常见问题。下面整理成表格方便快速排查。问题现象常见原因解决思路approve_function_call一直等待没有反应本地模式下没有在终端输入 allow/deny检查终端输入allow或deny审批通过后函数没有执行只有审批逻辑缺少业务执行代码在 approval.status approved 分支调用真实函数大模型频繁请求批准同一个操作system prompt 缺少约束在 system prompt 中强调“只在必须执行副作用操作时才请求审批”Slack 审批消息发不出去Token 权限不足或频道 ID 错误检查 Bot Token 的 scope确认频道邀请过 Bot模型不支持 function calling模型版本过旧或接口不支持更换支持 Tool Use 的模型或使用兼容接口审批结果返回超时API Key 配置错误检查 HUMANLAYER_API_KEY 环境变量生产环境误操作审批流配置只走了一个人设置多人审批或重要操作二次确认7.1 生产环境下的排查清单如果你在生成环境遇到问题可以按下面顺序排查检查 HumanLayer 云端服务状态检查审批联系人的联系方式是否配置正确检查网络是否能访问 HumanLayer API检查需要审批的函数是否被正确注册到大模型工具列表检查日志中是否记录了审批请求的 call_id使用 call_id 在 HumanLayer 后台查询审批状态如果审批长时间未响应设置超时策略与降级处理。7.2 避免审批风暴审批风暴是智能体开发中一个非常现实的问题。如果每执行一步都要人工审批智能体就失去了“智能”的意义但如果完全不审批风险又太高。实践中可以采取以下策略分级权限低风险操作自动执行高风险操作强制审批。敏感词触发当工具参数中包含“删除”“支付”“群发”“生产环境”等关键词时自动进入审批流。频率限制同一操作短时间内多次触发自动升级为人工审批。审批超时默认拒绝如果人工长时间未处理默认拒绝执行保证安全。下面给出一个分级审批的示例思路def should_require_approval(function_name: str, function_args: dict) - bool: 判断是否需要人工审批。 返回 True 表示需要审批False 表示自动执行。 # 高危操作关键词 high_risk_keywords [delete, remove, disable, refund, pay] # 函数名中包含高危关键词必须审批 if any(keyword in function_name.lower() for keyword in high_risk_keywords): return True # 参数中包含高危关键词必须审批 args_str json.dumps(function_args, ensure_asciiFalse).lower() if any(keyword in args_str for keyword in high_risk_keywords): return True # 低风险操作可以自动执行 return False在实际工程中你可以将这套判断逻辑接入权限中心、规则引擎或者内部审批系统形成更完整的权限策略。8. 为什么这期“智能体构建分享”能火内容拆解与启示回到开头的那个现象HumanLayer 智能体构建分享三周获 20 万观看。作为技术内容创作者这个现象很值得拆解。8.1 踩中了“智能体开发”的流量红利从搜索热词来看智能体相关的需求正在爆发式增长ai智能体开发人才需求大涨244%智能体开发教程、智能体搭建、多智能体、智能体工作流测试验证等词条搜索量持续走高大量开发者开始关注如何搭建智能体、如何开发 agent 智能体、如何选择智能体框架。也就是说“智能体”本身已经是技术内容的高流量赛道。而 HumanLayer 恰好站在“智能体应用落地”这个更细分的节点上话题天然具备稀缺性。8.2 选题差异化讲“安全边界”而不是“怎么调用模型”很多智能体教程都在讲如何调用大模型 API如何构建 prompt如何做 RAG如何选择向量数据库。但真正把智能体接入业务流程时开发者最担心的其实是失控。HumanLayer 这类工具解决了“智能体如何安全地使用工具”的问题这是一个被大多数教程忽略的盲区。这也是二十万观看背后的内容逻辑你不是在教别人怎么调 API你是在教别人怎么放心地把 API 交给 AI。8.3 具备“可复现性”一个视频或文章能火往往不是因为它有多高深而是因为看完就能动手做。HumanLayer 的本地模式让新手不需要复杂配置就能跑通一个 demo这正是技术教程最适合传播的形态安装依赖复制代码运行看到审批弹窗理解原理。8.4 给智能体内容创作者的建议如果你想围绕智能体构建持续输出建议重点关注以下几个方向方向内容建议智能体实战选一个业务场景完整拆解从 prompt 到工具调用的全流程智能体安全权限确认、审批流、防注入、token 使用限额多智能体协作多个智能体之间如何通信、如何避免互相循环调用框架对比对比常用智能体平台、低代码平台的工作流搭建方式性能优化智能体响应延迟、调用次数、模型成本控制9. 工程化最佳实践从 Demo 到生产当你不满足于跑通 demo而是要把智能体接入真实业务时下面这些工程化实践会很有帮助。9.1 权限最小化HumanLayer 的核心价值之一就是让“最小权限”原则在 AI 场景落地。每个工具函数只暴露必要参数不要把所有系统能力全部暴露给大模型审批人按角色分级不同角色能批准的操作不同高权限操作需要多人审批所有审批记录都要持久化存储方便审计。9.2 超时与降级处理智能体在调用 HumanLayer 时如果人类长时间不响应应该设置超时机制try: approval hl.approve_function_call( call_desccall_desc, fn_namefunction_name, fn_argsfunction_args, timeout60, # 60 秒无响应则超时 ) except TimeoutError: # 超时默认拒绝或进入异步审批队列 print(审批超时已拒绝执行。) return 审批超时操作未完成。在生产环境中超时后可以把任务转入异步审批队列让审批人在方便的时候处理而不是直接丢弃。9.3 日志与审计所有智能体工具调用都应该记录完整的日志请求时间用户会话 ID大模型的完整思考/调用链工具名称与参数HumanLayer 审批 ID审批人审批结果实际执行结果。这样一旦出现问题可以完整还原当时发生了什么。9.4 与现有智能体框架结合HumanLayer 并不排斥其他智能体框架。你可以把 HumanLayer 作为工具调用前的统一拦截层接入在自研 agent、Dify 工作流、Coze 智能体或其他低代码平台中。常见的架构模式是用户输入 ↓ 智能体框架负责规划、记忆、上下文管理 ↓ 工具调用前统一走 HumanLayer 审批网关 ↓ 审批通过 → 调用真实工具/API 审批拒绝 → 返回拒绝消息给智能体这种模式的好处是智能体负责聪明HumanLayer 负责安全二者各司其职。9.5 从低代码平台到编码开发如果你是低代码平台用户比如 Dify、Coze 等可能已经发现工作流搭建虽快但一旦涉及复杂权限控制、自定义审批流、私有化部署低代码平台往往难以满足需求。这种情况下转向代码化开发是必然选择。HumanLayer 这类 SDK 的优势在于可以嵌入任意 Python/Node.js 项目不依赖特定平台支持本地调试权限逻辑完全掌握在自己手里。10. 总结与下一步学习路线回到本文开头的问题为什么“HumanLayer 智能体构建分享”能获得 20 万观看因为开发者真正关心的不是“AI 能做什么”而是“AI 做的错事怎么办”。HumanLayer 用一层轻量级的人工审批机制正好切中了这个需求。本文从概念到实战带大家走完了完整流程理解了 HumanLayer 是什么以及它解决的智能体安全边界问题完成了环境准备和 SDK 安装掌握了approve_function_call的核心用法跑通了一个带人工确认的邮件发送智能体了解了从本地模式到 Slack/Telegram 审批的扩展方式整理了智能体开发中的常见问题和工程化实践。如果你打算继续深入智能体开发下一步可以优先学习Function Calling 原理深入了解大模型如何决定调用工具这是智能体开发的地基。多智能体协作当多个智能体互相调用时如何设计审批链和数据流。智能体工作流测试验证怎么对智能体做系统化的测试而不只是跑一两个 happy path。Agent 框架对比了解不同智能体框架的适用场景选择适合自己业务的技术栈。生产环境安全提示注入防护、敏感信息脱敏、工具调用审计。最后提醒一句在真实系统中引入智能体之前一定要在测试环境完整验证所有工具调用路径并保证所有重要操作都有日志留痕。智能体可以越用越聪明但前提是先把它关进一个安全、可控的围栏里。如果本文对你有帮助可以收藏备用。你近期在智能体开发中遇到过最头疼的问题是什么欢迎在评论区分享我们可以在后续文章中继续拆解。