AI Agent 工具权限分级实战：读、写、发布三类操作怎么管

AI Agent 一旦能调用工具，就从“只会回答问题”变成了“可以影响系统状态”。查询订单、修改资料、发送通知、发布内容，这些动作的风险完全不同。如果所有工具都用同一套放行规则，迟早会在权限边界上出问题。

摘要

本文给出一套轻量的工具权限分级方案：把工具按读、写、发布三类拆开管理。读操作可以自动放行；写操作需要确认关键参数；发布、删除、转账这类高风险操作必须二次确认，并写入审计日志。示例代码用 Python 描述路由逻辑，实际可以落到任意后端服务里。

适合人群

适合正在做 AI Agent、智能客服、数据助手、自动化运营后台的开发者。你不需要先上复杂平台，只要已有“模型输出工具名和参数”的基础流程，就可以按本文逐步加上权限层。

目录

• 为什么工具要分级
• 三类工具权限怎么划分
• 运行时守卫流程
• 一个简单的路由示例
• 常见坑和上线检查

为什么工具要分级

很多团队第一次接入 Agent 工具时，会把重点放在“模型能不能正确选工具”。但上线后真正麻烦的往往是另一个问题：模型选对了工具，但调用时机、参数范围、影响对象没有被管住。

例如下面三类动作，风险明显不同：

• 读取数据：查询订单状态、搜索知识库、读取配置。
• 修改数据：更新用户备注、调整工单状态、写入标签。
• 对外发布：发送邮件、发布文章、删除资料、触发付款。

如果把它们都当成普通工具，Agent 的一次错误判断就可能从“答错一句话”升级成“写错数据或发错内容”。

三类工具权限怎么划分

更稳的做法是把工具权限变成显式配置，而不是散落在各个工具函数里。下面这张图展示了一个简单分层：读操作走绿色通道，写操作进入确认，发布类操作走更严格确认，所有结果都写日志。

可以先从一张配置表开始：

TOOLS = {
    "search_order": {
        "level": "read",
        "desc": "查询订单状态",
        "required": ["order_id"],
    },
    "update_ticket": {
        "level": "write",
        "desc": "更新工单备注",
        "required": ["ticket_id", "note"],
    },
    "publish_article": {
        "level": "publish",
        "desc": "发布文章到线上",
        "required": ["title", "content_id"],
    },
}

这张表的作用不是替代权限系统，而是让 Agent 层先知道每个工具的风险级别。后面再叠加用户身份、业务状态和人工确认，就会清晰很多。

运行时守卫流程

工具真正被调用前，建议至少经过五步：参数结构检查、风险判断、人工确认、工具调用、审计记录。不要让模型输出一段工具参数后直接进入业务函数。

每一步的目标很明确：

• SCHEMA：检查工具名是否存在，必填参数是否齐全，类型是否合理。
• RISK：根据工具级别、用户身份、目标对象判断风险。
• APPROVE：对写操作和发布操作给出人工确认界面。
• CALL：只在通过前置检查后调用真实业务工具。
• LOG：记录请求、参数摘要、确认人、结果和时间。

一个简单的路由示例

下面代码演示一个最小可用的守卫层。它不会直接信任模型给出的工具调用，而是先拿配置表做检查，再决定是否放行。

from dataclasses import dataclass
from typing import Any


@dataclass
class ToolRequest:
    user_id: str
    tool_name: str
    args: dict[str, Any]


def check_schema(req: ToolRequest) -> list[str]:
    tool = TOOLS.get(req.tool_name)
    if not tool:
        return ["unknown tool"]

    missing = [
        name for name in tool["required"]
        if name not in req.args or req.args[name] in (None, "")
    ]
    return [f"missing {name}" for name in missing]


def need_approval(req: ToolRequest) -> bool:
    level = TOOLS[req.tool_name]["level"]
    return level in {"write", "publish"}


def need_double_check(req: ToolRequest) -> bool:
    return TOOLS[req.tool_name]["level"] == "publish"

然后在路由入口里统一处理：

def route_tool(req: ToolRequest) -> dict[str, Any]:
    errors = check_schema(req)
    if errors:
        return {
            "status": "rejected",
            "reason": "; ".join(errors),
        }

    if need_double_check(req):
        return {
            "status": "waiting_double_approval",
            "tool": req.tool_name,
            "args_preview": req.args,
        }

    if need_approval(req):
        return {
            "status": "waiting_approval",
            "tool": req.tool_name,
            "args_preview": req.args,
        }

    return {
        "status": "allowed",
        "tool": req.tool_name,
        "args": req.args,
    }

实际系统里，waiting_approval 可以进入后台确认页，waiting_double_approval 可以要求更高权限账号确认。确认通过后，再由后端服务调用真实工具，并把结果写入日志。

审计日志要记录什么

很多 Agent 问题不是当场发现的，而是用户反馈后才回头排查。所以日志不能只记“成功或失败”，至少要包含：

{
  "user_id": "u_1001",
  "tool_name": "update_ticket",
  "level": "write",
  "args_digest": "ticket_id=7788,note_len=24",
  "approval": "approved",
  "result": "ok",
  "created_at": "2026-06-13T15:30:00+08:00"
}

注意不要把完整敏感内容直接写进日志。更推荐记录摘要、长度、对象 ID、确认状态和结果码，既能追踪，又能减少隐私泄露风险。

常见坑和上线检查

• 只校验工具名：工具名对了，参数也可能越权，必须检查对象范围和必填字段。
• 把确认交给模型：确认应该来自用户或后台人员，不应该让模型自己判断自己是否安全。
• 发布类操作没有二次确认：对外发送、删除、付款、上线发布都建议更严格。
• 日志里写入明文敏感信息：用摘要和对象 ID 代替完整内容。
• 没有失败兜底：被拒绝时要给出可读原因，而不是静默失败。

总结

AI Agent 工具治理的核心不是把工具接得越多越好，而是让每个工具的风险级别可见、可控、可追踪。先把 READ、WRITE、PUBLISH 三类操作分开，再加上 SCHEMA、RISK、APPROVE、CALL、LOG 这条守卫流程，就能在不牺牲太多效率的前提下，把线上风险压低很多。