共享Agent与权限隔离：从设计理念到代码实现

如果你所在的团队已经开始使用各种 AI 编程助手、运营机器人、数据查询机器人一定会遇到一个尴尬场景Agent 被做成了“单人份”每个人都维护一套相同的脚本和配置权限还很难管理。要么所有成员共用一套账号越权风险很大要么每个人各搞一套运维成本直线上升。AgentConnect 这个项目名字背后其实是一个非常典型的多用户协作问题Agent 可以共享但权限必须隔离。这篇文章会围绕这个主题从设计理念讲到代码实现。需要注意的是这篇文章中的“Agent”指智能体、自动化机器人而不是网络代理。我们讨论的是 AI Agent、自动化工作流的共享与权限隔离问题。1. 共享 Agent 的权限隔离为什么需要 AgentConnect1.1 从“Agent 私有化”到“Agent 共享化”最早使用 AI Agent 时多数团队是让每个工程师自己写脚本、自己调 API。后来发现问题很明显二十个人的团队有二十份“查询数据库并生成周报”的代码接口升级时要通知所有人改代码权限也只能靠各自记住“别乱删数据”来维持。于是团队开始把高频 Agent 统一成一个公共能力中心。所有人调用的是同一个 Agent同一个版本的逻辑同一个维护入口。这样很高效但立刻暴露出一个新的瓶颈权限。假设团队里有一个数据查询 Agent它能查客户订单也能导出全量客户信息。产品经理只需要看汇总数据数据分析师需要导出明细客服主管只想看售后记录。如果大家用的是同一个 Agent而 Agent 又“一视同仁”地开放全部能力那产品经理不小心导出客户明细就成了数据安全事故。1.2 共享与隔离并不矛盾AgentConnect 这种设计给了我一个很清晰的思路Agent 本身是共享资源但每个使用者在 Agent 上的权限是独立的。这是什么意思呢举个例子团队共享一个>pip install pyyaml版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你使用的是 Python 3.12 或 3.13同样可以运行。3.2 创建项目结构我们先创建一个干净的目录结构方便后续扩展成完整的 Agent 管理平台。mkdir agentconnect_demo cd agentconnect_demo目录结构如下agentconnect_demo/ |-- agents.yaml |-- policies.yaml |-- agent_manager.py |-- main.pyagents.yaml定义所有共享 Agent 资源。policies.yaml定义权限策略即谁能对哪个 Agent 做什么。agent_manager.py核心逻辑加载配置、校验权限、执行 Agent。main.py命令行入口模拟不同用户调用 Agent。整体实现尽量保持轻量便于理解权限模型的本质。4. 定义 Agent 资源与权限策略4.1 定义共享 Agent 资源现在先定义三个共享 Agent模拟一个团队常见的 AI Agent 场景。文件路径agentconnect_demo/agents.yamlagents: - id: code-reviewer name: 代码评审助手 description: 对代码提交进行静态分析和风险提示 actions: - review - comment - id: data-query name: 数据查询助手 description: 查询业务数据库生成报表可导出明细 actions: - query - export - id: ops-bot name: 运维操作机器人 description: 执行发布、重启等运维操作 actions: - deploy - restart在这个文件里actions声明了该 Agent 支持的全部动作。代码评审助手支持 review 和 comment数据查询助手支持 query 和 export运维机器人支持 deploy 和 restart。要注意的是这里声明的只是 Agent 的“能力”。一个用户是否真的能用这些能力还要看权限策略。4.2 定义权限策略权限策略文件是关键。我们给不同用户分配不同权限模拟真实的共享 Agent 场景。文件路径agentconnect_demo/policies.yamlpolicies: - agent_id: code-reviewer users: [alice, bob] groups: [developers] actions: [review, comment] - agent_id: data-query users: [alice] groups: [data-analysts] actions: [query, export] - agent_id: data-query users: [bob] groups: [developers] actions: [query] - agent_id: ops-bot users: [ops-lead] groups: [ops] actions: [deploy, restart]这里的策略含义如下code-reviewer共享给 alice、bob以及 developers 组允许 review 和 comment。>import json import time from typing import Dict, List import yaml class AgentPermissionError(Exception): 权限不足时抛出的异常 pass class AgentNotFoundError(Exception): Agent 不存在时抛出的异常 pass导入yaml用于解析配置文件。定义两个自定义异常在后续逻辑中分别表示权限不足和 Agent 不存在。5.2 加载配置接下来定义一个配置加载函数和一个资源管理器类。def load_yaml(path: str): with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) class AgentRegistry: 共享 Agent 资源注册中心 def __init__(self, agents_file: str, policies_file: str): self.agents_data load_yaml(agents_file) self.policies_data load_yaml(policies_file) self.agents {agent[id]: agent for agent in self.agents_data[agents]} self.policies self.policies_data[policies] def get_agent(self, agent_id: str) - dict: if agent_id not in self.agents: raise AgentNotFoundError(fAgent 不存在: {agent_id}) return self.agents[agent_id]AgentRegistry把两个 YAML 文件解析成内存对象然后提供一个get_agent方法。self.agents是字典结构用agent_id作为 key这样可以根据 ID 快速找到 Agent。5.3 权限校验器权限校验是整个系统的核心。我们单独写一个类避免和业务逻辑混在一起。class PermissionValidator: 基于策略的权限校验器 def __init__(self, registry: AgentRegistry): self.registry registry def _match_user_or_group(self, rule: dict, user: str, groups: List[str]) - bool: if user in rule.get(users, []): return True if any(group in rule.get(groups, []) for group in groups): return True return False def _match_action(self, rule: dict, action: str) - bool: return action in rule.get(actions, []) def check(self, user: str, groups: List[str], agent_id: str, action: str) - bool: 如果允许返回 True否则返回 False for rule in self.registry.policies: if rule[agent_id] ! agent_id: continue if not self._match_user_or_group(rule, user, groups): continue if self._match_action(rule, action): return True return Falsecheck方法的流程如下遍历所有策略规则。如果规则中的agent_id不是当前请求的 Agent跳过。如果规则没有匹配当前用户和用户组跳过。如果规则包含请求的动作返回允许。所有规则都遍历完仍然没有匹配返回拒绝。这个顺序很重要。因为“默认拒绝”意味着只有在找到显式授权时才放行。5.4 模拟 Agent 执行器接下来定义 Agent 执行器。在实际系统中这一步可能是调用 LLM、执行 Shell 命令或访问数据库。为了保持演示简单我们使用一个模拟实现。class AgentRuntime: 模拟 Agent 运行环境 def __init__(self, registry: AgentRegistry): self.registry registry def execute(self, agent_id: str, action: str, payload: dict) - dict: agent self.registry.get_agent(agent_id) if action not in agent.get(actions, []): raise AgentNotFoundError( fAgent {agent_id} 不支持动作: {action} ) result { agent_id: agent_id, action: action, payload: payload, status: success, message: f[模拟执行] {agent[name]} 完成 {action} 操作, ts: int(time.time()), } return result这里先检查动作是否在 Agent 支持的能力范围内。这一步是资源校验不是权限校验两者要分开。权限校验决定“你能不能做”资源校验决定“这个动作存不存在”。5.5 统一入口为了方便调用再写一个门面类把权限校验和执行逻辑串起来。class AgentManager: 共享 Agent 管理入口 def __init__(self, agents_file: str, policies_file: str): self.registry AgentRegistry(agents_file, policies_file) self.validator PermissionValidator(self.registry) self.runtime AgentRuntime(self.registry) def invoke(self, user: str, groups: List[str], agent_id: str, action: str, payload: dict None): if payload is None: payload {} if not self.validator.check(user, groups, agent_id, action): raise AgentPermissionError( f用户 {user} 没有权限执行 Agent {agent_id} 的 {action} 动作 ) return self.runtime.execute(agent_id, action, payload)invoke是外部调用的唯一入口。流程是权限校验。如果校验失败抛出AgentPermissionError。如果校验通过交给AgentRuntime执行。这样设计的好处是权限逻辑与业务逻辑完全分离。以后如果要接入真实 Agent只需要改AgentRuntime部分权限校验流程可以保持不变。6. 运行验证6.1 命令行入口接下来编写命令行入口模拟不同用户执行操作。文件路径agentconnect_demo/main.pyimport json import sys from agent_manager import AgentManager, AgentPermissionError # 模拟用户数据库用户 ID - 所属用户组 USER_DB { alice: [data-analysts], bob: [developers], ops-lead: [ops], eve: [], } def main(): if len(sys.argv) ! 5: print(用法: python main.py user agent_id action payload) print(示例: python main.py alice>python main.py alice>{ agent_id: data-query, action: query, payload: { sql: SELECT COUNT(*) FROM orders }, status: success, message: [模拟执行] 数据查询助手 完成 query 操作, ts: 1710000000 }alice 也可以执行export动作因为她被授权了query和export。python main.py alice>python main.py bob>python main.py eve ops-bot deploy {service: web}预期输出[权限拒绝] 用户 eve 没有权限执行 Agent ops-bot 的 deploy 动作因为策略中没有给 eve 配置任何权限所以即使 eve 知道 Agent 的 ID也无法执行任何动作。这验证了“默认拒绝”原则。6.4 结果分析从运行结果可以看到权限校验完全发生在 Agent 动作执行之前。权限判断不依赖 Agent 内部逻辑只依赖policies.yaml配置。如果后续需要调整某个用户对某个 Agent 的权限只需要修改配置文件不需要重新发布 Agent 代码。这种模式在团队 Agent 数量较多时尤其有价值。7. 常见问题与故障排查7.1 问题排查表共享 Agent 权限相关问题在开发和上线阶段经常出现。下面整理了几个高频问题问题现象常见原因解决思路用户被拒绝但配置了权限用户组匹配失败检查用户是否在groups匹配的组中或用户 ID 是否拼写一致权限修改后仍然不生效进程缓存了旧配置确认配置是否重新加载必要时增加配置版本号提示 Agent 不存在agent_id 在agents.yaml中不存在检查两个文件中的 ID 是否一致能访问 Agent但不能执行某个动作策略中actions未包含该动作在对应策略中补充动作新增用户可以直接访问 Agent忘记新增策略规则确认默认拒绝逻辑没有被绕过多条策略冲突权限时有时无策略编写逻辑混乱保持单一规则匹配逻辑避免模糊授权7.2 权限策略最好写单元测试权限策略是安全边界不能只靠手工验证。建议在项目中为权限校验写单元测试覆盖至少以下场景未配置策略的用户被拒绝。配置了 actions 子集的用户被拒绝越权动作。配置了完整 actions 的用户可以正常执行。不存在的 Agent 返回 AgentNotFoundError。同一 Agent 多条策略合并后行为正确。下面是一个使用pytest的测试示例结构import pytest from agent_manager import AgentManager, AgentPermissionError pytest.fixture def manager(): return AgentManager(agents.yaml, policies.yaml) def test_bob_can_query(): result manager.invoke(bob, [developers], data-query, query, {}) assert result[status] success def test_bob_cannot_export(): with pytest.raises(AgentPermissionError): manager.invoke(bob, [developers], data-query, export, {}) def test_unknown_user_denied(): with pytest.raises(AgentPermissionError): manager.invoke(eve, [], data-query, query, {})这类测试能保证权限策略在多人协作迭代时不被意外破坏。7.3 日志与审计权限拒绝和权限允许都应该记录日志。尤其在共享 Agent 场景下多个人使用同一资源一旦出现问题必须能追溯到具体时间点、操作者、调用参数和最终结果。建议每条调用日志至少包含时间戳用户 ID用户组Agent ID动作权限结果调用来源 IP请求 ID8. 最佳实践与工程建议8.1 权限模型设计建议使用用户组管理权限不要为每个用户单独配置策略。用户数量大时单用户策略会爆炸。默认拒绝是底线不要默认允许再加黑名单。保持动作粒度清晰。动作要能表达业务语义比如export、deploy、restart不要用execute笼统代替所有操作。尽量控制策略数量避免两个策略互相覆盖导致难以判断。8.2 Agent 安全边界Agent 本身是自动化执行单元共享后风险会放大。需要注意以下几点不要让 Agent 直接使用高权限账号执行命令。如果 Agent 需要访问数据库或云平台建议使用最小权限的服务账号。对敏感操作要求二次授权。比如deploy这类高危动作可以要求管理员单独审批而不是只要策略匹配就放行。执行环境隔离。如果 Agent 会执行 Python 代码或 Shell 命令应放入 Docker 容器或沙箱环境防止恶意输入影响宿主机器。调用参数校验。权限校验通过后还必须校验 payload 的格式和合法性避免恶意参数进入执行器。8.3 配置管理权限配置属于敏感配置最好不要直接放在普通仓库里明文管理。使用 Git 管理并设置代码评审。通过 CI 检查配置文件格式缺失字段直接失败。权限文件与代码文件分离便于审计。定期检查长期无人使用的 Agent 和策略及时清理。8.4 从 demo 到生产本文的 demo 是一个最小实现。如果要在生产环境落地还需要补充使用 RBAC/ABAC 模型替代简单的用户组匹配。接入统一身份认证比如 OIDC 或企业 SSO。增加分布式会话管理避免多实例部署时权限配置不一致。使用配置中心管理策略支持热更新。接入监控告警权限拒绝次数异常上升时及时感知。这些能力在实际项目中各有不同实现方案但最核心的“共享 Agent独立权限”思路保持一致。9. 总结与下一步这篇文章从 AgentConnect 的设计理念出发围绕“共享 Agent独立权限”实现了一个可运行的权限隔离 demo。我们完成了以下内容理解了共享 Agent 场景下权限隔离的必要性。拆分了主体、Agent、动作三个基本概念。使用 YAML 定义共享 Agent 资源和权限策略。实现了默认拒绝的权限校验器。验证了不同用户对同一 Agent 的不同操作权限。整套代码只有两个配置文件加两个 Python 文件非常适合作为 Agent 权限管理的入门模板。如果你想继续深入可以尝试把AgentRuntime替换成真实的 LLM 调用或工具调用再接入一个 HTTP 接口层就可以变成一个轻量级的内部 Agent 网关。动手把这套 demo 跑一遍然后把你自己的 Agent 能力补进去应该很快就能感受到“共享 Agent独立权限”在团队协作里的价值。