Agent Governance Toolkit 10 分钟快速入门：从零构建受治理 AI 智能体

Agent Governance Toolkit 10 分钟快速入门：从零构建受治理 AI 智能体

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit

本文是 Agent Governance Toolkit 的繁體中文快速入門指南。你將在 10 分鐘內完成從安裝、驗證到寫出第一個「受治理智能體」的完整流程，學會如何讓每一次工具呼叫都在執行前通過策略引擎檢查，並了解如何將治理能力接入 LangChain、CrewAI 等主流智能體框架，以及如何用內建 CLI 核對 OWASP Agentic 安全覆蓋率。讀完本文，你將具備在 Python、TypeScript/Node.js 與 .NET 三種技術棧下部署治理層的實戰能力。

架構概述：治理層如何在執行前攔截每一個智能體操作

Agent Governance Toolkit 的核心思路非常直接：在智能體真正執行任何操作（工具呼叫、模型呼叫、輸入輸出）之前，先讓一個獨立的治理層做策略判定。只有判定為允許（Allowed）的操作才會進入執行階段，被攔截（Blocked）的操作則直接觸發安全封鎖，且無論允許還是封鎖，最終都會寫入稽核日誌並流向 OTEL / 結構化日誌：

這條攔截鏈在倉庫中的落地實現可以參見 AgentControl 與 HostSession 的封裝：AgentControl負責把 ACS（Agent Control Specification）清單綁定到原生運行時，HostSession則為每個智能體會話提供同步的攔截點調用介面，例如pre_tool_call。後文我們會沿著這條鏈路逐層展開。

前置條件：Python 3.10+ / Node.js 18+ / .NET 8.0+（任選其一或多個）。

1. 安裝治理工具包

Python 最簡單的安裝方式是一次裝入完整工具鏈：

pip install agent-governance-toolkit[full]

也可以按需安裝單獨的套件，每個套件對應一類治理能力：

pip install agent-os-kernel # 策略執行 + 框架整合 pip install agentmesh-platform # 零信任身份 + 信任卡 pip install agent-governance-toolkit # OWASP ASI 驗證 + 完整性 CLI pip install agent-sre # SLO、錯誤預算、混沌測試 pip install agentmesh-runtime # 執行期監督 + 權限環 pip install agentmesh-marketplace # 外掛生命週期管理 pip install agentmesh-lightning # 強化學習訓練治理

從倉庫中的安裝校驗腳本 scripts/check_gov.py 可以印證上述包名與模組的對應關係：agent-os-kernel提供agent_os模組、agentmesh-platform提供agentmesh模組、agent-governance-toolkit提供agent_compliance模組、agent-sre提供agent_sre模組——這正是「策略執行」「零信任身份」「OWASP 驗證」「SRE 可觀測性」四條能力線的分工。

TypeScript / Node.js

npm install @microsoft/agent-governance-sdk

對應的 TypeScript SDK 原始碼與測試位於 agent-governance-typescript，覆蓋策略評估、身份、稽核、MCP、沙箱等模組。

.NET

dotnet add package Microsoft.AgentGovernance

如果您目前不在包含.csproj的目錄中，請明確傳入專案路徑：

dotnet add YourApp.csproj package Microsoft.AgentGovernance

在 Visual Studio 的 Package Manager Console 中，請先在Default project下拉選單中選取目標專案，再執行：

Install-Package Microsoft.AgentGovernance

.NET 套件的原始碼與範例位於 agent-governance-dotnet，包含 ASP.NET Core 中介軟體範例 examples/AspNetMiddleware 與快速入門 examples/Quickstart。

2. 驗證安裝

安裝完成後，先執行倉庫內建的安裝校驗腳本，確認核心包與關鍵依賴均可導入：

python scripts/check_gov.py

從 check_gov.py 的實現可以看到，它逐一嘗試導入agent_os、agentmesh、agent_compliance、agent_sre，以及安全關鍵依賴cryptography、pynacl，並檢查agent-governanceCLI 的 verify 子命令是否可用，最後輸出READY或INCOMPLETE狀態。若有缺失，腳本會提示pip install agent-governance-toolkit[full]補齊。

也可以直接使用治理 CLI：

agent-governance verify agent-governance verify --badge

verify子命令的底層實現在 agent-compliance CLI：GovernanceVerifier.verify()會生成一份「證明（attestation）」，並根據參數決定輸出 JSON、Markdown 徽章或摘要。

3. 您的第一個受治理智能體

建立一個名為governed_agent.py的檔案：

from agent_control_specification import AgentControl, HostSession runtime = AgentControl.from_path("policies/manifest.yaml") session = HostSession( runtime, agent_id="quickstart-agent", session_id="quickstart-session", ) result = session.pre_tool_call( tool_name="delete_file", args={"path": "/etc/passwd"}, ) print(result.verdict) print(result.reason_code)

執行：

python governed_agent.py

當策略清單policies/manifest.yaml中禁止刪除/etc/passwd這類敏感路徑時，result.verdict將是DENY，並帶有分類化的reason_code，程式無需真正呼叫任何工具即可完成一次安全攔截。

深入理解這段程式背後的機制

