共享Agent权限隔离实战：从权限模型到最小策略执行器

最近一年，AI Agent 从一个展示用的概念，快速变成了团队里真实跑任务的角色。不少人应该都经历过这样的场景：本地 demo 里，agent 调用工具、读写文件、执行命令，一切都很顺利；可一旦想把它放到团队里共享，问题立刻冒出来——怎么让这个 agent 既能干活，又不能什么活都干？尤其是当它背后连着代码仓库、数据库、第三方 API 时，一个权限边界不清晰的 agent，就像一个拥有万能钥匙但缺乏判断力的实习生。

Hacker News 上有一个叫 AgentConnect 的项目，项目定位非常直白：共享 agents，但权限完全分离。表面上看，它解决的是“让多个 agent 能互相连接”的问题；但更准确地说，它真正处理的矛盾是：团队希望复用一套 agent 基础设施，而不同角色、不同项目、不同环境，又必须拥有互不干扰的权限边界。这个方向比单纯多做一个 agent 框架更接近生产环境的核心焦虑。

这篇文章不打算停留在项目介绍层面。我会从“为什么 agent 权限隔离是上生产的必修课”讲起，拆解一套通用的共享 agent 权限模型，然后给出可跑通的演示环境、配置文件和最小策略执行器代码。考虑到项目资料有限，文中涉及的安装命令和配置均为演示性写法，实际部署请以 AgentConnect 官方文档为准，但其中的架构思路和权限模型，可以直接迁移到你自己的 agent 平台里。

1. 为什么说 Agent 权限隔离是上生产的必修课

传统软件系统的权限控制，对象是“用户”和“角色”。一个用户登录系统，后端根据他属于哪个角色，决定能访问哪些接口。这套模型运行了几十年，非常成熟，但 AI Agent 把这个问题彻底改变了。

原因在于，Agent 不是被动的 API 调用方。它会根据模型推理结果，自主决定下一步调用哪个工具、读取哪个文件、执行哪条命令。也就是说，权限控制的粒度不能再停留在“用户能不能登录系统”这个层面，而要深入到“这个 agent 在下一次工具调用时，能不能访问某一个具体资源”。大模型本身不可控，Agent 的规划路径也不可预测，如果权限控制只做在入口，运行时的每一次工具调用就可能成为越权点。

共享 Agent 的需求又加剧了这个问题。一个成熟的 agent 往往封装了模型配置、提示词模板、工具集合和一套工作流，搭建成本不低。如果每个团队成员各自维护一套，不仅浪费资源，还容易出现模型版本和工具逻辑的分叉。更合理的做法是：团队共享一套 agent 基础设施，再根据使用者身份、项目环境、数据敏感度，动态决定这个 agent 当前能调用哪些能力。

如果这两个需求没有同时设计，就一定会出现下面几类事故：

• 一个用于本地调试的 agent，因为配置里带上了生产数据库的凭证，直接在同事电脑上连上了线上库。
• 两个项目共享同一个 agent，结果 A 项目的 agent 意外读取了 B 项目保存在同一目录下的配置文件和密钥。
• 运维同学通过 agent 执行了一条删除命令，但由于操作者是“管理员角色”，系统无条件放行，事后却无法定位到具体是哪条指令、哪个触发点。

这些问题的本质，不是 agent 能力不够，而是权限模型没有跟上 agent 的执行方式。AgentConnect 这类项目想做的，就是把“共享”和“隔离”放到同一个系统设计里，让 agent 可以复用，但能力边界必须按人、按项目、按环境切分。

2. AgentConnect 的设计核心：共享 Agent，分离权限

从项目命名和定位来看，AgentConnect 的核心思路是把“执行能力”和“权限边界”解耦。这句话值得多说几遍，因为很多 agent 平台的设计是反过来的：先给 agent 挂上一堆工具，再在调用时做一些简单的“当前用户是否登录”校验，完全没有把权限作为一级公民来设计。

