AI Agents · 课时

工具访问控制

工具必须检查用户（而不只是代理）是否获得授权——代理不是主体。

工具访问控制 是 CoddyKit 上的免费 AI Agents 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

工具不是权限主体

模型会“调用工具”，但实际执行 ACTION 的是您的代码。权限主体是用户，而不是代理。

请根据 USER 的身份进行授权，绝不要仅仅因为“代理做出了决定”就授予权限。

Authorise at the Tool Boundary

def refund_order(order_id, *, user):
    order = db.get_order(order_id)
    if order.customer_id != user.id and not user.is_staff:
        raise PermissionError(f'User {user.id} cannot refund order {order_id}')
    return stripe.refund(order.payment_id)

传递用户上下文

将用户对象传入每次工具调用：

def dispatch(tool_call, user):
    args = json.loads(tool_call.function.arguments)
    fn = TOOLS[tool_call.function.name]
    return fn(**args, user=user)

按工具设置权限

定义每个角色可以使用哪些工具：

ROLE_TOOLS = {
    'customer': ['search_orders', 'open_ticket'],
    'support': ['search_orders', 'refund_order', 'cancel_order'],
    'admin': ['*']
}

visible_tools = [t for t in ALL_TOOLS if t.name in ROLE_TOOLS[user.role] or 'admin' in ROLE_TOOLS[user.role]]

限定数据访问范围

查询数据库的工具必须自动按用户限定数据范围：

def search_orders(query, user):
    # NEVER let the model bypass this WHERE clause
    return db.query('SELECT * FROM orders WHERE customer_id = %s AND ...', (user.id,))

审计每次工具调用

记录：谁、做了什么、何时进行、使用了哪些参数，以及结果。当出现问题时，这就是您的取证轨迹：

audit_log({
    'user_id': user.id,
    'tool': tool_name,
    'args': args,
    'result_status': result.status,
    'timestamp': now()
})

确认破坏性操作

即使是已获授权的用户，也要再次确认破坏性操作：

def delete_account(user_id, confirmed=False, user=None):
    if not confirmed:
        return {'requires_confirmation': True, 'msg': 'Confirm deletion of account.'}
    db.execute('DELETE ...', (user_id,))

OAuth / 令牌限定工具

对于代表用户操作外部服务的代理，请严格限定 OAuth 令牌的权限范围：

# Token only has gmail.send scope, not gmail.read
send_email = build_with_token(user_token_scoped_send)

服务账户边界

代理自己的服务账户应仅拥有最低限度的权限：

供分析工具使用的只读数据库用户
按客户划分的 S3 存储桶
通过 VPC 隔离的网络

Rate Limits Per Tool

def ratelimit(key, per_user_per_day=10):
    counts = {}
    def decorator(func):
        def wrapper(user_id, *args, **kwargs):
            counts.setdefault(user_id, 0)
            if counts[user_id] >= per_user_per_day:
                print(f'{key}: user {user_id} rate limited')
                return None
            counts[user_id] += 1
            return func(user_id, *args, **kwargs)
        return wrapper
    return decorator

@ratelimit(key='tool:refund', per_user_per_day=2)
def refund_order(user_id, order_id):
    print(f'refunding order {order_id} for user {user_id}')
    return True

for i in range(3):
    refund_order('user1', f'order{i}')

用户可见的权限界面

向用户展示代理可以代表其执行哪些操作，并允许用户撤销各工具的权限。这对建立信任至关重要。

高风险操作需要重新认证

让敏感工具要求进行新鲜认证（最近一次登录距今 < 5 分钟）：

if tool.is_sensitive and user.last_auth_age_seconds > 300:
    raise StaleAuthError('Please re-authenticate to perform this action.')

像测试代码一样测试授权

编写测试，验证“用户 A 不能为用户 B 的订单退款”——绝不要假设访问控制一定有效。访问控制是代理安全漏洞的第一大来源。

授权原则

代理调用工具时，检查的是谁的权限？

回顾

用户是权限主体。将用户身份传递给每个工具。按用户限定数据范围。审计每次调用。确认破坏性操作。像测试代码一样测试授权。

常见问题解答

「工具访问控制」课时是免费的吗？

是的 — 「工具访问控制」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「工具访问控制」这节课中我会学到什么？

工具必须检查用户（而不只是代理）是否获得授权——代理不是主体。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「工具访问控制」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents