14-多工具任务Agent实战任务书
核对日期：2026-05-18
官方资料：Agents https://docs.langchain.com/oss/javascript/langchain/agents；Tools https://docs.langchain.com/oss/javascript/langchain/tools；Human-in-the-loop https://docs.langchain.com/oss/javascript/langchain/human-in-the-loop；Middleware https://docs.langchain.com/oss/javascript/langchain/middleware。
目标
把 src/projects/multi-tool-task-agent.ts 扩展成可控的多工具 Agent。它要能根据用户角色和任务风险动态暴露工具，对高风险操作做人类审批，对瞬时失败做有限重试，并记录审计日志。
机制
TypeScript 任务拆解
| 任务 | 修改位置 | 产物 | 验收方式 |
|---|---|---|---|
| 工具风险分级 | tool metadata | risk: low/medium/high | 高风险工具默认隐藏 |
| 动态暴露 | toolsForRole | 按角色和意图返回工具 | employee 不见 manager 工具 |
| HITL 审批 | send_external_report | approval token + reason | 无审批 pending |
| 重试策略 | runWithOneRetry | transient only retry | permanent error 不重试 |
| 审计日志 | context.trace | actor/action/ok/detail | 每个工具调用都有记录 |
工具设计模板
interface ToolPolicy {
name: string;
risk: "low" | "medium" | "high";
requiredPermission?: string;
requiresApproval: boolean;
}
不要让模型自己决定 risk。risk 是业务策略，应来自配置或后端 policy。
审批状态
高风险工具至少记录：
| 字段 | 用途 |
|---|---|
| approvalId | 审批单 ID |
| approverId | 审批人 |
| reason | 为什么需要执行 |
| expiresAt | 防止审批长期复用 |
| toolInputHash | 防止审批后改参数 |
Python 差异
Python 侧常用 LangGraph interrupt/resume 处理 HITL；TypeScript 侧也要把审批当状态恢复问题，而不是 UI 弹窗。语言不同，审批状态和审计字段必须一致。
Eval 数据集
| 用例 | 输入 | 预期 |
|---|---|---|
| 普通员工建工单 | employee + 工单请求 | 不调用 create_ticket |
| manager 建工单 | manager + 工单请求 | 调用 create_ticket |
| 外发无审批 | manager + 外部报告 | pending approval |
| 外发有审批 | approvals 包含工具名 | 成功执行 |
| transient 失败 | calendar 第一次失败 | 只重试一次后成功 |
工程边界
- Agent 不能直接拿全量工具列表。
- 写工具必须幂等。
- 审批必须绑定工具输入，避免审批 A 参数后执行 B 参数。
- 审计日志不能只存在前端。
常见反模式
| 反模式 | 后果 |
|---|---|
| “模型判断是否危险” | 风险边界不可控 |
| 所有工具都暴露给 Agent | 误调用概率上升 |
| 审批不绑定输入 | 参数被篡改后仍能执行 |
| 工具失败无限重试 | 造成重复副作用或成本爆炸 |
练习任务
- 给每个工具增加
riskmetadata。 - 让
send_external_report检查toolInputHash。 - 增加一个 permanent error 工具，确认不会重试。