跳到主要内容

**AI Agent 和 MCP 工具的授权**

AI Agent 在运行时决定调用哪些工具以及使用哪些参数。模型可能会出错,也可能被它在工单、网页或文档中读取到的文本诱导做出错误行为。授权必须位于模型之外,即在工具调用执行的那个点,并回答两个问题:

  1. 这个 Agent 可以用这些参数调用这个工具吗? 支持助手可以读取工单并发放小额退款,但绝不应运行 shell 命令。
  2. 它代表的用户可以这样做吗? 代表某人执行的 Agent 不得获得比该人更多的访问权限。

Casbin 以处理用户的相同方式,用一个模型和一个策略来处理这两个问题。本页首先展示规则,然后将它们接入一个简单的工具调用循环和一个 MCP 服务器。代码为 Python。该模型和策略也适用于其他 Casbin 实现;在 Go 中,将参数作为结构体传递,并在条件中使用其导出字段名,例如 r.args.Amount。

1. 安装​

pip install pycasbin

2. 编写模型​

将其保存为 model.conf:

[request_definition]
r = sub, tool, args

[policy_definition]
p = sub, tool, cond, eft

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow)) && !some(where (p.eft == deny))

[matchers]
m = g(r.sub, p.sub) && globMatch(r.tool, p.tool) && (p.cond == '' || eval(p.cond))
  • r = sub, tool, args:调用者(Agent 或用户)、工具名称以及工具的参数对象。
  • p = sub, tool, cond, eft:每条规则指定一个角色、一个工具模式、一个可选的参数条件,以及是允许还是拒绝。
  • g = _, _:Agent 和用户具有角色,且角色可以从其他角色继承。
  • globMatch 匹配带有通配符的工具名称,例如 tickets.* 或 *.delete。
  • 策略效果规定,如果某条规则允许调用且没有规则拒绝它,则允许该调用,因此拒绝规则始终优先。

3. 编写策略​

将其保存为 policy.csv:

p, support-agent, tickets.*, , allow
p, support-agent, orders.read, , allow
p, support-agent, orders.refund, r.args.amount <= 100, allow
p, any-agent, shell.*, , deny
p, any-agent, *.delete, , deny

p, support-staff, tickets.*, , allow
p, support-staff, orders.*, , allow

g, support-agent, any-agent
g, triage-agent, any-agent
p, triage-agent, tickets.read, , allow
p, triage-agent, tickets.label, , allow

g, alice, support-staff

从上往下阅读:

  • support-agent 可以使用所有工单工具,读取订单,并且每次调用最多退款 100。条件 r.args.amount <= 100 会根据模型生成的参数进行求值。
  • 继承自 any-agent 的每个角色都会被拒绝 shell 工具和任何以 .delete 结尾的工具,无论还授予了哪些其他权限。将适用于所有代理的护栏规则放在这里。
  • support-staff 是一个人类角色;alice 拥有该角色。
  • triage-agent 是第二个更窄范围的代理,只能读取和标记工单。
提示

在条件中编写字符串字面量时使用单引号,例如 r.args.region == 'eu'。如果条件需要逗号,请用双引号将整个字段包裹起来。

4. 检查每个工具调用​

authorize_tool_call 运行两项检查。代理自身的权限限制了代理总体能做什么,而用户的权限限制了代理能为该用户做什么。只有同时通过这两项检查的调用才会被执行。

tools.py
from types import SimpleNamespace

import casbin

enforcer = casbin.Enforcer("model.conf", "policy.csv")


class ToolDenied(Exception):
pass


def authorize_tool_call(agent: str, user: str, tool: str, args: dict) -> None:
"""Allow the call only if both the agent and the user it acts for may make it."""
request_args = SimpleNamespace(**args)
if not enforcer.enforce(agent, tool, request_args):
raise ToolDenied(f"{agent} may not call {tool} with {args}")
if not enforcer.enforce(user, tool, request_args):
raise ToolDenied(f"{user} may not call {tool}, so an agent acting for them may not either")


# The tools your agent can see. In a real application they call your services.
TOOLS = {
"tickets.read": lambda ticket_id: {"id": ticket_id, "subject": "Refund request", "order_id": "A-1001"},
"orders.read": lambda order_id: {"id": order_id, "total": 240},
"orders.refund": lambda order_id, amount: {"order_id": order_id, "refunded": amount},
"shell.exec": lambda command: {"output": "..."},
}


def call_tool(agent: str, user: str, tool: str, args: dict) -> dict:
"""Run a tool call proposed by the model, or return the denial as the tool result."""
try:
authorize_tool_call(agent, user, tool, args)
except ToolDenied as e:
# Returning the reason lets the model explain it or try something else.
return {"error": "permission_denied", "reason": str(e)}
return TOOLS[tool](**args)