我更愿意把 AgentConnect 这类方案拆成四个层次来理解：

这个分层的价值在于，Agent Runtime 不需要知道自己正在为哪个用户服务；它只需要在每次调用外部能力之前，向 Policy Engine 发起一次授权请求。允许就执行，拒绝就返回原因。Capability Registry 管“有哪些能力可以用”，Policy Engine 管“当前上下文里谁能用哪些能力”，两者通过资源标识串起来。

对比传统权限方案，差异非常明显：

从项目标题“shared agents with separate permissions”来看，AgentConnect 想强调的就是“共享”与“分离”并存。共享的是 agent 本身，分离的是权限模型。这种设计如果落地，团队内部可以沉淀出一套 agent 市场：不同团队注册自己的 agent，使用者按权限访问，互相看不到不该看的工具和数据。

3. Agent 权限模型：从用户权限到工具级权限

在设计 Agent 权限模型之前，可以先回顾两套经典模型：RBAC 和 ABAC。

RBAC（Role-Based Access Control，基于角色的访问控制）是最常见的权限模型。系统里定义若干角色，例如 developer、ops、admin，再把用户分配到角色，角色绑定权限。它的优点是简单直观，缺点是粒度较粗：一个“开发者”角色可能同时拥有读写代码仓库和访问生产日志的权限，但某个具体开发者只需要其中一部分。

ABAC（Attribute-Based Access Control，基于属性的访问控制）更进一步。它不是直接判断“用户属于哪个角色”，而是根据一组属性来做决策，例如用户部门、资源归属、访问时间、IP 段、数据敏感级别。ABAC 的表达能力更强，但实现和运维复杂度和 RBAC 不在一个量级。

Agent 场景的权限模型，需要把两者结合起来，再加一层“工具调用级”的控制。一个完整的权限决策，通常需要几个要素：

• 主体（Subject）：发起操作的用户、agent、服务账号，或者用户身份在 agent 会话里的延续。
• 动作（Action）：read、write、execute、delete、create 等。
• 资源（Resource）：数据库表、文件路径、API 端点、浏览器会话、云服务实例。
• 条件（Condition）：环境标签、时间窗口、IP 范围、数据敏感等级、租户 ID。

例如，一条权限策略可以表达为：“允许 developer 角色在 staging 环境读取 sales 数据库的订单表，但禁止在生产环境执行删除操作。”在 Agent 场景下，这条策略还会继续细化：“允许 agent-a 调用 git_push 工具，但只允许在 repo 前缀为 demo- 的仓库里执行。”

下面是权限策略的 JSON 风格示例，方便理解模型结构：

{ "policy_id": "policy-001", "effect": "allow", "subject": { "role": "developer", "project": "demo-project-a" }, "action": ["read", "execute"], "resource": { "type": "tool", "name": "git_tool", "repo_prefix": "demo-" }, "condition": { "environment": ["dev", "staging"], "time_range": "09:00-18:00" } }

注意，这里有一个很多团队容易忽略的点：Agent 执行期间，用户身份不能丢失。很多实现为了省事，让 agent 用自己的服务账号去调用所有工具，结果就是审计日志里只能看到“agent-x 做了什么”，看不到“哪个用户发起的会话导致 agent 这么做”。正确的做法是，在会话开始时就绑定用户身份，在每次工具调用时把这个身份透传到权限引擎。这也恰好对应了共享 Agent 场景里“同一个 agent，不同人有不同权限”的基本要求。

4. 架构拆解：一次带权限校验的 Agent 请求

理解了权限模型，再看架构就比较清楚了。一个共享 Agent 平台，至少要包含这几个组件：客户端入口、认证网关、Agent Runtime、策略引擎、工具执行器，以及贯穿全流程的审计日志。

一次完整请求的路径大致如下：

