過去一年AI 的最大變化不是“更會聊天”而是“開始動手做事”。從調(diào)用搜索、讀寫數(shù)據(jù)庫到操作瀏覽器、執(zhí)行 Shell 命令越來越多的 Agent 應(yīng)用開始擁有真實世界的行為能力。能力變強當然是好事但它也帶來了一個非?，F(xiàn)實的問題模型說它要執(zhí)行某個動作你憑什么相信這個動作是安全、合理、被授權(quán)的這篇文章想分享的是我在給 AI Agent 加“門檻”時的一套完整設(shè)計。簡單說就是當 AI 想調(diào)用一個工具、執(zhí)行一個操作時它必須先通過一道 Gate證明自己有權(quán)限、有依據(jù)、且符合策略才允許真正動手。我會從一個容易理解的背景講起逐步拆解 Gate 的原理然后給出一個可運行的完整項目最后補充生產(chǎn)環(huán)境中遇到的坑和最佳實踐。無論你是做 AI 應(yīng)用開發(fā)還是正在設(shè)計企業(yè)內(nèi)部 Agent 平臺這篇文章都可以給你一個直接的參考。1. 背景與核心概念1.1 從“AI 只能聊”到“AI 可以動手”上一代 AI 產(chǎn)品的邊界很清晰模型負責(zé)生成文本人負責(zé)看、判斷、執(zhí)行。它的輸出無論如何不嚴謹最壞的結(jié)果也就是一段不通順的文字。但現(xiàn)在不一樣了。以 Tool Use、Function Calling、Code Interpreter 等能力為基礎(chǔ)的 Agent 應(yīng)用已經(jīng)可以主動觸發(fā)動作。一個典型的 Agent 調(diào)用鏈路大概是這樣的用戶輸入 - 大模型理解意圖 - 模型生成工具調(diào)用 - 系統(tǒng)執(zhí)行工具 - 結(jié)果返回給模型 - 模型繼續(xù)決策在這個鏈路里模型從一個“內(nèi)容生成器”變成了“行為決策器”。也就是說模型生成的每一個工具調(diào)用背后都對應(yīng)一個真實世界的動作讀文件、發(fā)消息、改配置、刪數(shù)據(jù)、下單支付……這些動作一旦被系統(tǒng)無條件執(zhí)行風(fēng)險就是不可控的。我在實際開發(fā)中最深的體會是很多 Agent 框架把“如何調(diào)用工具”做得很完善但幾乎沒有解決“該不該調(diào)用這個工具”的問題。模型拿到一個工具列表只要它認為這個工具對完成用戶目標有幫助就會直接發(fā)起調(diào)用。它是“按照概率生成文本”的不理解權(quán)限邊界是什么更不知道一個刪除接口被誤調(diào)用意味著什么。1.2 什么是 Agent GateGate 不是一個新的 AI 組件而是一個位于“模型輸出”和“工具執(zhí)行”之間的受控檢查層。它在工具真正生效之前攔截每一次調(diào)用請求按照預(yù)定義的策略判斷這個 Agent 是否有權(quán)限調(diào)用這個工具、參數(shù)是否合法、該動作是否符合當前上下文、是否需要人工確認只有通過檢查的請求才會被放行。從設(shè)計視角看Gate 的本質(zhì)是在 AI Agent 系統(tǒng)里引入“最小權(quán)限”和“審批流”思路。傳統(tǒng)系統(tǒng)里用戶登錄后的一切操作都由權(quán)限框架統(tǒng)一校驗而在 Agent 系統(tǒng)里模型的每一次工具調(diào)用就相當于一次“用戶操作”所以也需要類似的驗證機制。Gate 可以有多層實現(xiàn)既可以是嵌入代碼里的攔截器函數(shù)也可以是一個獨立的權(quán)限校驗微服務(wù)。如果 Agent 數(shù)量少、工具調(diào)用頻率不高用中間件函數(shù)即可如果多個 Agent 共享同一批工具獨立服務(wù)會是更合適的做法。1.3 Gate 要解決什么問題我總結(jié)下來Agent 安全不是某一個環(huán)節(jié)的問題而是貫穿整個調(diào)用鏈的。Gate 要解決的核心問題可以拆成四塊問題分類具體表現(xiàn)Gate 的應(yīng)對方式身份問題不知道是哪個 Agent 在調(diào)用或者一個 Agent 偽裝成另一個調(diào)用方身份校驗給每個 Agent 分配獨立身份權(quán)限問題只負責(zé)運維的 Agent 調(diào)用了一個刪除數(shù)據(jù)庫的接口工具級 操作級權(quán)限按 Agent 角色授權(quán)合法性問題參數(shù)格式錯誤、關(guān)鍵參數(shù)缺失、輸入包含異常內(nèi)容入?yún)?Schema 校驗對關(guān)鍵參數(shù)做白名單限制風(fēng)險問題高風(fēng)險操作沒有二次確認直接被模型“順手”執(zhí)行了風(fēng)險分級高風(fēng)險操作進入人工審批隊列這四個問題在很多項目里是隱藏的因為開發(fā)階段模型調(diào)用次數(shù)少、工具數(shù)量少問題不容易暴露。但一旦進入生產(chǎn)環(huán)境工具數(shù)量增長、多個 Agent 接入、權(quán)限角色變多沒有 Gate 的話整個系統(tǒng)就會變成一個“誰都能被模型帶動手”的狀態(tài)。那種感覺就像把所有接口都從內(nèi)網(wǎng)開放到了公網(wǎng)又沒有加鑒權(quán)一樣讓人不安。1.4 為什么工程師需要關(guān)注很多開發(fā)者會覺得AI Agent 的安全是安全團隊的事。但實際落地時你會發(fā)現(xiàn)Agent 的工具調(diào)用發(fā)生在業(yè)務(wù)代碼里權(quán)限判斷必須依賴業(yè)務(wù)上下文安全檢查需要融合在業(yè)務(wù)流程中這恰恰是應(yīng)用開發(fā)者的職責(zé)范圍。如果你正在開發(fā) Agent 應(yīng)用或者在規(guī)劃公司內(nèi)部的 AI 基礎(chǔ)設(shè)施Gate 會是“AI 工程實踐”中一個繞不開的節(jié)點。它不要求你會訓(xùn)練模型而是要求你具備系統(tǒng)設(shè)計能力怎么注冊工具、怎么設(shè)計策略、怎么做審計、怎么處理異常。這些能力在傳統(tǒng)后端里很常見但換到 Agent 場景下它有自己獨特的難點——調(diào)用方不再是明確的人而是一個概率模型。2. 環(huán)境準備與版本說明本文的實戰(zhàn)示例以一個輕量級的 Python Agent Gate 為例重點演示核心設(shè)計而不是依賴某個重量級框架。這樣做的原因是Gate 的本質(zhì)是一個通用策略剝離框架依賴后更容易看清楚它的實現(xiàn)思路。環(huán)境準備清單如下操作系統(tǒng)Windows 10/11、macOS、Linux 均可。Python 版本建議 3.10 及以上示例代碼使用dataclass、enum、typing等標準庫能力。額外依賴無強制依賴為了演示 HTTP 調(diào)用可安裝requests但核心 Gate 邏輯不依賴第三方庫。IDE / 編輯器任意支持 Python 的 IDE 均可我習(xí)慣使用 VS Code 或 PyCharm。版本需要根據(jù)你的項目實際情況調(diào)整。如果你的項目已經(jīng)使用 Spring AI、LangChain 或自研 Agent 框架本文的 Gate 設(shè)計思路依然適用只是接入方式要從“函數(shù)攔截”改成框架對應(yīng)的 Middleware 或 Interceptor。本文示例代碼只依賴 Python 標準庫唯一可能不同的是 Python 版本3.8 以上也能跑通只是部分類型語法需要微調(diào)。下面先看一下示例項目的目錄結(jié)構(gòu)。agent-gate-demo/ ├── main.py # 啟動入口模擬 Agent 對話與工具調(diào)用 ├── gate/ │ ├── __init__.py │ ├── registry.py # 工具注冊表登記模型可調(diào)用的工具 │ ├── policies.py # 策略引擎判定 allow/reject/need_review │ ├── auditor.py # 審計器記錄每次調(diào)用的完整軌跡 │ └── gate.py # AgentGate 核心類統(tǒng)一攔截入口這個結(jié)構(gòu)把工具注冊、策略判定、審計記錄、統(tǒng)一入口拆開方便后續(xù)擴展。我建議你也按這個思路組織代碼不要讓 Gate 變成一大坨邏輯堆在 Agent 的調(diào)用循環(huán)里。3. Gate 的核心設(shè)計原理3.1 三層檢查模型身份、權(quán)限、合法性我把 Gate 的檢查邏輯設(shè)計成三層也叫“三層防線”。每一層只負責(zé)一件事通過后進入下一層。這樣可以清晰地知道請求到底在哪一步被拒審計日志也能記錄得更有價值。第一層是身份層。它確認調(diào)用請求來自哪個 Agent。在實際系統(tǒng)中每次調(diào)用都會攜帶一個agent_idGate 會去身份注冊表里確認這個 Agent 是否存在、是否處于啟用狀態(tài)。身份層不解決“能不能干”的問題它只解決“你是誰”的問題。第二層是權(quán)限層。它根據(jù) Agent 的角色和工具聲明的權(quán)限級別判斷該 Agent 是否有權(quán)調(diào)用這個工具。這里會用到類似 RBAC 的角色判斷admin角色可以調(diào)用高權(quán)限工具readonly角色只能調(diào)用查詢類工具。權(quán)限層是 Gate 的核心大多數(shù)攔截也發(fā)生在這一層。第三層是合法性層。權(quán)限通過后再檢查參數(shù)是否合法。一個工具有它聲明的參數(shù)結(jié)構(gòu)比如send_email要求to是合法郵箱格式、subject不能為空。合法性檢查不僅是格式校驗還可以包含業(yè)務(wù)規(guī)則比如刪除操作要求附帶confirm_reason。三層檢查的順序是固定的先身份、再權(quán)限、后合法性。因為如果身份不對后面再檢查權(quán)限和參數(shù)都是白費如果權(quán)限不足參數(shù)是否合法已經(jīng)沒有意義。3.2 工具注冊與元數(shù)據(jù)聲明Gate 要判斷一個工具調(diào)用是否合法前提是它了解這個工具。所以所有 Agent 可調(diào)用的工具都必須先在“工具注冊表”中登記并且?guī)贤暾脑獢?shù)據(jù)。一個工具注冊項至少需要包含以下字段name工具唯一名稱模型調(diào)用時使用這個名字。description工具的功能描述給模型看讓它決定何時調(diào)用。risk_level風(fēng)險等級low、medium、high。allowed_roles允許調(diào)用該工具的角色列表。params_schema參數(shù)的結(jié)構(gòu)化描述用于合法性校驗。handler工具真正執(zhí)行的函數(shù)引用?？梢赃@樣理解工具注冊表是 Agent 的“API 文檔 權(quán)限清單”。模型只能看到已注冊工具的名字和描述Gate 也只能對已注冊工具做校驗。沒有注冊的工具模型即使“想”調(diào)用Gate 也會直接拒絕。3.3 風(fēng)險分級與審批策略不同工具的風(fēng)險差異非常大。查天氣和刪庫顯然不能走相同的檢查策略。所以我把審批策略和風(fēng)險等級綁定在一起低風(fēng)險low自動放行。只要身份、權(quán)限、合法性檢查通過直接調(diào)用。中風(fēng)險medium按參數(shù)條件自動放行否則進入人工審批。比如允許查詢最近 7 天數(shù)據(jù)超過 7 天則需要審批。高風(fēng)險high一律進入人工審批隊列或者根據(jù)業(yè)務(wù)規(guī)則直接拒絕。這種方式和代碼評審里的“合并門禁”很類似小改動自動合并大改動必須人工 review。它會明顯增加高風(fēng)險的調(diào)用延遲但這是合理的權(quán)衡因為高風(fēng)險操作本來就不應(yīng)該被模型“隨手”執(zhí)行。3.4 審計與可追溯審計不是在操作失敗后才需要的而是在每一次調(diào)用發(fā)生時就應(yīng)該記錄。Gate 里的審計器負責(zé)把每次調(diào)用的關(guān)鍵信息寫入日志或數(shù)據(jù)庫至少包含調(diào)用時間。Agent ID。工具名稱。入?yún)⒄舾凶侄蚊撁?。判定結(jié)果allow / reject / need_review。命中策略描述。調(diào)用鏈追蹤 ID。有了審計日志就可以回答幾個關(guān)鍵問題某個 Agent 在過去一周調(diào)用了哪些工具哪個調(diào)用被拒絕了被拒絕的請求發(fā)了多少次這些數(shù)據(jù)不僅是安全追溯的依據(jù)也是優(yōu)化權(quán)限策略的重要輸入。4. 完整實戰(zhàn)案例實現(xiàn)一個最小可用的 Agent Gate接下來我們進入實戰(zhàn)。我會從零構(gòu)建一個 Agent Gate Demo并用模擬的模型輸出演示完整的攔截流程。4.1 定義風(fēng)險等級與工具注冊表由于真實調(diào)用 LLM 需要成本和網(wǎng)絡(luò)依賴而且不同模型的工具調(diào)用格式不一致這里我使用一個內(nèi)置的工具調(diào)用序列來模擬模型返回。這樣能讓代碼專注于 Gate 本身也方便你直接運行驗證。先創(chuàng)建gate/registry.py定義風(fēng)險等級和工具數(shù)據(jù)結(jié)構(gòu)。# 文件路徑gate/registry.py from dataclasses import dataclass, field from enum import Enum from typing import Any, Callable, Dict, List class RiskLevel(Enum): LOW low MEDIUM medium HIGH high dataclass class ToolSpec: name: str description: str risk_level: RiskLevel allowed_roles: List[str] params_schema: Dict[str, Dict[str, Any]] handler: Callable[..., Any]ToolSpec描述了一個可調(diào)用工具的完整元數(shù)據(jù)。handler是真正執(zhí)行業(yè)務(wù)邏輯的函數(shù)。下面定義三個工具分別對應(yīng)低、中、高風(fēng)險。# 文件路徑gate/registry.py from datetime import datetime, timedelta def query_weather(city: str) - str: return f{city} 今天晴氣溫 18~25 攝氏度。 def query_order(start_date: str, end_date: str) - str: return f查詢訂單數(shù)據(jù){start_date} 至 {end_date}共 128 筆。 def delete_order(order_id: str) - str: return f訂單 {order_id} 已刪除模擬。 def build_registry(): return { query_weather: ToolSpec( namequery_weather, description查詢指定城市的天氣情況, risk_levelRiskLevel.LOW, allowed_roles[user, assistant, admin], params_schema{ city: {type: string, required: True, description: 城市名稱} }, handlerquery_weather, ), query_order: ToolSpec( namequery_order, description查詢指定日期范圍內(nèi)的訂單數(shù)據(jù), risk_levelRiskLevel.MEDIUM, allowed_roles[user, admin], params_schema{ start_date: {type: string, required: True, description: 開始日期如 2024-01-01}, end_date: {type: string, required: True, description: 結(jié)束日期如 2024-01-31}, }, handlerquery_order, ), delete_order: ToolSpec( namedelete_order, description刪除指定的訂單數(shù)據(jù), risk_levelRiskLevel.HIGH, allowed_roles[admin], params_schema{ order_id: {type: string, required: True, description: 訂單ID} }, handlerdelete_order, ), }這里有一個重要的設(shè)計點allowed_roles是工具和角色之間的權(quán)限綁定。比如query_weather允許所有角色調(diào)用delete_order只有admin角色能調(diào)用。模型并不感知權(quán)限策略它只負責(zé)生成工具調(diào)用權(quán)限判斷完全交給 Gate。4.2 實現(xiàn)策略引擎策略引擎負責(zé)把“三層檢查”落成可執(zhí)行的代碼。我把它拆成三個方法這樣每一層的邏輯都清晰獨立。# 文件路徑gate/policies.py from typing import Dict, Any from gate.registry import ToolSpec, RiskLevel class PolicyDecision: def __init__(self, allowed: bool, reason: str, need_review: bool False): self.allowed allowed self.reason reason self.need_review need_review def __repr__(self): status ALLOW if self.allowed else (REVIEW if self.need_review else REJECT) return fPolicyDecision {status}: {self.reason} class PolicyEngine: def __init__(self, registry: Dict[str, ToolSpec]): self.registry registry def check(self, agent_id: str, agent_role: str, tool_name: str, params: Dict[str, Any]) - PolicyDecision: if tool_name not in self.registry: return PolicyDecision(False, f工具 {tool_name} 未注冊) tool self.registry[tool_name] # 第一層身份檢查 if agent_id is None or agent_id.strip() : return PolicyDecision(False, 缺少調(diào)用方身份 agent_id) # 第二層權(quán)限檢查 if agent_role not in tool.allowed_roles: return PolicyDecision( False, f角色 {agent_role} 無權(quán)調(diào)用工具 {tool_name}允許角色: {tool.allowed_roles} ) # 第三層合法性檢查 schema tool.params_schema for param_name, rule in schema.items(): if rule.get(required, False) and (param_name not in params or params[param_name] in (None, )): return PolicyDecision(False, f參數(shù) {param_name} 不能為空) # 風(fēng)險分級策略 if tool.risk_level RiskLevel.LOW: return PolicyDecision(True, 低風(fēng)險工具自動放行) elif tool.risk_level RiskLevel.MEDIUM: if self._medium_risk_review(tool, params): return PolicyDecision(False, 中風(fēng)險工具需人工審批, need_reviewTrue) return PolicyDecision(True, 中風(fēng)險工具參數(shù)滿足自動放行條件) elif tool.risk_level RiskLevel.HIGH: return PolicyDecision(False, 高風(fēng)險工具一律進入人工審批, need_reviewTrue) return PolicyDecision(False, 未知風(fēng)險等級默認拒絕) def _medium_risk_review(self, tool: ToolSpec, params: Dict[str, Any]) - bool: # 示例查詢訂單超過 7 天日期范圍時進入人工審批 if tool.name query_order: try: from datetime import datetime start datetime.strptime(params.get(start_date), %Y-%m-%d) end datetime.strptime(params.get(end_date), %Y-%m-%d) return (end - start).days 7 except Exception: return True return FalsePolicyEngine.check是 Gate 的核心函數(shù)。你可以把它想象成一個保安先確認你是誰再看你有沒有權(quán)限進門最后檢查你帶進來的東西合不合規(guī)定而且對不同的“危險物品”執(zhí)行不同的檢查流程。這里需要解釋一個細節(jié)為什么高風(fēng)險工具直接返回need_reviewTrue而不是直接拒絕因為delete_order這類操作雖然危險但業(yè)務(wù)上是有合法使用場景的。我們需要做的不是“禁止”而是“受控”。直接拒絕會讓 Agent 的能力大打折扣而進入人工審批可以讓合法的高風(fēng)險操作安全地完成。4.3 審計器與 Gate 主類審計器負責(zé)記錄每次調(diào)用。為了演示方便我用一個簡單的內(nèi)存列表存儲日志生產(chǎn)環(huán)境建議替換為數(shù)據(jù)庫或消息隊列。# 文件路徑gate/auditor.py from datetime import datetime from typing import Dict, Any, List class Auditor: def __init__(self): self.logs: List[Dict[str, Any]] [] def record( self, agent_id: str, agent_role: str, tool_name: str, params: Dict[str, Any], decision: Any, ): log_entry { time: datetime.now().isoformat(), agent_id: agent_id, agent_role: agent_role, tool: tool_name, params: params, decision: { allowed: decision.allowed, need_review: decision.need_review, reason: decision.reason, }, } self.logs.append(log_entry) return log_entry def show_logs(self): for log in self.logs: status ALLOW if log[decision][allowed] else REVIEW if not log[decision][allowed] and not log[decision][need_review]: status REJECT print( f[{log[time]}] agent{log[agent_id]} role{log[agent_role]} ftool{log[tool]} status{status} reason{log[decision][reason]} )接下來是統(tǒng)一入口AgentGate。它把策略引擎、審計器、工具執(zhí)行包裝起來對外只暴露一個call_tool方法。# 文件路徑gate/gate.py from typing import Dict, Any from gate.registry import ToolSpec, build_registry from gate.policies import PolicyEngine, PolicyDecision from gate.auditor import Auditor class AgentGate: def __init__(self): self.registry build_registry() self.policy PolicyEngine(self.registry) self.auditor Auditor() # 模擬人工審批隊列 self.review_queue [] def call_tool( self, agent_id: str, agent_role: str, tool_name: str, params: Dict[str, Any], ) - Dict[str, Any]: # 1. 策略檢查 decision self.policy.check(agent_id, agent_role, tool_name, params) # 2. 審計記錄 self.auditor.record(agent_id, agent_role, tool_name, params, decision) # 3. 根據(jù)決策執(zhí)行或攔截 if decision.allowed: tool: ToolSpec self.registry[tool_name] try: result tool.handler(**params) return {status: success, result: result, decision: decision.reason} except Exception as e: return {status: error, error: str(e), decision: decision.reason} elif decision.need_review: review_ticket { agent_id: agent_id, agent_role: agent_role, tool: tool_name, params: params, reason: decision.reason, } self.review_queue.append(review_ticket) return { status: review, message: 該操作已進入人工審批隊列, review_id: len(self.review_queue) - 1, reason: decision.reason, } else: return {status: rejected, message: decision.reason, decision: decision.reason}call_tool的邏輯非常簡單清楚先判斷再記錄最后執(zhí)行。所有工具調(diào)用都必須走這一個方法不允許 Agent 繞過它直接調(diào)用handler。這一點在集成到真實系統(tǒng)時也要注意Gate 必須是工具調(diào)用的唯一出入口否則規(guī)則就會被輕松繞過。4.4 編寫主程序模擬 Agent 調(diào)用現(xiàn)在編寫main.py模擬一個user角色和一個admin角色分別發(fā)起工具調(diào)用。這里我使用固定的調(diào)用序列模擬模型輸出目的是演示不同場景下 Gate 的判定結(jié)果。# 文件路徑main.py from gate.gate import AgentGate # 創(chuàng)建 Gate 實例 gate AgentGate() def simulate_agent_call(agent_id: str, agent_role: str, tool_name: str, params: dict): print(f\n Agent({agent_id}, role{agent_role}) 發(fā)起調(diào)用: {tool_name}({params})) result gate.call_tool(agent_id, agent_role, tool_name, params) print( 返回結(jié)果:, result) if __name__ __main__: # 場景1低風(fēng)險工具普通用戶直接放行 simulate_agent_call(agent_user_01, user, query_weather, {city: 上海}) # 場景2中風(fēng)險工具查詢范圍超過7天進入人工審批 simulate_agent_call(agent_user_01, user, query_order, { start_date: 2024-01-01, end_date: 2024-01-20, }) # 場景3中風(fēng)險工具查詢范圍在7天內(nèi)自動放行 simulate_agent_call(agent_user_01, user, query_order, { start_date: 2024-01-01, end_date: 2024-01-05, }) # 場景4高風(fēng)險工具user 角色無權(quán)調(diào)用直接拒絕 simulate_agent_call(agent_user_01, user, delete_order, {order_id: ORD-10086}) # 場景5高風(fēng)險工具admin 角色調(diào)用進入人工審批 simulate_agent_call(agent_admin_01, admin, delete_order, {order_id: ORD-10086}) # 場景6未注冊工具 simulate_agent_call(agent_user_01, user, drop_database, {db: prod}) print(\n 審計日志 ) gate.auditor.show_logs() print(\n 人工審批隊列 ) for ticket in gate.review_queue: print(ticket)4.5 運行與驗證在項目根目錄執(zhí)行python main.py預(yù)期輸出如下時間部分會有所不同 Agent(agent_user_01, roleuser) 發(fā)起調(diào)用: query_weather({city: 上海}) 返回結(jié)果: {status: success, result: 上海 今天晴氣溫 18~25 攝氏度。, decision: 低風(fēng)險工具自動放行} Agent(agent_user_01, roleuser) 發(fā)起調(diào)用: query_order({start_date: 2024-01-01, end_date: 2024-01-20}) 返回結(jié)果: {status: review, message: 該操作已進入人工審批隊列, review_id: 0, reason: 中風(fēng)險工具需人工審批} Agent(agent_user_01, roleuser) 發(fā)起調(diào)用: query_order({start_date: 2024-01-01, end_date: 2024-01-05}) 返回結(jié)果: {status: success, result: 查詢訂單數(shù)據(jù)2024-01-01 至 2024-01-05共 128 筆。, decision: 中風(fēng)險工具參數(shù)滿足自動放行條件} Agent(agent_user_01, roleuser) 發(fā)起調(diào)用: delete_order({order_id: ORD-10086}) 返回結(jié)果: {status: rejected, message: 角色 user 無權(quán)調(diào)用工具 delete_order允許角色: [\admin\], decision: 角色 user 無權(quán)調(diào)用工具 delete_order允許角色: [\admin\]} Agent(agent_admin_01, roleadmin) 發(fā)起調(diào)用: delete_order({order_id: ORD-10086}) 返回結(jié)果: {status: review, message: 該操作已進入人工審批隊列, review_id: 1, reason: 高風(fēng)險工具一律進入人工審批} Agent(agent_user_01, roleuser) 發(fā)起調(diào)用: drop_database({db: prod}) 返回結(jié)果: {status: rejected, message: 工具 drop_database 未注冊, decision: 工具 drop_database 未注冊} 審計日志 [2025-01-10 10:24:31.123456] agentagent_user_01 roleuser toolquery_weather statusALLOW reason低風(fēng)險工具自動放行 [2025-01-10 10:24:31.123456] agentagent_user_01 roleuser toolquery_order statusREVIEW reason中風(fēng)險工具需人工審批 [2025-01-10 10:24:31.123456] agentagent_user_01 roleuser toolquery_order statusALLOW reason中風(fēng)險工具參數(shù)滿足自動放行條件 [2025-01-10 10:24:31.123456] agentagent_user_01 roleuser tooldelete_order statusREJECT reason角色 user 無權(quán)調(diào)用工具 delete_order允許角色: [admin] [2025-01-10 10:24:31.123456] agentagent_admin_01 roleadmin tooldelete_order statusREVIEW reason高風(fēng)險工具一律進入人工審批 [2025-01-10 10:24:31.123456] agentagent_user_01 roleuser tooldrop_database statusREJECT reason工具 drop_database 未注冊 人工審批隊列 {agent_id: agent_user_01, agent_role: user, tool: query_order, params: {start_date: 2024-01-01, end_date: 2024-01-20}, reason: 中風(fēng)險工具需人工審批} {agent_id: agent_admin_01, agent_role: admin, tool: delete_order, params: {order_id: ORD-10086}, reason: 高風(fēng)險工具一律進入人工審批}4.6 結(jié)果說明從輸出結(jié)果可以看出幾件事低風(fēng)險操作沒有額外負擔(dān)直接執(zhí)行用戶體驗不受影響。中風(fēng)險操作只有在超出合理范圍時才進入審批業(yè)務(wù)靈活性保留得很好。高風(fēng)險操作不允許普通角色調(diào)用管理員也需要額外確認。未注冊工具直接拒絕防止模型“發(fā)明”出我們不希望它調(diào)用的工具。每次判定都有審計記錄事后可以完整回溯。如果你已經(jīng)有一個成熟的 Agent 應(yīng)用接入這套 Gate 的成本其實不高把原來直接調(diào)用tool.handler(**params)的地方全部改成gate.call_tool(...)即可。如果你的工具數(shù)量很大可以維護一個注冊表模塊從配置中心加載這樣新增工具時不需要改動 Gate 代碼。5. 常見問題與排查思路在實際編碼和落地過程中我遇到過不少問題這里整理成表格方便快速排查。問題現(xiàn)象常見原因解決思路所有工具調(diào)用都被拒絕身份參數(shù)agent_id為空或allowed_roles配置有誤檢查調(diào)用方是否傳了agent_id確認工具的角色白名單中風(fēng)險工具每次都進入審批params_schema里日期格式與解析代碼不一致統(tǒng)一日期格式建議使用 ISO 8601 并增加格式校驗?zāi)Ｐ汀鞍l(fā)明”了工具名系統(tǒng)提示詞里工具列表不完整或模型幻覺在系統(tǒng)提示詞里明確“只能調(diào)用以下工具”Gate 層拒絕未注冊工具高風(fēng)險操作被直接執(zhí)行Gate 被繞過Agent 直接調(diào)用了 handler檢查代碼里是否還存在直接調(diào)用 handler 的路徑確保所有調(diào)用走call_tool審計日志缺少關(guān)鍵信息審計器沒有記錄入?yún)⒒驔Q策原因為每條日志補充完整字段敏感參數(shù)先脫敏再記錄多個 Agent 共用一個白名單角色粒度太粗權(quán)限被放大按 Agent 粒度配置額外限制結(jié)合工具維度做更細的授權(quán)這里我想重點展開兩個排查案例。第一個案例是“審計日志里只有成功記錄”。我某次在排查一個 Agent 的異常行為時發(fā)現(xiàn)審計庫里只有ALLOW的記錄完全沒有被拒絕的調(diào)用。原因是當時的實現(xiàn)只在執(zhí)行成功后寫日志被攔截的請求在else分支直接return了沒有走審計器。這提醒了我一個原則審計必須發(fā)生在所有分支之前而不是執(zhí)行成功之后。上面示例代碼里審計記錄在策略判斷之后立即執(zhí)行就是這樣處理的。第二個案例是“工具權(quán)限白名單寫死在業(yè)務(wù)代碼里”。一開始我把allowed_roles寫在各個工具函數(shù)內(nèi)部導(dǎo)致后來調(diào)整權(quán)限需要改很多文件。后來我改成把工具注冊表抽成獨立模塊用配置驅(qū)動這樣權(quán)限調(diào)整只改一個地方。開發(fā)時你可能覺得寫死更方便但上線后你會發(fā)現(xiàn)Agent 的權(quán)限策略變更頻率遠比你想象得高。6. 最佳實踐與工程建議6.1 權(quán)限設(shè)計最小權(quán)限是底線給 Agent 分配角色時從最小權(quán)限開始不要一上來就給admin。很多 Agent 框架默認讓 Agent 使用當前登錄用戶的身份甚至使用一個超級管理員身份這是很危險的做法。更合理的方案是每個 Agent 有獨立身份權(quán)限按業(yè)務(wù)需要單獨分配。比如一個只負責(zé)查天氣的助手它的角色權(quán)限應(yīng)該只有query_weather連query_order都不應(yīng)該有。如果你的系統(tǒng)支持還可以引入資源級權(quán)限。比如同樣是query_orderAgent A 只能查詢?nèi)A東區(qū)數(shù)據(jù)Agent B 能查詢?nèi)珖鴶?shù)據(jù)。這類細粒度控制在 Gate 的合法性檢查層實現(xiàn)。6.2 參數(shù)校驗不要只做格式校驗合法性檢查不能只驗證“參數(shù)類型對不對”還要驗證“參數(shù)值合不合理”。我見過一個刪除接口模型傳入的order_id是空字符串雖然格式上不報錯但到了數(shù)據(jù)庫層就出問題。更好的做法是對關(guān)鍵參數(shù)做顯式校驗比如正則匹配、枚舉值白名單、業(yè)務(wù)規(guī)則判斷。import re def validate_order_id(order_id: str) - bool: return bool(re.match(r^ORD-\d{4,}$, order_id))這類校驗函數(shù)可以注冊到ToolSpec里作為params_schema之外的增強校驗邏輯。如果讀者集成到 Spring AI 等框架中可以在工具調(diào)用前增加一個自定義MethodInterceptor或 AOP 切面完成同樣的工作。6.3 人工審批要有超時和告警進入審批隊列的操作如果一直沒人處理Agent 任務(wù)就會卡住。所以審批流需要設(shè)計超時策略超過 5 分鐘未審批自動拒絕并通知 Agent。審批人可以通過 IM、郵件接收待辦提醒。審批記錄要保留操作人信息方便事后追責(zé)。審批不是簡單的“同意/拒絕”還應(yīng)該支持“修改參數(shù)后同意”。比如模型要刪除訂單ORD-10086審批人覺得可以刪但需要先備份這時可以在審批流里附加一個前置操作步驟。6.4 審計完整、脫敏、可檢索審計日志的建議包括以下幾點每條日志附帶trace_id串聯(lián)起整個 Agent 任務(wù)。敏感參數(shù)如手機號、身份證號要脫敏后再記錄。日志保存周期要符合公司的安全合規(guī)要求。不要把審計日志和應(yīng)用業(yè)務(wù)日志混在一起建議使用獨立存儲或獨立表。有了審計數(shù)據(jù)你可以定期分析哪些工具被高頻調(diào)用、哪些操作經(jīng)常被審批拒絕、哪些 Agent 的調(diào)用行為異常。這些都是優(yōu)化權(quán)限策略的重要依據(jù)。6.5 測試策略你的測試要覆蓋攔截分支很多團隊測試 Agent 時只驗證“工具調(diào)用成功”的路徑Gate 的攔截路徑完全沒有覆蓋測試。這會導(dǎo)致權(quán)限配置變更后出現(xiàn)意外放行或誤攔截。我建議至少準備以下幾類測試用例低風(fēng)險工具 合法角色 合法參數(shù) 放行。低風(fēng)險工具 非法角色 拒絕。中風(fēng)險工具 超出范圍參數(shù) 進入審批。高風(fēng)險工具 管理員 進入審批。高風(fēng)險工具 普通用戶 拒絕。未注冊工具 拒絕。缺少必填參數(shù) 拒絕。把這些用例固化成單元測試或集成測試后續(xù)改動權(quán)限策略時有回歸保障。6.6 生產(chǎn)環(huán)境注意事項Gate 服務(wù)本身要考慮高可用建議獨立部署或做成中間件插件避免成為單點。策略配置要支持熱更新可以在配置中心中維護。對 Gate 自身的性能和延遲要做好監(jiān)控不要讓每層校驗都變成一次數(shù)據(jù)庫查詢。對于高風(fēng)險操作建議在工具執(zhí)行時使用一個獨立的受限賬號不要使用 Agent 的高權(quán)限賬號直接操作。如果 Agent 需要操作真實生產(chǎn)系統(tǒng)務(wù)必先在小流量、測試環(huán)境驗證策略的完整性和穩(wěn)定性。7. 總結(jié)與學(xué)習(xí)路線這篇文章從一個很直接的問題出發(fā)Agent 開始“動手做事”之后我們?nèi)绾伪ＷC它做的事是安全、合理、被授權(quán)的我給出的方案是構(gòu)建一個 Gate在模型輸出與工具執(zhí)行之間增加一個受控的檢查層用身份、權(quán)限、合法性三層檢查來攔截風(fēng)險并用風(fēng)險分級和人工審批來平衡安全與靈活性。示例項目雖然短小但已經(jīng)包含了一個完整 Agent Gate 的四個核心模塊工具注冊表、策略引擎、審計器、統(tǒng)一入口。它可以直接復(fù)制運行也可以作為你接入真實項目的起點。如果你接下來想深入建議按這條路線繼續(xù)學(xué)習(xí)接入真實模型把示例中的模擬調(diào)用換成 OpenAI Function Calling 或 Claude Tool Use 的真實響應(yīng)讓模型輸出直接經(jīng)過 Gate。引入 Spring AI 等框架如果你用 Java 技術(shù)?？梢匝芯?Spring AI 的ToolCallingManager和自定義攔截器。引入配置中心把工具注冊表和策略配置遷移到 Nacos、Apollo 等配置中心實現(xiàn)動態(tài)策略。引入可觀測體系為 Gate 增加指標埋點如調(diào)用次數(shù)、攔截率、審批耗時完善告警。最后給你一個實操建議不要等到 Agent 規(guī)模大了才考慮安全。先從最小權(quán)限和審計做起哪怕只有一個 Agent、三個工具也要讓每次調(diào)用都經(jīng)過 Gate。這樣等技術(shù)方案成熟時你的系統(tǒng)已經(jīng)具備應(yīng)對復(fù)雜場景的基礎(chǔ)能力了。如果你在實踐中有更好的 Gate 設(shè)計思路歡迎在評論區(qū)交流。