if __name__ == "__main__":
# Tool calls as a model might propose them while helping alice with a ticket.
proposed = [
("tickets.read", {"ticket_id": "T-42"}),
("orders.read", {"order_id": "A-1001"}),
("orders.refund", {"order_id": "A-1001", "amount": 240}),
("orders.refund", {"order_id": "A-1001", "amount": 80}),
("shell.exec", {"command": "rm -rf /"}),
]
for tool, args in proposed:
print(tool, args, "->", call_tool("support-agent", "alice", tool, args))

print()
print("bob:", call_tool("support-agent", "bob", "tickets.read", {"ticket_id": "T-42"}))

运行它会打印:

tickets.read {'ticket_id': 'T-42'} -> {'id': 'T-42', 'subject': 'Refund request', 'order_id': 'A-1001'}
orders.read {'order_id': 'A-1001'} -> {'id': 'A-1001', 'total': 240}
orders.refund {'order_id': 'A-1001', 'amount': 240} -> {'error': 'permission_denied', 'reason': "support-agent may not call orders.refund with {'order_id': 'A-1001', 'amount': 240}"}
orders.refund {'order_id': 'A-1001', 'amount': 80} -> {'order_id': 'A-1001', 'refunded': 80}
shell.exec {'command': 'rm -rf /'} -> {'error': 'permission_denied', 'reason': "support-agent may not call shell.exec with {'command': 'rm -rf /'}"}

bob: {'error': 'permission_denied', 'reason': 'bob may not call tickets.read, so an agent acting for them may not either'}

即使 alice 可以退款任意金额,240 的退款请求也会被拒绝,因为代理不能这样做。Bob 没有角色,所以代理无法为他做任何事。将拒绝作为工具结果返回,而不是将其抛给最终用户,可以让模型解释限制或将案例转交给人工处理。

5. 在 MCP 服务器中使用它​

在使用 OAuth 的 MCP 服务器中,访问令牌已经告诉了你两个身份:OAuth 客户端是代理,令牌的主体是授权它的用户。使用官方 Python SDK(版本 2),通过 get_access_token() 读取它们,并检查每个工具调用:

server.py
from mcp.server.auth.middleware.auth_context import get_access_token
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

from tools import ToolDenied, authorize_tool_call

mcp = MCPServer("support-tools")


def authorize(tool: str, args: dict) -> None:
"""Check the tool call against Casbin for the OAuth client (the agent) and the user it acts for."""
token = get_access_token()
if token is None or token.subject is None:
raise ToolError("not authenticated")
try:
authorize_tool_call(token.client_id, token.subject, tool, args)
except ToolDenied as e:
raise ToolError(str(e)) from e


@mcp.tool()
def refund_order(order_id: str, amount: float) -> dict:
"""Refund part or all of an order."""
authorize("orders.refund", {"order_id": order_id, "amount": amount})
return {"order_id": order_id, "refunded": amount}


@mcp.tool()
def read_ticket(ticket_id: str) -> dict:
"""Read a support ticket."""
authorize("tickets.read", {"ticket_id": ticket_id})
return {"id": ticket_id, "subject": "Refund request"}

抛出 ToolError 会将拒绝转换为设置了 isError 的工具结果,MCP 客户端会将其传回给模型。令牌的 client_id 必须与策略中的代理名称匹配;将每个代理注册为其自己的 OAuth 客户端,以便赋予其独立的权限并单独撤销它们。

设计说明​

  • 默认拒绝。 任何规则未提及的工具都无法被调用,因此在授予权限之前,新工具对代理不可用。
  • 每个代理的最小权限。 为每个代理分配其自己的角色,而不是共享一个强大的角色。上面的 triage-agent 即使提示要求,也无法触及订单。
  • 检查参数,而不仅仅是名称。 关于金额、接收者、路径或区域的限制属于条件部分。在检查之前验证参数类型:条件会比较模型发送的任何内容,将字符串 "500" 与数字比较会引发错误,而不是返回决策。
  • 无需重新部署即可更改权限。 规则是数据:enforcer.add_policy(...)、enforcer.add_role_for_user(...) 或通过 adapter 进行的编辑会在下一次调用时生效。当多个进程为代理服务时,请使用 watcher。
  • 审计。 enforcer.enforce_ex(...) 返回允许调用的规则;将其记录在工具调用旁边。
  • 过滤工具列表。 在列出工具时调用相同的检查,这样模型甚至不会被提供它无法使用的工具。这也有助于节省 token。

下一步​

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.