1. 用户通过客户端发起一个任务，例如“帮我检查代码仓库里有没有泄露的密钥”。
2. 请求首先经过认证网关，解析用户身份、项目归属和环境标签。
3. 网关把身份信息透传给 Agent Runtime，Agent Runtime 开始规划任务。
4. 模型根据任务规划，决定调用哪个工具，例如code_scan_tool。
5. 在真正调用工具之前，Agent Runtime 向 Policy Engine 发起授权请求，带上主体、动作、资源和条件。
6. Policy Engine 加载策略集合，按匹配顺序做决策，返回 allow 或 deny。
7. 允许则执行工具调用，拒绝则中断规划并向用户解释原因。
8. 无论结果如何，审计日志都会记录这一次权限决策和工具调用。

画成文字流程可能不够直观，但有一个关键点必须强调：权限决策不能只靠 agent 的提示词约束，必须在运行时由独立的策略引擎强制执行。

很多人在 demo 阶段会想：“我在 system prompt 里写清楚‘不要访问生产数据库’不就行了？”但提示词本质上是一种软约束，模型可能被后续对话中的 prompt injection 覆盖，也可能因为上下文太长而遗忘规则。策略引擎不一样，它运行在模型之外，在工具调用真正发生前拦截，不依赖模型的自觉性。这就像路上写的交通标语再多，也不如红绿灯和交警的强制执法有效。

还有一个细节值得注意：工具执行器在拿到策略允许结果后，应该再次校验资源标识，避免 agent 在策略评估后被注入或篡改参数。也就是说，授权决策和实际执行之间的资源标识必须一致，才能防止 TOCTOU 竞态问题。

这一整套流程，在本地跑一个单机 agent 时是多余的，但一旦放到团队共享场景，它的价值立刻显现。AgentConnect 想做的，就是把这套强制执行逻辑做成通用组件，而不是让每个团队从头实现。

5. 环境准备：用 Docker Compose 搭建演示环境

在深入具体配置之前，先准备一个可以跑通的演示环境。这里我用 Docker Compose 搭建一个简化版的共享 Agent 权限服务，包含网关、策略服务和内存工具执行器。这个演示不依赖特定云服务，适合在本地快速理解权限模型。

环境要求如下：

• Docker 20.10 以上，支持 Compose V2。
• 可用的命令行终端。
• Python 3.9 以上，用于运行最后的权限策略执行器脚本。
• 内存至少 2GB，避免容器启动失败。

版本信息请以实际环境为准，本文重点是演示思路。创建一个工作目录，例如agent-connect-demo，然后新建docker-compose.yml文件：

version: "3.9" services: policy-service: image: python:3.11-slim container_name: agent-policy-service working_dir: /app volumes: - ./policy:/app/policy - ./policies.yml:/app/policies.yml command: python /app/policy_server.py ports: - "8080:8080" environment: POLICY_FILE: /app/policies.yml LOG_LEVEL: info agent-runtime: image: python:3.11-slim container_name: agent-runtime working_dir: /app volumes: - ./runtime:/app/runtime command: python /app/runtime/agent_server.py ports: - "8081:8081" depends_on: - policy-service environment: POLICY_SERVICE_URL: http://policy-service:8080

由于演示服务需要实际代码，这里我先创建一个极简的 Python HTTP 服务。为了不让篇幅失控，下面直接给出完整的政策服务端代码，这是一个只包含核心逻辑的最小实现。

如果你不想用 Docker，也可以直接把 Python 服务跑在宿主机上，只需要保证policies.yml文件路径正确即可。使用 Docker 的好处是隔离干净、不污染本地 Python 环境，这也是团队共享 agent 时推荐的做法。

6. 配置共享 Agent 与权限策略

先定义一个 agent 注册文件，这个文件描述了一个名为dev-assistant的共享 agent。它自身可用能力包含代码读取、测试执行、数据库查询和配置刷新，但具体哪些能力对谁开放，完全由权限策略决定。

