Citadel AGT 集成架构Foundry Citadel 四层治理与 Agent Governance Toolkit 的边界协作实战指南【免费下载链接】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 ToolkitAGT与微软 Foundry Citadel 平台集成架构的技术指南。Citadel 提供面向基础设施边界网关、身份、安全、可观测性的 AI 治理分层架构而 AGT 负责代理运行时内逐动作、逐消息的细粒度策略执行两者互补而非竞争。读完本文你将掌握两者在四层架构中的职责切分、Policy Bundle 与 Access Contract 的绑定机制、治理事件导出到 Azure Event Hub / Application Insights 的完整数据流以及 APIM 网关侧治理元数据的透传与关联实现并可直接运行仓库中的端到端示例验证整套流程。定位两种互补的强制边界Citadel 与 AGT 治理的是不同的强制边界两者是互补关系而非竞争关系。Citadel 站在基础设施外沿gateway perimeterAGT 站在代理运行时内部agent runtime。二者对同一代理动作的治理粒度、身份模型、审计目标各不相同关注点Citadel网关AGT代理运行时治理对象基础设施边界处的模型/工具/代理访问单个代理动作、工具调用、代理间消息强制点APIM 网关集中式代理运行时 sidecar / 库本地延迟模型经过网关的一次网络跳转进程内亚毫秒级评估策略粒度粗粒度限流、内容过滤、配额、JWT 校验细粒度逐动作 allow/deny、能力模型、调用方限制身份模型Entra ID / 订阅密钥Ed25519 / SPIFFE 密码学身份审计目标Event Hub / App Insights / Log Analytics哈希链审计日志可导出至 Azure Monitor这一分工的核心判断依据是网关无法理解代理的意图与内部状态而运行时无法替代网关的容量与合规边界。因此合理的设计是让两者各守边界、通过协议与元数据协作这正是本文后续各节展开的内容。AGT 如何映射到 Citadel 的四层AGT 并不局限于 Citadel 的某一层而是横跨整个架构在每一层都有对应的协作点┌─────────────────────────────────────────────────────────────────┐ │ Foundry Citadel Platform │ │ │ │ Layer 4: Security Fabric (Defender, Purview, Entra) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ AGT trust scores surface as risk labels in Defender │ │ │ │ AGT data_classification aligns with Purview labels │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Layer 3: Agent Identity (Agent 365 / Entra) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ AGT agent identities federate with Entra agent IDs │ │ │ │ Entra enterprise identity, AGT runtime credentials │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Layer 2: AI Control Plane (Foundry Control Plane) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ AGT exports governance evidence and traces │ │ │ │ Policy decisions enrich Foundry/OTEL traces │ │ │ │ Fleet-wide compliance visibility via Azure Monitor │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Layer 1: Governance Hub (APIM Gateway) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Access Contracts reference AGT policy bundles │ │ │ │ AGT metadata headers pass through APIM for correlation │ │ │ │ Gateway coarse rules, AGT action-level rules │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘Layer 1Governance HubAPIM 网关Citadel 的 APIM 网关强制基础设施级控制代理可以访问哪些模型、以什么速率、经过哪些内容安全过滤器。AGT 通过Access Contract 策略包绑定Access Contract policy bundle binding接入当 Citadel Access Contract 部署代理环境时它引用一个 AGT 策略包的 ID/版本代理运行时在启动时加载该策略包由 PolicyBundleResolver 负责解析详见下文Policy Bundle Binding一节。策略优先级网关规则限流、内容过滤器、JWT首先在 APIM 层强制AGT 的动作级策略其次在代理运行时内强制。两层都必须通过动作才能继续执行。Layer 2AI Control PlaneFoundry 控制平面AGT 在 Layer 2 的核心贡献是治理证据与追踪增强。CitadelAuditExporter 将策略决策、信任分变化、动作拦截事件发送到 Azure Event Hub 和 Application Insights。这些事件携带关联 IDcorrelation ID把 AGT 决策与 APIM 请求追踪、Foundry 执行追踪串联起来从而支撑统一的可观测性仪表盘。从源码看导出器通过CorrelationContext数据结构携带apim_request_id、foundry_trace_id、agt_decision_id、session_id四类 ID见 citadel_exporter.pyApp Insights 侧则以agt.*/citadel.*前缀的 span attributes 写入确保跨系统关联。Layer 3Agent Identity代理身份Entra ID / Agent 365 仍是企业级代理身份与生命周期管理的权威来源AGT 的 Ed25519/SPIFFE 身份仍是运行时密码学凭据的权威来源。集成方式是联邦federation而非替换replacementAGT 信任分0-1000作为遥测中的风险标签risk label呈现而不是作为 Entra 的主元数据。EntraIdentityBridge专门负责这种映射见下文Entra 身份联邦一节。Layer 4Security Fabric安全织网AGT 策略上的data_classification标签与 Purview 敏感度标签对齐AGT 信任分可作为 Defender for AI 中的风险信号。该集成主要通过遥测管道Layer 2 导出实现而非直接 API 集成。数据流Agent Runtime Citadel Gateway Azure Monitor ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ │ │ │ │ │ │ Agent Code │ LLM │ APIM Gateway │ │ App Insights│ │ ┌────────────┐ │ request │ ┌────────────┐ │ │ │ │ │ AGT Policy ├──┼──────────►│ │ Rate Limit ├──┼────►LLM │ Event Hub │ │ │ Engine │ │ │ │ Content │ │ │ │ │ │ │ │ │ │ JWT Auth │ │ │ Log │ │ │ Decision: │ │ │ └────────────┘ │ │ Analytics │ │ │ allow/deny │ │ │ │ │ │ │ └─────┬──────┘ │ └──────────────────┘ └──────┬───────┘ │ │ │ │ │ ┌─────▼──────┐ │ ┌──────────────────┐ │ │ │ Citadel ├──┼──────────►│ Event Hub / │───────────────┘ │ │ Audit │ │ events │ App Insights │ │ │ Exporter │ │ └──────────────────┘ │ └────────────┘ │ └──────────────────┘一次完整请求的治理闭环包含以下 5 步代理动作触发 AGT 策略评估进程内、亚毫秒级。若允许请求通过 Citadel APIM 网关。APIM 强制网关级策略限流、内容过滤器、JWT。AGT 审计导出器将治理事件发送到 Azure Event Hub / App Insights。事件携带关联 ID将 AGT 决策与 APIM 请求追踪串联。其中第 4 步的实现细节值得展开CitadelAuditExportercitadel_exporter.py支持批量缓冲、异步 flush 与优雅降级——事件先进入本地缓冲区达到batch_size默认 50或flush_interval_seconds默认 10 秒后自动刷出发送失败的事件进入_failed_buffer待重试不会丢失。from_env()工厂方法从环境变量读取全部配置见 citadel_exporter.py环境变量作用默认值CITADEL_EVENTHUB_CONNECTION_STRINGEvent Hub 连接串空未配置则本地记录CITADEL_APPINSIGHTS_CONNECTION_STRINGApp Insights 连接串空CITADEL_EVENTHUB_NAMEEvent Hub 名称agt-governance-eventsCITADEL_EXPORT_BATCH_SIZE批量刷出阈值50CITADEL_EXPORT_FLUSH_INTERVAL最大刷出间隔秒10导出器定义了 5 类治理事件GovernanceEventTypepolicy_decision、policy_violation、trust_score_change、action_intercepted、bundle_loaded每类事件还携带hash_chain_prev/hash_chain_current字段把 AGT 哈希链审计的防篡改证据一并上送见 citadel_exporter.py。Policy Bundle Binding策略包绑定Citadel Access Contract 使用.bicepparam文件声明代理环境可以访问哪些资源。AGT 通过追加一个策略包引用来扩展该声明// In the Access Contract .bicepparam file param agtPolicyBundle object { bundleId: customer-support-v2 version: 1.3.0 source: https://vault.azure.net/secrets/agt-policy-bundle }在部署时策略包被拉取并注入代理环境AGT 运行时在启动时通过PolicyBundleResolver加载它。仓库中的完整示例见 examples/citadel-governed-agent/sample-access-contract/main.bicepparam它给出了三个取值来源的完整注释param agtPolicyBundle { bundleId: customer-support-v2 version: 1.3.0 source: keyvault // keyvault | file | url secretName: agt-policy-bundle-customer-support // For file source: filePath: ./policies/agent-policy.yaml // For url source: url: https://policy-store.example.com/bundles/customer-support-v2 }PolicyBundleResolver 的三种来源从源码看PolicyBundleResolver 支持三种加载来源并带有内存缓存_cache按bundle_id去重本地文件fileresolve_from_file()使用 PyYAML 解析 YAML 策略文件适合开发调试Azure Key Vaultkeyvaultresolve_from_keyvault()通过DefaultAzureCredentialSecretClient读取 JSON 序列化的策略包适合生产环境需要安装azure-keyvault-secrets azure-identityURLurlresolve_from_url()支持 JSON 或 YAML 两种格式适合集中式策略管理。resolve()方法是入口见 policy_bundle.py它从 Access Contract 配置中读取agtPolicyBundle参数根据source字段分发到对应加载器并先查缓存。若契约参数缺失或来源未知会抛出ValueError保证配置错误在启动期即被暴露。PolicyBundle 与契约校验加载后的策略包被建模为PolicyBundle数据类关键字段包括bundle_id、version、data_classification、allowed_actions、blocked_actions、rate_limits、requires_justification、min_trust_score、audit_config并自动计算content_hash对原始配置做 sort_keys 后的 SHA-256见 policy_bundle.py用于完整性校验。validate_against_contract()方法还负责反向校验AGT 策略约束不能超出契约允许范围例如 AGT 限流不应超过 Citadel 配额ID/版本不匹配会返回警告。配套的策略包文件 examples/citadel-governed-agent/policies/agent-policy.yaml 展示了完整的字段语义policy: name: customer-support-policy version: 1.3.0 data_classification: confidential # 与 Citadel/Purview 标签对齐 allowed_actions: - query_customer_database - search_knowledge_base - send_email - create_ticket - escalate_to_human blocked_actions: - delete_customer_record - modify_billing - access_internal_systems - execute_code # Citadel 在网关层限制 100 calls/hourAGT 在动作层收紧到每动作更小限额 rate_limits: query_customer_database: max_calls: 50 window_seconds: 3600 send_email: max_calls: 10 window_seconds: 3600 requires_justification: - send_email - escalate_to_human trust: minimum_score: 400 degraded_threshold: 600 actions_when_degraded: - query_customer_database - search_knowledge_base audit: log_all_decisions: true hash_chain: true export_to_citadel: true对应的策略评估流程可以在示例引擎 examples/citadel-governed-agent/src/agent.py 中看到完整实现顺序先查blocked_actions命中即拒绝并扣信任分 50再查allowed_actions白名单随后校验信任分是否低于minimum_score、动作是否缺少必需 justification、最后检查按动作的滑动窗口限流全部通过才放行。每次决策都会追加进 SHA-256 哈希链genesis 起链形成防篡改审计线索见 agent.py。Coverage Boundaries职责边界明确各系统处理什么可以避免重复治理或治理真空关注点由谁处理LLM 模型访问控制Citadel Layer 1APIM products/subscriptionsToken 限流Citadel Layer 1APIM policies内容安全过滤Citadel Layer 1Azure Content Safety网关侧 PII 检测Citadel Layer 1Azure Language Service逐动作策略评估AGT Policy Engine工具调用 allow/denyAGT Capability Model代理间信任AGT Trust LayerEd25519、SPIFFE信任评分0-1000AGT AgentMesh哈希链审计日志AGT Audit System舰队可观测性Citadel Layer 2 AGT Exporter代理企业身份Citadel Layer 3Entra代理运行时凭据AGTEd25519/SPIFFE威胁检测Citadel Layer 4Defender数据治理标签Citadel Layer 4Purview AGT data_classificationFailure Modes故障模式理解各组件不可用时的降级行为是生产部署的必要前提组件不可用行为Azure Event Hub / App InsightsAGT 继续运行。事件本地排队并在重连后重试。遥测采用 fail-open。Citadel APIM 网关代理无法触达 LLM/工具。AGT 策略引擎本地仍然可用。AGT Policy Engine代理动作在无治理状态下继续默认 fail-open可配置为 fail-closed。Entra IDAGT 使用本地密码学身份。企业身份联邦暂停。第 1 行的遥测 fail-open在源码中有直接印证CitadelAuditExporter.flush()在未配置 Event Hub 时会把事件降级为本地日志记录logger.info(Governance event (local): ...)见 citadel_exporter.py发送失败的事件进入_failed_buffer等待下次 flush 重试而不是抛出异常中断代理。azure-eventhub或azure-monitor-opentelemetry-exporter未安装时也只会记录警告并跳过对应导出目标见 citadel_exporter.py。Entra 身份联邦EntraIdentityBridge将 AGT 代理身份映射到 Entra ID 代理身份用于 Citadel Layer 3 关联。这是证明/联邦attestation/federation而非回写write-backEntra 仍是企业身份与生命周期的权威AGT 仍是运行时凭据与信任分的权威AGT 信任分作为风险标签呈现在遥测中而不是 Entra 元数据。from agent_os.integrations.citadel import EntraIdentityBridge bridge EntraIdentityBridge.from_env() # Bind AGT agent to its Entra managed identity (one-time setup) binding bridge.bind( agt_agent_idcustomer-support-agent-01, agt_public_keybase64-ed25519-pubkey, entra_object_id00000000-0000-0000-0000-000000000001, ) # Produce attestation (emitted as telemetry) attestation bridge.attest(binding, trust_score850) # attestation.risk_label TrustRiskLabel.TRUSTED信任分阈值源码中TrustRiskLabel.from_score()的实现见 identity_bridge.py 700trusted可信 400degraded降级 400untrusted不可信桥接实现的三个细节从源码与测试可以确认该桥接的三个工程细节密钥只存指纹不存明文bind()对 Ed25519 公钥计算 SHA-256 指纹agt_public_key_thumbprint存入绑定记录而非保存密钥本身。测试test_bind_hashes_the_public_key_rather_than_storing_it明确断言指纹等于密钥的 SHA-256且密钥材料不出现在绑定序列化结果中见 test_citadel_integration.py。阈值边界是包含下限参数化测试test_risk_label_boundaries验证了 700/400 是inclusive lower bounds——700 → TRUSTED、699 → DEGRADED、400 → DEGRADED、399 → UNTRUSTED。Graph 验证可选CITADEL_ENTRA_VERIFYtrue时bind()会通过 Microsoft Graph 校验 Entra object 是否存在_verify_entra_object需要azure-identity验证失败仅告警并标记verifiedFalse不阻断绑定。桥接产生的IdentityAttestation记录携带binding_id、agt_agent_id、entra_object_id、trust_score、risk_label、policy_bundle_id、policy_bundle_hash与时间戳作为遥测事件输出见 identity_bridge.py。APIM Governance Metadata治理元数据透传agt-governance-metadata策略片段policy fragment让 Citadel 网关记录 AGT 治理态势而无需把 AGT 放进请求热路径。这是该集成中最关键的性能设计决策APIM不会在每个请求上都调用 AGT 的策略端点——那会带来额外网络跳转延迟、造成可用性耦合、并产生两个系统同时做 allow/deny的脑裂决策。相反代理运行时本地评估策略把结果作为咨询性元数据经由网关传递APIM 只负责记录与关联不做治理决策除非显式开启可选的信任阈值拦截。完整流程代理运行时在发起 LLM 调用前设置X-AGT-*请求头APIM 片段读取这些请求头将其作为自定义追踪维度记录片段在转发到后端前剥离 AGT 请求头纵深防御防止下游泄露治理元数据响应携带X-AGT-APIM-Request-Id供跨系统关联。策略片段 XML、示例产品策略与部署说明见 examples/citadel-governed-agent/apim-policies/对应文件为 agt-governance-metadata.xml 与 agt-governed-product-policy.xml。请求头 Schema代理运行时在发起 LLM 调用前设置的请求头Header类型说明X-AGT-Trust-ScoreInteger (0-1000)代理当前信任分X-AGT-Risk-LabelStringtrusted、degraded或untrustedX-AGT-Policy-BundleString策略包 ID如customer-support-v2X-AGT-Policy-VersionString策略包版本如1.3.0X-AGT-Decision-IdUUID用于关联的 AGT 策略决策 ID片段追加到响应中的头Header类型说明X-AGT-APIM-Request-IdUUID用于跨系统追踪关联的 APIM 请求 ID片段代码中见 agt-governance-metadata.xml还包含一段默认注释掉的choose拦截逻辑如需在网关层做粗粒度安全兜底可取消注释当X-AGT-Risk-Label untrusted时直接返回403并携带agt_decision_id片段作者明确提示这是粗粒度安全网而非 AGT 细粒度策略评估的替代品。代理侧设置请求头apim-policies/README.md 给出了代理代码中设置请求头并与响应关联的完整示例import httpx from agent_os.integrations.citadel.identity_bridge import TrustRiskLabel headers { X-AGT-Trust-Score: str(current_trust_score), X-AGT-Risk-Label: TrustRiskLabel.from_score(current_trust_score).value, X-AGT-Policy-Bundle: policy_bundle.bundle_id, X-AGT-Policy-Version: policy_bundle.version, X-AGT-Decision-Id: decision_id, } response httpx.post( https://apim-gateway.azure-api.net/openai/deployments/gpt-4o/chat/completions, headers{**auth_headers, **headers}, jsonpayload, ) # Read back the APIM request ID for correlation apim_request_id response.headers.get(X-AGT-APIM-Request-Id, )部署片段通过 Azure CLI 将片段部署为 APIM named value名为agt-governance-metadataaz apim api-management named-value create \ --resource-group rg \ --service-name apim \ --named-value-id agt-governance-metadata \ --display-name AGT Governance Metadata Fragment \ --value $(cat agt-governance-metadata.xml)然后在 Access Contract 的产品策略中引用include-fragment fragment-idagt-governance-metadata /。快速开始部署 Citadel Governance Hub参考 Citadel 的 Layer 1 参考实现AI Hub Gateway Solution Accelerator 的 citadel-v1 分支完成 APIM 网关与 Access Contract 基础设施部署。安装 AGTpip install agent-governance-toolkit[full]配置导出器设置CITADEL_EVENTHUB_CONNECTION_STRING和CITADEL_APPINSIGHTS_CONNECTION_STRING两个环境变量可选配置CITADEL_ENTRA_TENANT_ID、CITADEL_ENTRA_VERIFY。部署 APIM 片段按上文 Azure CLI 命令部署 agt-governance-metadata.xml。运行端到端示例见 examples/citadel-governed-agent/。本地零依赖跑通治理闭环示例 examples/citadel-governed-agent/README.md 支持两种模式# 本地模式无需任何 Azure 依赖mock 网关 mock 导出器 python src/agent.py --mock # 接真实 Citadel 网关需配置环境变量 export CITADEL_GATEWAY_URLhttps://your-apim.azure-api.net export CITADEL_API_KEYyour-subscription-key export CITADEL_EVENTHUB_CONNECTION_STRINGEndpointsb://... python src/agent.py本地模式下agent.py 会依次演示 5 个治理场景白名单动作放行query_customer_database、显式拦截delete_customer_record、缺少 justification 拒绝send_email、携带 justification 放行、未知动作拒绝execute_code并在摘要中输出决策总数、放行/拒绝计数、当前信任分、哈希链头与导出事件数完整展示策略评估 → 信任分联动 → 哈希链审计 → 事件导出的治理闭环。参考AGT 系统架构设计AGT 整体设计Citadel AGT 受治理代理示例含代理源码、策略包、Access Contract 与 APIM 策略Citadel 集成模块源码EntraIdentityBridge、PolicyBundleResolver、TrustRiskLabel的实现Citadel 审计导出器CitadelAuditExporter与GovernanceEventCitadel 集成测试信任分阈值、密钥指纹、绑定增删与契约校验的测试佐证【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考