# AI Agent 接工具前，先把权限分层和人工确认做清楚

很多团队做 AI Agent 试点时，最容易兴奋的部分是“模型终于能调用工具了”。

它能查数据、改工单、发通知、写 CRM、触发工作流，看起来离真正的数字员工很近。但一进入真实业务，风险也会一起放大：一次误判可能改错客户状态，一次重复执行可能创建多条订单，一次权限配置错误可能把只读查询变成写入动作。

所以 Agent 上线前，不应该先问“能不能多接几个工具”，而应该先问：每个工具到底允许 Agent 做到哪一步？

生产环境里，工具权限至少要分层。

## 1. 先把工具分成四类权限

不要让所有工具都用同一套调用权限。一个比较实用的分层方式是：

```yaml
tool_permission_tiers:
  read_only:
    examples:
      - search_docs
      - query_order_status
      - get_device_metrics
    risk: low
    approval: none

  draft_only:
    examples:
      - draft_customer_reply
      - generate_refund_plan
      - create_change_summary
    risk: medium
    approval: human_before_send

  reversible_write:
    examples:
      - add_internal_note
      - update_ticket_label
      - create_task
    risk: medium
    approval: conditional
    rollback_required: true

  high_risk_action:
    examples:
      - issue_refund
      - change_device_config
      - modify_contract_terms
      - send_external_message
    risk: high
    approval: explicit_human_approval
```

这个表的价值不是写得漂亮，而是让工程团队、业务团队和运营人员对“Agent 可以做什么”有同一张边界图。

如果没有这张图，后续讨论会变成模糊的安全感：大家都觉得“应该没问题”，但没有人能说清楚系统在哪些动作上会停下来。

## 2. 不要把“生成建议”和“执行动作”混在一起

Agent 的很多能力可以拆成两段：

- 先生成建议；
- 再执行动作。

比如退款场景里，Agent 可以读取订单、售后规则、客户历史，生成一个退款建议。但“真正发起退款”应该是另一类工具权限，不应该和建议生成绑在一起。

可以把工具调用设计成这样：

```typescript
type AgentAction =
  | {
      kind: "draft";
      tool: "refund_plan";
      requiresApproval: false;
    }
  | {
      kind: "execute";
      tool: "issue_refund";
      requiresApproval: true;
      approvalReason: "external_financial_action";
    };
```

这样做有两个好处。

第一，模型可以继续承担信息整理、证据汇总和方案草拟的工作，不会因为高风险动作被限制而完全失去价值。

第二，系统可以把高风险动作显式拦下来，把“请人确认”变成产品流程的一部分，而不是靠运营人员事后发现。

## 3. 人工确认要确认证据，不只是点一个按钮

很多系统的人工确认做得太薄：弹一个确认框，按钮上写“确定执行”。这不够。

真正有用的确认页至少要给人看四类信息：

- Agent 准备执行什么动作；
- 它依据了哪些数据和规则；
- 如果执行失败或执行错了，怎么撤回；
- 这次动作的风险等级和预算影响。

一个最小确认对象可以这样设计：

```json
{
  "action_id": "act_20260623_001",
  "workflow": "support_refund_review",
  "proposed_action": "issue_refund",
  "amount": 128.5,
  "evidence": [
    "order_status: delivered",
    "policy_match: seven_day_return",
    "customer_history: no_abuse_signal"
  ],
  "risk_level": "high",
  "rollback_plan": "refund can be reversed by finance within same settlement day",
  "approval_required_from": "support_lead"
}
```

这里的重点是：确认不是让人替模型背锅，而是让人有足够信息判断这件事该不该执行。

## 4. 写入动作必须有幂等和回滚

Agent 接工具后，重复执行是常见事故来源。

用户刷新页面、队列重试、模型重新规划、网络超时后的 fallback，都可能让同一个动作被执行两次。如果工具没有幂等键，系统很容易创建重复任务、重复发送消息、重复扣减额度。

写入类工具至少要带三个字段：

```json
{
  "idempotency_key": "tenant42:ticket889:update_label:20260623",
  "requested_by": "agent_run_abc123",
  "rollback_ref": "ticket_label_previous_state"
}
```

高风险写入还要在审计日志里记录执行前状态和执行后状态。

```json
{
  "tool": "update_ticket_label",
  "before": { "label": "pending" },
  "after": { "label": "refund_review" },
  "idempotency_key": "tenant42:ticket889:update_label:20260623",
  "approved_by": "support_lead_17",
  "agent_run_id": "run_abc123"
}
```

没有这些字段，后续出了问题只能靠日志猜；有这些字段，至少能知道问题发生在哪一步、能不能撤、谁批准了。

## 5. 权限策略要跟模型路由一起看

权限分层不是孤立模块。它应该和模型路由、风险等级、证据质量一起工作。

比如：

- 只读查询：可以走低成本模型或规则；
- 内部草稿：可以走中等模型，但必须保留引用证据；
- 可撤销写入：需要风险检查和幂等键；
- 外部发送、资金、合同、设备控制：需要强模型审查加人工确认；
- 证据不足：不升级模型继续猜，直接停止或转人工。

这类策略最好写成配置，而不是散落在 prompt 里。

```yaml
route_policy:
  external_customer_message:
    min_model_tier: strong
    required_evidence:
      - source_document
      - customer_context
      - policy_match
    permission_tier: high_risk_action
    human_approval: required
    audit_log: append_only
```

Prompt 可以描述行为，但生产系统的边界应该由配置和代码兜住。

## 6. 上线前的权限验收清单

我通常会用这 8 项检查 Agent 的工具权限：

| 检查项 | 通过标准 |
|---|---|
| 工具分层 | 每个工具标明只读、草稿、可撤销写入或高风险动作 |
| 审批规则 | 高风险动作必须显式人工确认 |
| 证据展示 | 确认页能看到来源、规则和上下文 |
| 幂等控制 | 写入工具有 idempotency key |
| 回滚设计 | 可撤销动作记录前后状态和回滚引用 |
| 权限最小化 | Agent 默认不能拿到全量后台权限 |
| 审计日志 | 工具调用、审批人、输入输出摘要可追溯 |
| 异常处理 | 证据不足、审批拒绝、工具失败都有停止路径 |

这些检查不一定一开始都做成复杂平台，但不能靠口头约定。

## 一句话总结

生产级 AI Agent 接工具，关键不是“能调多少工具”，而是“每个工具在哪些条件下能被调用、什么时候必须停、谁来确认、出了错怎么回滚”。

AgentKick 做 AI Agent Production-Readiness Review 时，会把工具权限、人工确认、审计日志、模型路由和可观测性放在同一组检查里看。因为真正的生产风险，通常不是模型不知道怎么回答，而是系统让它在不该执行的时候执行了。