agent: id: dev-assistant name: "Development Assistant" description: "Shared agent for daily development tasks" capabilities: - id: read_repo type: tool command: git - id: run_test type: tool command: pytest - id: query_database type: tool command: sql - id: refresh_config type: tool command: config credentials: # 实际部署时通过环境变量或密钥管理服务注入，不要写入仓库 - name: db_password env_key: DEMO_DB_PASSWORD

接下来是权限策略文件policies.yml。这个文件定义了三类策略：默认拒绝所有未匹配的请求；developer 角色允许在 dev 环境读代码和跑测试；ops 角色允许在 staging 环境刷新配置，但禁止操作生产环境数据库。

policies: - id: default-deny description: "Default deny all" effect: deny subject: "*" action: "*" resource: "*" - id: developer-dev-read description: "Developer can read repo and run tests in dev" effect: allow subject: role: developer action: [read, execute] resource: type: tool id: [read_repo, run_test] condition: environment: dev - id: ops-staging-refresh description: "Ops can refresh config in staging" effect: allow subject: role: ops action: [execute] resource: type: tool id: refresh_config condition: environment: staging - id: never-prod-db description: "Never allow database operations in production" effect: deny subject: "*" action: [read, write, execute, delete] resource: type: tool id: query_database condition: environment: production

注意这里的关键设计：default-deny放最前面，作为兜底；never-prod-db用 deny 规则显式拦截生产数据库操作，优先级高于 allow 规则。在实际策略引擎里，deny 优先是最稳妥做法，因为默认允许 + 黑名单模式在 Agent 场景下会造成不可控的权限面。应该用“默认拒绝 + 白名单 allow + deny 例外”的方式来组织策略。

还有一个容易被忽略的细节：策略里的 environment 字段，不应该从客户端传入的请求参数直接读取，而应该由网关根据环境标签决定。否则一个攻击者可能直接把请求里的 environment 改成 dev，绕过生产环境的限制。这个字段属于可信上下文，不能由前端随意指定。

7. 完整示例：写一个最小权限策略执行器

为了把策略模型跑起来，这里实现一个最小权限策略执行器。它不依赖任何外部框架，用 Python 标准库即可运行，核心逻辑是：输入“用户角色 + 动作 + 工具 ID + 环境”，输出 allow 或 deny，并记录决策原因。

# 文件路径：agent-connect-demo/policy/engine.py import yaml from datetime import datetime class PolicyEngine: def __init__(self, policy_file: str): with open(policy_file, "r", encoding="utf-8") as f: data = yaml.safe_load(f) self.policies = data.get("policies", []) @staticmethod def _match_subject(subject_rule, user_role, user_project): if subject_rule == "*": return True if isinstance(subject_rule, dict): role_ok = subject_rule.get("role") in (None, user_role) project_ok = subject_rule.get("project") in (None, user_project) return role_ok and project_ok return False @staticmethod def _match_action(action_rule, action): if action_rule == "*": return True if isinstance(action_rule, list): return action in action_rule return action == action_rule @staticmethod def _match_resource(resource_rule, tool_id): if resource_rule == "*": return True if isinstance(resource_rule, dict): if resource_rule.get("type") != "tool": return False allowed_ids = resource_rule.get("id", []) if isinstance(allowed_ids, list): return tool_id in allowed_ids return tool_id == allowed_ids return False @staticmethod def _match_condition(condition_rule, environment): if not condition_rule: return True if "environment" in condition_rule: return environment in condition_rule["environment"] return True def authorize(self, user_role, user_project, action, tool_id, environment): for policy in self.policies: if not self._match_subject(policy.get("subject"), user_role, user_project): continue if not self._match_action(policy.get("action"), action): continue if not self._match_resource(policy.get("resource"), tool_id): continue if not self._match_condition(policy.get("condition"), environment): continue decision = policy.get("effect", "deny") return { "allowed": decision == "allow", "policy_id": policy.get("id"), "reason": policy.get("description", ""), "timestamp": datetime.utcnow().isoformat(), } return { "allowed": False, "policy_id": None, "reason": "no matching policy", "timestamp": datetime.utcnow().isoformat(), } if __name__ == "__main__": import json import sys engine = PolicyEngine("policies.yml") tests = [ ("developer", "project-a", "read", "read_repo", "dev"), ("developer", "project-a", "execute", "query_database", "prod"), ("ops", "project-b", "execute", "refresh_config", "staging"), ("ops", "project-b", "execute", "refresh_config", "prod"), ("guest", "project-c", "read", "read_repo", "dev"), ] for user_role, user_project, action, tool_id, environment in tests: result = engine.authorize(user_role, user_project, action, tool_id, environment) print(json.dumps(result, ensure_ascii=False))