• AgentControl.from_path：從 _orchestration.py 的實現 可以看到，它把 manifest 路徑交給NativeRuntimeClient.from_path構建無狀態原生運行時。除了from_path，還提供from_url（可選配 sha256 校驗）、from_native與from_manifest_chain（多清單合併），滿足從遠端拉取策略或分層疊加策略的場景。
• HostSession：它將AgentControl綁定到一個 SnapshotBuilder。SnapshotBuilder持有每次評估所需的身份資訊（agent_id、session_id、tenant_id）與預算計數器（tool_call_count、token_count、elapsed_seconds、cost_usd），並通過record_tool_call、record_tokens、record_cost等累加式方法推進計數，供預算類策略讀取。
• pre_tool_call：對應 ACS 的pre_tool_call干預點（intervention point）。從 _host.py 可以看到，它把工具名與參數包裝為tool_call={"name": ..., "args": ..., "id": ...}後送入評估，返回InterventionPointResult，呼叫方直接讀取result.verdict.decision即可。
• EnforcementMode：HostSession預設以EnforcementMode.ENFORCE運行；若只需試探策略效果而不真正封鎖，可改為evaluate_only模式。
• 審批超時：當判定需要人工審批時，HostSession使用預設的 DEFAULT_APPROVAL_TIMEOUT_SECONDS = 300 秒 作為等待上界，超時預設 fail-closed（判定為拒絕），避免無界等待變成隱性的放行漏洞。

策略清單（manifest）長什麼樣

policies/manifest.yaml是治理的核心配置。以倉庫的冒煙測試清單 policy-engine/tests/fixtures/smoke/manifest.yaml 為例，它包含三大部分：

• policies：聲明 Rego 策略的類型、bundle 路徑與查詢入口；
• intervention_points：把策略綁定到具體干預點，如agent_startup、input、pre_model_call、pre_tool_call、post_tool_call、output、agent_shutdown，每個干預點都指定policy_target（策略評估的 JSON 路徑，例如$.tool_call.args）與對應的policy.query；
• tools：聲明工具目錄，每個工具可帶clearance（所需權限）與security_labels（如benign/sensitive），供策略按敏感度分級治理。

處理一次拒絕

在生產代碼中，攔截不應只靠print。英文版快速入門 docs/quickstart.md 展示了標準處理方式——先檢查判定是否允許，不允許則轉為結構化異常並讀取稽核記錄：

if not evaluation.verdict.decision.permits: error = PolicyViolationError.from_evaluation_result(evaluation) print(str(error)) print(error.evaluation_result.audit_record())

公開異常文本經過淨化處理；可信代碼可透過附帶的PolicyEvaluation獲取結構化稽核與分發所需資訊。完整的拒絕處理範例也可參見 control-plane 範例 basic_usage.py。

4. 包裝現有框架

工具包與所有主要智能體框架整合，安裝對應的轉接器即可將治理層掛進既有框架：

pip install agentmesh-langchain # LangChain 轉接器 pip install llamaindex-agentmesh # LlamaIndex 轉接器 pip install crewai-agentmesh # CrewAI 轉接器

支援的框架：LangChain、OpenAI Agents SDK、AutoGen、CrewAI、Google ADK、Semantic Kernel、LlamaIndex、Anthropic、Mistral、Gemini等。從倉庫的框架轉接測試目錄（如 agt-policies 的場景測試）可以看到這些轉接器均以「同一份原生運行時 + 框架特定攔截點」的方式工作。

包裝方式非常簡潔。以 LangChain 為例，將上一步的runtime直接傳給框架內核即可：

from agent_os.integrations.langchain_adapter import LangChainKernel kernel = LangChainKernel(runtime=runtime)

注意一個設計原則：策略定義、被封鎖的內容、工具目錄、預算、轉換與審批都應該放在 manifest 中，而不是塞進轉接器的構造參數。這樣無論底層換成哪個框架，治理規則都保持單一來源。

5. 檢查 OWASP ASI 2026 覆蓋率

部署完成後，用同一條 CLI 驗證您的部署是否涵蓋 OWASP 智能體安全威脅：

agent-governance verify agent-governance verify --json agent-governance verify --badge

• 不加參數：輸出人類可讀的摘要，並以退出碼（0 = 通過，1 = 未通過）標示結果；
• --json：輸出 JSON 格式的證明文件（attestation），便於接入 CI 或稽核管線；
• --badge：只輸出 Markdown 徽章，可直接嵌入 README 展示治理狀態。

關於威脅覆蓋的完整映射，可參閱 OWASP Agentic Top 10 架構映射。

後續步驟

至此，你已經完成從安裝、驗證、寫出第一個受治理智能體，到接入主流框架、核對 OWASP 覆蓋率的完整閉環。下一步可以嘗試：用AgentControl.from_manifest_chain疊加多層策略、用SnapshotBuilder.record_cost啟動成本預算治理，或參考 docs/tutorials/55-agent-control-specification.md 深入 Agent Control Specification 的干預點模型，把治理從「攔截工具呼叫」擴展到「輸入淨化、輸出審查、生命週期管理」的全覆蓋。

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit