Agent人工任务看板：从状态机到人机协作的落地指南

Human task board for my agents直译过来是“给我的智能体们准备的人工任务看板”。它不是普通团队协作用的 Kanban而是让 AI Agent 在执行自动任务时能把当前状态、输入输出、决策点同步给人类并允许人类在关键节点介入的一块控制面板。很多同学做 Agent 自动化时会把大部分精力放在模型调用、工具调用和流程编排上。等 Agent 连续跑错几次才发现真正缺的不是 Agent 能力而是一个能让人看到任务进展、补充上下文、做审批、按重跑的入口。这篇文章就按实际落地顺序拆一遍重点讲任务模型、状态机、前后端对接、批量任务和常见坑点。适合正在做 Agent 平台、自动化工作流、企业内部 AI 任务系统的人参考。1. 先想清楚这是给 Agent 用的“人工介入舱”不是普通看板1.1 Agent 全自动跑完之后最怕什么Agent 自动化表面上是把任务交给模型去执行但在真实业务里Agent 经常遇到几种情况跑着跑着方向偏了、缺少某个关键资料、需要确认一个外部操作、工具账号没有权限、生成结果要人工审核才能发布。这些问题有一个共同点单靠 Agent 自己处理不了必须有人介入。可是问题在于Agent 执行过程中人类看不到它在干什么也不知道该在哪里插手。如果只靠日志普通业务人员看不懂。如果只靠数据库你只能看到一条任务记录看不到业务上下文。Human task board 要解决的就是把“日志级的执行信息”转成“任务级的人工操作信息”让人知道三件事这个任务现在卡在哪、为什么卡、我需要做什么。1.2 看板里需要出现哪些人机协作点不是所有任务都需要人工介入。设计看板之前先把协作点列清楚。我一般会按这五类来梳理前置信息缺失任务创建时输入不完整Agent 需要用户补充资料。高风险动作审批Agent 准备调用外部接口、发送消息、创建订单、修改配置需要先确认。中间结果审核Agent 生成了一版初稿需要人确认后再继续执行后续步骤。异常决策任务执行失败、成本超预算、重复次数过多需要人决定是继续还是放弃。最终验收整个任务执行完毕需要人对最终输出做验收归档。这五类协作点就是 Human task board 的核心。其他信息比如运行日志、Token 消耗、调用耗时属于辅助信息可以用来解释“为什么需要人工介入”但不能替代人工介入本身。注意不要一开始就把所有过程都设计成人工节点。人工介入越多Agent 自动化的价值越低。先把“必须人做”的点提炼出来剩下的全部自动化。2. 任务模型的字段和状态机决定后面所有功能2.1 一个任务对象最少要有这些字段看板不是给 Agent 做日志展示而是给人做任务管理。任务对象必须包含业务信息、执行状态和人工操作信息。基于我自己的实践一个最小可用任务对象应该包含这些字段task_id任务唯一编号建议用分布式 ID不要用自增整数。title 和 description给人看的任务说明让审批者不用翻日志就知道要做什么。type 和 source任务类型和来源方便筛选和统计。batch_id批次编号批量任务时把同一批任务聚合在一起。status当前状态必须和 Agent 执行状态严格对应。requester 和 assignee_agent发起人、执行 Agent用于权限和定位。input_data 和 output_data任务输入输出注意敏感字段要脱敏。current_step当前执行步骤比日志更精简。latest_log最近一条日志摘要。human_action_required当前需要人做什么这是看板里最重要的字段。attempts重试次数避免无限重试。created_at、updated_at、due_at时间信息用于排序和超时提醒。字段不需要一次设计得特别复杂但要保证“人看到这个任务时能直接判断下一步要干什么”。2.2 状态机必须预留“等待人工”节点任务状态是看板的骨架。如果状态机设计得不对后续所有筛选、通知、统计都会乱。我常用的状态集合如下pending已创建等待 Agent 调度。runningAgent 正在执行。awaiting_human_input等待人工补充信息。needs_reviewAgent 已完成中间结果或最终结果等待审批。approved人工审核通过。rejected人工驳回。completed任务完成。failed任务失败。cancelled人工取消。这里最容易忽略的是“等待人工”类状态不要只做一个。补充输入和审批通过虽然都涉及人但触发条件不同。补充输入代表信息不全审批通过代表执行结果需要确认。如果混在一起后面做自动通知时很难判断该通知谁。状态流转可以简单约定成pending 进入 runningrunning 可能变成 awaiting_human_input 或 needs_review人工操作后回到 running、进入 failed 或 cancelled最终到 completed。2.3 任务来源、去重和批量归属任务从哪里来直接决定看板的设计。常见来源有用户手动创建、上游系统推送、定时任务生成、另一个 Agent 编排产生。手动创建最简单看板页面加一个“新建任务”按钮就行。上游系统推送要考虑幂等避免重复入队。定时任务生成要考虑 batch_id因为同一批可能生成几十上百个任务。Agent 编排产生还要记录 parent_task_id方便追溯这个任务是从哪个父任务拆出来的。去重逻辑我一般放在任务创建层不放在看板层。规则可以简单一点同一来源、同一业务主键、同一时间段内只允许一条 pending 或 running 任务。这样能避免很多重复审批。3. Agent 执行器、后端 API 和看板的对接链路3.1 Agent 侧上报状态、心跳、日志、调用链看板的数据来源是 Agent 执行器。执行器不能只在最后上报一个完成结果而是要在整个执行过程中持续上报。我的基本要求是Agent 每次发生状态变化就调用一次后端接口同步状态。比如启动任务时上报 running遇到需要人确认时上报 awaiting_human_input 或 needs_review完成时上报 completed。这些状态上报里要带上三样东西当前步骤名方便人知道卡在哪。关键输入输出摘要方便人做判断。必要的日志或调用链 ID方便开发排查。如果 Agent 运行在外部进程里还需要心跳机制。心跳不一定要秒级30 秒到 1 分钟一次都可以。如果连续几次心跳丢失看板就要把任务标记为“执行器失联”而不是一直显示 running。这个坑我在早期遇到过Agent 进程挂掉后任务永远卡在运行中。3.2 后端接口查询、人工回填、审批、重跑后端接口不用复杂但要对齐状态机。我一般会提供这些接口风格大致如下GET /api/v1/tasks GET /api/v1/tasks/{task_id} POST /api/v1/tasks/{task_id}/approve POST /api/v1/tasks/{task_id}/reject POST /api/v1/tasks/{task_id}/input POST /api/v1/tasks/{task_id}/retry POST /api/v1/tasks/{task_id}/cancel审批接口的入参不要只传 approve/reject还要允许审批者填写审批意见。因为 Agent 被驳回后需要知道下一步是修改输出、补充材料还是干脆放弃。人工回填接口要处理一种常见场景Agent 向人提问人补充了一段资料。这段资料不能只是展示还要成为后续执行的正式输入所以建议单独保存不要直接拼接进原始任务描述里。重跑接口要区分“从当前步骤重试”和“整个任务重新执行”。前者只重试失败的那一步后者会把任务状态重置为 pending。从我的经验看先支持整任务重跑等积累几次真实重跑需求后再做步骤级重试。3.3 列表刷新轮询和长连接的取舍任务看板需要实时性但实时性的标准要按场景定。如果用户主要在看板里处理审批刷新太慢会影响效率。如果任务列表就是一个辅助页面那 10 秒轮询都够。我建议第一版先用轮询。原因很简单实现简单排查方便对服务器压力也可控。等确实出现“任务状态变了看板要立刻弹出来”的需求再引入 WebSocket 或 SSE。WebSocket 适合双向交互SSE 适合服务端单向推送。对于任务看板这种场景SSE 通常更合适因为主要变化来自服务端向客户端推送状态更新。不管用哪种方案都要考虑连接断开和消息丢失。前端要在重新连接后主动拉一次全量列表保证状态一致。3.4 权限与敏感信息隔离很多人做个人项目时忽略权限但现在只要是多人可见的系统就应该把权限做进去哪怕是简单的角色区分。基础规则可以是普通用户只能看到自己创建或自己被指派的待办任务管理员可以看到全量任务Agent 执行器有独立的服务账号只能读写自己的任务不能访问其他 Agent 的任务。敏感信息方面最容易出错的是把 API Key、Token、密码、完整日志直接回传到前端。Agent 调用工具时可能把密钥写进日志如果原样显示就变成越权信息泄露了。对外展示前要做脱敏处理也就是只保留前面几位或明确标注“已隐藏”。4. 前端看板别再按“进度条”设计4.1 列表视图筛选条件比状态列更重要看板首页如果只是把任务按状态放在几列里其实并不好用。原因是 Agent 任务状态变化快用户更关心的是“哪些任务需要我处理”而不是“现在的全部状态分布”。我建议第一屏直接展示“待我处理”的列表也就是当前人需要介入的所有任务。顶部提供这几个筛选条件状态等待补充输入、待审批、已完成、失败、已取消。来源 Agent某个 Agent 名或服务名。批次batch_id。时间范围创建时间、更新时间。任务类型比如审批类、生成类、调度类。状态列可以有但不是主视图。主视图要让人一进来就看到自己的待办。每个任务卡片上不用塞太多信息。标题、任务来源、当前卡点、等待时间、优先级这几个字段就够了。具体输入输出留给详情页。4.2 详情面板给人工决策需要的信息用户点进一个任务后详情面板需要展示完整上下文。我的经验是按这个顺序组织任务基本信息和当前状态。当前需要人做什么简单一句话比如“审批是否发送邮件给用户”。任务输入数据包括用户原本提供的上下文和 Agent 已经收集到的信息。最近一轮执行过程展示到步骤级别就行不需要完整调试日志。已完成的历史动作比如 Agent 已经调用了哪些工具、生成了什么中间结果。操作按钮根据状态动态渲染。很多看板失败在信息过载。用户打开详情页看到的是几十行原始 JSON但没有一条在回答“我现在要干什么”。所以我建议在详情页最顶部放一个醒目的“行动提示”区块写清楚本次任务需要人决定什么。4.3 人工操作审批、回填、指派、跳过、重跑操作按钮要按状态动态出现不能让用户在已完成任务上还能点审批。常见操作包括补充输入打开表单填写额外信息提交后 Agent 继续执行。批准对中间结果或最终结果表示认可。驳回填写驳回原因可以选择让 Agent 修改后重新提交。跳过本次不做处理标记为跳过任务继续或挂起。重跑失败之后重新执行。取消彻底终止任务。每个操作都要二次确认。尤其重跑和取消一个会重复消耗资源一个会终止后续流程不能手滑。4.4 通知触达把“等人”变成显式状态任务看板是被动工具用户不会一直盯着页面。真正让人及时介入的是通知。状态变成 awaiting_human_input 或 needs_review 时应该通过站内信、邮件或 IM 机器人通知相关人。通知内容必须包含任务标题、卡点说明、任务链接并且只通知有权限处理该任务的人。这里要避免一个错误自动审批。有些场景看起来可以把 Agent 动作包装成“自动批准”但一旦外发消息、创建订单、删除资源自动审批就是隐患。通知可以自动发审批动作必须留给人。5. 从单条任务到批量任务关键差异在队列和重试5.1 先按最小闭环跑一遍任何功能先做最小闭环。Human task board 的最小闭环可以这样定义创建一条任务写入数据库。Agent 拉取任务并开始执行。Agent 执行到需要审批的节点上报 needs_review。用户在看板看到待办点开详情批准或驳回。Agent 收到人工结果继续执行或终止。任务最终进入 completed 或 failed。这个闭环跑通之后再看板才算真正可用。不要一开始就做多 Agent、多批次、复杂权限很容易被细节淹没。5.2 批量任务看板和单任务看板的差异批量任务看起来只是多条任务同时跑实际上有两个变化一是任务数量变多二是失败类型变多。数量变多后看板不能按单个任务展示需要先把同一批任务聚合起来。聚合维度可以是 batch_id。进入批次详情后再按任务列表展示每一条的执行状态。批次页面上要显示本批总量、已完成量、等待人工量、失败量、失败率。人工处理上也应该有批量能力比如多选几条任务批量批准或者批量驳回。但批量审批要小心。如果一批任务代表几十个不同用户人工不可能逐条看批量审批会导致质量问题。我一般只开放批量操作给“低风险、标准化”的任务类型高风险任务必须逐条处理。5.3 失败重试、超时和人工兜底批量任务里失败重试是必然要处理的。我的建议是先把失败分成两类。第一类是可重试失败比如网络超时、依赖服务临时不可用、文件暂时被占用。这类可以让 Agent 自动重试重试次数有上限比如 2 到 3 次。第二次重试前适当延迟避免打爆下游服务。第二类是不可重试失败比如输入格式错误、权限被拒绝、规则冲突、人工驳回。这类不能自动重试只能进入 failed 或 needs_review等人来判断。重试次数要记录在 attempts 字段里。每次重试生成新的 attempt 编号对应不同的日志和输出避免重试后旧日志覆盖新日志导致排查时看不到真实失败原因。超时也要单独设计。比如一个任务等待人工审批超过 24 小时系统应该自动提醒审批人而不是无限挂起。提醒几次后仍然没有人处理按预设策略自动升级给管理员。5.4 审计日志和状态不一致排查批量任务跑起来后审计日志非常重要。每次状态变更、每次人工操作、每次重试都应该记录一条不可变日志。审计日志至少包含这些字段task_id、操作人、操作类型、操作前状态、操作后状态、操作时间、备注。这不仅是合规要求也是排查状态不一致的依据。如果数据库显示任务已经审批通过但 Agent 还在运行就要看审批日志和 Agent 回调日志确认是回调丢失还是状态更新顺序错了。我遇到过一种典型情况人工审批成功后回调 Agent 的接口超时Agent 没有继续执行但看板已经显示 approved。最后靠审计日志才发现审批成功和 Agent 继续执行是两个独立动作中间缺了重试补偿。6. 最容易踩的坑和我的排查顺序6.1 任务状态不一致先看时间戳还是先看日志状态不一致是 Human task board 里最常遇到的问题。现象通常是看板显示 waitingAgent 已经在跑或者看板显示 completedAgent 还在执行。排查顺序我建议先从最后一次状态变更时间开始确认是哪一次状态更新丢失了。然后看 Agent 执行器日志确认它是否真的发起过状态上报。最后看后端接口日志确认请求是否到达、是否有异常。不要先把问题归到数据库上。大部分状态不一致源头是执行器上报失败、回调超时、接口幂等处理不到位。6.2 人工审批一直卡住超时、通知、锁冲突人工审批卡住有两种常见情形。一种是用户根本没收到通知。这种情况要检查通知渠道、通知对象和权限配置尤其是“待办任务是否分配给了正确的人”。如果任务指派人错了审批人永远看不到。另一种是用户点了审批但页面一直转圈或者审批后又被旧状态覆盖。这种情况要检查并发控制。多人同时处理同一个任务时必须用乐观锁或任务锁更新状态前先比对当前版本号。否则两个审批人同时操作后提交的人可能把前一个人的操作覆盖掉。6.3 Agent 跑偏但看板拦不住缺少干预点看板本身不能阻止 Agent 跑偏。它只是把人工介入点暴露出来而介入点放在哪里取决于任务流程设计。如果 Agent 经常先发消息后审批那说明审批点放晚了。如果 Agent 生成结果后直接入库用户只能在最终输出中发现问题说明缺少中间结果审核。更稳妥的做法是在每次 Agent 执行“外部副作用”动作前强制插入一个审核节点。比如调用支付、发送消息、写入生产库、删除文件这些动作都要在动作前暂停审批。动作完成后的日志只作为审计记录不承担纠偏职责因为已经执行完毕看板只能记录问题不能挽回损失。6.4 安全边界命令注入、越权访问和数据脱敏设计任务看板时安全边界容易被忽略尤其在个人项目里。第一个风险是命令注入。如果 Agent 把用户输入或人工回填内容直接拼接进系统命令攻击者可能通过任务描述让 Agent 执行非预期命令。正确的做法是所有需要执行命令的参数走参数化方式不要直接拼字符串外部输入不能作为 shell 指令的一部分。第二个风险是越权访问。任务详情接口必须校验当前用户是否有权限查看该任务。不能因为前端隐藏了“查看”按钮后端就省略鉴权。直接请求接口 URL 仍然可以拿到数据。第三个风险是数据脱敏。Agent 处理的数据可能包含手机号、身份证、内部 Token 等敏感信息。看板列表、详情、日志里要统一脱敏不能只在前端做遮罩接口层就要处理。7. 落地时我建议按什么顺序推进7.1 先做一条任务的闭环第一优先级永远是创建一条任务、由一个 Agent 执行、在一个节点等待人工审批、人在看板里处理、任务继续或终止。这个闭环里你会遇到状态同步、接口设计、前端展示、日志排查等所有核心问题但范围还比较小来得及调整。做到这一步不要急着加 WebSocket、多 Agent、复杂权限、批量审批。先把数据库里的状态和看板上的展示完全对齐再考虑扩展。7.2 再评估是否需要批量、权限、通知闭环跑通后我会建议观察一段时间的真实使用数据。重点看两个指标哪个节点人工介入频率最高哪个节点 Agent 失败率最高。介入频率高的节点应该重点优化交互让人处理得更快。失败率高的节点要看是 Agent 能力问题还是输入数据质量问题而不是简单加几次重试。批量功能、通知系统、审计日志按需引入。不要为了做而做。7.3 个人项目和企业项目的差异个人项目里Human task board 可以做成一个很小的 Web 应用。数据库用 SQLite 或 PostgreSQL前端用简单的表格页面Agent 通过 HTTP 接口上报状态。优先级是快速看到效果。企业内部使用时要提前考虑 SSO 登录、角色权限、审计合规、告警监控和高可用。任务量上来之后还要考虑数据库读写的压力、任务队列是否会阻塞、Agent 执行器是否需要独立部署。这时候 Human task board 就不再是一个小看板而是一个任务管理平台。最后留一个我自己的验收标准如果一个任务从创建到完成中间的每一次失败、每一次人工操作都能从看板里查到是谁、在哪一步、卡了什么这套看板就基本合格了。如果你正在做 Agent 自动化可以先从任务模型和状态机入手把人工介入点设计清楚再慢慢补前面的界面和后面的批量能力。