这段代码实现了策略匹配的最核心逻辑：按策略列表顺序执行，找到第一个同时匹配主体、动作、资源和条件的策略，返回它的 effect。这样的设计有一个小缺点：如果 allow 策略写在 deny 策略前面，本来应该被 deny 的请求可能先命中了 allow 分支。所以实际部署时，需要在加载策略后先按优先级排序，保证 deny 规则的优先级。

运行之前，记得安装依赖：

pip install pyyaml python policy/engine.py

如果policies.yml在项目根目录，上面的脚本可以直接读取。等到脚本跑通，再把它包装成 HTTP 服务，就是上一节 Docker Compose 里policy-server的基础。

8. 运行验证与结果分析

运行python policy/engine.py之后，预期输出如下：

{"allowed": true, "policy_id": "developer-dev-read", "reason": "Developer can read repo and run tests in dev", "timestamp": "2025-01-01T10:00:00.000000"} {"allowed": false, "policy_id": "never-prod-db", "reason": "Never allow database operations in production", "timestamp": "2025-01-01T10:00:00.000000"} {"allowed": true, "policy_id": "ops-staging-refresh", "reason": "Ops can refresh config in staging", "timestamp": "2025-01-01T10:00:00.000000"} {"allowed": false, "policy_id": "default-deny", "reason": "Default deny all", "timestamp": "2025-01-01T10:00:00.000000"} {"allowed": false, "policy_id": "default-deny", "reason": "Default deny all", "timestamp": "2025-01-01T10:00:00.000000"}

怎么判断结果是正确的？

第一组测试，developer 角色在 dev 环境读代码仓库，匹配developer-dev-read，允许。第二组测试，同一个 developer 在 prod 环境执行数据库查询，被never-prod-db拦截，符合预期。第三组，ops 在 staging 刷新配置，允许。第四组，ops 在 prod 刷新配置，没有匹配的 allow 策略，被default-deny兜底拒绝。第五组，guest 角色尝试读仓库，同样被默认拒绝。

如果你看到的结果里第五组测试返回了 allow，优先检查default-deny策略的 subject 是不是*。很多情况下，默认拒绝策略写成了subject: ""或者直接漏掉，导致引擎遍历完所有策略后返回系统默认的no matching policy，这在权限模型里虽然也会拒绝，但语义上不如显式的default-deny清晰，也会让审计日志更难分析。

把脚本改成 HTTP 服务后，可以这样验证一次真实请求：

curl -X POST http://localhost:8080/authorize \ -H "Content-Type: application/json" \ -d '{ "user_role": "developer", "user_project": "project-a", "action": "read", "tool_id": "read_repo", "environment": "dev" }'

预期响应：

{ "allowed": true, "policy_id": "developer-dev-read", "reason": "Developer can read repo and run tests in dev", "timestamp": "2025-01-01T10:00:00.000000" }

如果服务没有启动，先看 Docker 容器日志：docker compose logs policy-service。权限服务最大的特点是没有状态，日志里应该能直接看到每一条请求的决策结果。如果连日志都没有，检查网关是否把请求转发到了正确的端口，以及 Python 服务是否成功读取了policies.yml。

9. 常见问题与排查思路

在实际集成 AgentConnect 或自建类似方案时，下面这些问题是出现频率最高的。

