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