这里特别提醒一点：权限策略是运行时拦截，但不是万能保险。如果工具执行器本身可以直接被网络访问，攻击者完全可以绕过 agent 平台，直接调用工具接口。所以“策略引擎拦截”和“工具执行器不对外暴露”必须同时成立。就像浏览器会对 unload 事件做 Permissions-Policy 拦截一样，平台侧的强制策略要尽量靠近资源端，而不是只放在入口处。

关于权限绕过类的话题，技术社区偶尔会有讨论，但并不值得研究。正确的做法是默认拒绝、最小授权、全量审计，把攻击面压到最小，而不是和模型的可控性较劲。

10. 工程落地最佳实践

把共享 Agent 和权限分离真正落地到生产环境，下面几条实践值得写进团队规范。

第一，默认拒绝，白名单放行。权限策略的默认动作必须是 deny，每一条 allow 都应该能说清楚“为什么需要这个权限”。这会让策略文件变长，但换来的是一次误操作事故省下的成本。实际项目中，可以先从 3 到 5 条策略开始跑通流程，再逐步细化到工具级和资源级。

第二，按环境彻底隔离。dev、staging、production 三个环境的 agent 配置、凭证、工具目标必须在物理或逻辑上隔离。最稳妥的做法是每个环境独立部署一套服务，生产环境的 agent 不持有 test 环境的数据库凭证。环境字段不能只靠策略文件里的条件判断，更要把不同环境的配置放在不同配置文件里。

第三，密钥和凭证一律外部化。agent 注册文件里不要出现明文密码。凭证通过环境变量、KMS 或密钥管理服务注入，agent 运行时本身不感知明文密钥。这样即使 agent 被诱导输出日志或文件内容，也不会直接把生产凭证带出来。

第四，审计日志必须完整且不可篡改。授权决策、工具调用、执行结果、失败原因，四类事件缺一不可。日志至少保留 90 天，推荐追加写入，禁止普通运维账号删除审计日志。出了问题能追溯，是 Agent 权限体系最后的底线。

第五，变更前备份，变更后验证。修改权限策略属于高风险操作。建议先导出当前策略文件备份，再在 staging 环境预览改动影响，确认没有意外放行后，再同步到生产。同时，策略引擎要支持灰度切换，至少做到“旧策略和新策略并行对比”。

第六，定期做权限评审。Agent 的能力是变化的，模型版本升级、工具集合调整、人员角色变动，都会让旧策略失效或过于宽松。建议每月或者每个迭代周期，由安全负责人和 agent 负责人一起过一遍策略文件，重点检查是否有长期无人使用的宽泛 allow 规则。

第七，在测试场景里也要用权限模型。例如用 Playwright 编写 agent 测试时，测试 agent 同样需要独立的浏览器会话权限，以及访问测试环境的授权。不要因为“只是测试”就放开所有权限，因为测试环境往往最容易拿到真实数据的副本。

11. 总结与后续学习建议

AgentConnect 这个项目真正切中的问题，是 AI Agent 从单机 demo 走向团队协作时绕不开的权限边界。共享 agent 降低的是基础设施成本，权限隔离降低的是事故风险，两者缺一不可。如果不能做到“共享但隔离”，团队可能永远只敢把 agent 用在低风险场景，无法发挥它的真正价值。

这篇文章从权限模型讲到了架构流程，又给出了一个可以直接跑通的最小策略执行器。建议下一步按这样的路径实践：先在本地跑通 demo，把用户角色、工具、资源、环境四个维度理清楚；然后画出你自己业务的权限矩阵，把所有工具调用列出来；最后以“默认拒绝 + deny 优先 + 全量审计”为底线，做一个最小可用的拦截层。

权限体系不是一次性配置，而是持续运营。随着 agent 数量增加、工具种类变多、团队成员变动，策略会不断演进。只要设计时把“执行能力”和“权限边界”分开，后面扩展就不会失控。无论最终选用 AgentConnect 还是自建方案，这套模型都值得作为团队 agent 平台的默认起点。