Agent Governance Toolkit IATP 参考 Sidecar 架构为 AI Agent 构建生产级信任代理【免费下载链接】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 中 IATPInter-Agent Trust Protocol代理间信任协议的参考 Sidecar 架构文档为核心介绍如何像 Envoy 之于微服务那样将信任校验、策略执行、隐私保护与审计遥测从 Agent 中抽离到独立的 Sidecar 代理进程。读者读完将掌握 Sidecar 的四层组件划分Proxy / Policy / Telemetry / Core、参考实现的 Go 伪代码与配置项、部署形态Kubernetes / 独立二进制 / systemd以及仓库内 Python SDK 的真实实现与测试验证方式。IATP Sidecar 是什么IATP Sidecar 是一个轻量级二进制进程位于 Agent 之前扮演“信任网关”的角色。参考架构文档将其定位描述为与 Envoy 位于微服务之前一样它拦截所有入站请求、依据信任与隐私策略进行校验、将校验通过的请求代理给后端 Agent并对全部流量做日志记录以实现审计与可逆性reversibility。从仓库实现看这套设计对应 Python SDK 中的SidecarProxy类iatp/sidecar/init.py其 docstring 明确列出的职责包括能力清单capability manifest交换、Agent 证明attestation验证、声誉跟踪与削减slashing、安全校验、隐私检查、请求路由、遥测与追踪。之所以采用“减法扩展”Scale by Subtraction思路是因为把信任逻辑、策略检查和审计日志硬编码进每个 Agent 会导致紧耦合、脆弱且无法互操作将这些横切关注点下沉到 Sidecar 后Agent 退化为纯业务函数可靠性由基础设施承担。总体架构与组件划分参考架构将 Sidecar 划分为四个内聚组件Python SDK 的模块布局与之一一对应┌──────────────────────────────────────────────────────┐ │ IATP Sidecar │ ├──────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ Proxy │ │ Policy │ │ Telemetry │ │ │ │ Layer │ │ Engine │ │ │ │ │ └─────────────┘ └──────────────┘ └────────────┘ │ │ ▲ ▲ ▲ │ │ └────────────────┴──────────────────┘ │ │ │ │ │ ┌───────┴────────┐ │ │ │ Core Library │ │ │ │ - Manifest │ │ │ │ - Security │ │ │ │ - Trace │ │ │ └────────────────┘ │ └──────────────────────────────────────────────────────┘ ▼ ┌──────────────────┐ │ Your Agent │ │ (Any Language) │ └──────────────────┘Proxy Layer/proxy负责接受 HTTP/gRPC 连接、路由到策略引擎校验、转发校验通过的请求、返回带追踪头的响应。参考文件结构为server.go/router.go/middleware.go/manifest_handler.go提供/.well-known/agent-manifest端点。Policy Engine/policy加载并解析能力清单、计算信任分数、检测敏感数据信用卡、SSN 等、应用隐私规则、生成警告或阻断决策。参考文件为evaluator.go/trust_score.go/sensitive_data.go/privacy_rules.go/config.go。Telemetry Layer/telemetry生成唯一 trace IDUUID、记录请求/响应/错误/阻断事件、日志写入前清洗敏感数据、支持 OpenTelemetry 分布式追踪、提供 trace 检索 API。参考文件为flight_recorder.go/trace_id.go/scrubber.go/otel_bridge.go/metrics.go。Core Library/core共享的数据结构与工具包括CapabilityManifest、TrustLevel、可逆性类型、隐私策略类型与 manifest JSON 校验。参考文件为manifest.go/trust_levels.go/reversibility.go/privacy.go/validation.go。在仓库的 Python 实现中这四个组件分别对应 iatp/sidecar/init.pySidecarProxy、iatp/policy_engine.pyIATPPolicyEngine、iatp/telemetry/init.pyFlightRecorder / TraceIDGenerator与 iatp/models/init.py数据模型。参考架构还为生产级 Sidecar 给出了性能目标作为设计预算而非实测结论指标目标说明延迟 (p50) 1ms仅代理开销延迟 (p99) 5ms含策略评估吞吐 10k RPS2 核机器内存 50MB空闲内存 200MB负载10k RPSCPU 1%空闲CPU 50%10k RPS 时核心数据模型与信任评分算法CapabilityManifest 与 TrustLevel参考架构给出的 Go 结构体定义了CapabilityManifest的字段$schema、identity、trust_level、capabilities、reversibility、privacy、authentication、rate_limiting、protocol_version、manifest_version、updated_at其中TrustLevel为五档枚举TrustLevel 值BaseScoreverified_partner10trusted7standard5unknown2untrusted0仓库 Python 实现中models/init.py 的CapabilityManifest由agent_id、agent_version、trust_level、capabilitiesAgentCapabilities、privacy_contractPrivacyContract与scopesRBAC 权限域如repo:read、repo:write构成TrustLevel枚举与上表完全一致ReversibilityLevel分为full/partial/noneRetentionPolicy分为ephemeral/temporary/permanent/forever。可参考实际示例清单 examples/manifests/standard_agent.json{ agent_id: standard-agent, trust_level: standard, capabilities: { reversibility: partial, idempotency: true, rate_limit: 50, sla_latency: 3000ms }, privacy_contract: { retention: temporary, human_review: false } }信任分数计算参考架构给出了如下 Go 参考实现来自trust_score.go的设计示意func CalculateTrustScore(manifest *CapabilityManifest) int { score : manifest.TrustLevel.BaseScore() // 0-10 if manifest.Reversibility.Level ! none { score 2 } if manifest.Privacy.Retention ephemeral { score 1 } if manifest.Privacy.Retention permanent || manifest.Privacy.Retention forever { score - 1 } if manifest.Privacy.HumanInLoop { score - 2 } if manifest.Privacy.TrainingConsent { score - 1 } return clamp(score, 0, 10) }需要说明的是该算法属于参考架构的设计蓝图仓库内 Python SDK 已提供可运行的等价实现CapabilityManifest.calculate_trust_score()models/init.py其计分口径略有不同以中性分 5 为基准verified_partner3、trusted2、standard0、unknown-2、untrusted-5幂等 1、可逆性full/partial1ephemeral留存 2、permanent/forever留存 -2、无人工审查 1最终 clamp 到 [0, 10]。分数区间含义8-10 为高度可信受验证伙伴 强隐私5-7 为中等可信3-4 为低可信0-2 为极低可信需强警告。Policy Engine 策略引擎参考架构中的 Policy Engine 职责为加载解析能力清单、评估信任分数、检测敏感数据、应用隐私规则、生成警告或阻断。仓库的 policy_engine.py 提供了一个自包含、协议原生的IATPPolicyEngine核心设计为规则按序匹配、首个命中的规则决定动作动作包括allow/warn/deny默认规则WarnUntrustedAgenttrust_level untrusted时警告默认规则RequireReversibilityreversibility none时警告默认规则AllowEphemeralretention_policy ephemeral时放行。add_custom_rule()允许注入自定义规则name/action/conditions/description并插入规则列表头部以获得更高优先级。validate_handshake()则校验远程 Agent 的能力是否满足本地要求如reversibility、idempotency以及 RBAC scope 是否齐备这正是参考架构中“握手handshake”端点的协议层实现。与之配合的是 security/init.py 中的SecurityValidatordetect_sensitive_data()通过正则识别信用卡、SSN、邮箱信用卡号码额外用Luhn 算法校验实现见_luhn_checkvalidate_privacy_policy()信用卡数据 permanent/forever留存 → 阻断SSN 非ephemeral留存 → 阻断generate_warning_message()信任分数 5、无可逆性、无幂等、永久留存、人工审查等场景拼接警告should_quarantine()信任分数 3、或“无可逆性 永久留存”、或untrusted时进入隔离quarantine流程。PrivacyScrubber会在日志落盘前递归地把信用卡/SSN 替换为[CREDIT_CARD_REDACTED]/[SSN_REDACTED]对应参考架构 Telemetry 层的 scrubber 职责。代理层请求处理链路参考架构中 Proxy Layer 的典型流程是“接受连接 → 策略校验 → 转发 → 返回带追踪头的响应”。仓库内 SidecarProxy._setup_routes() 给出了完整的 FastAPI 端点实现端点方法作用/.well-known/agent-manifestGET握手端点返回能力清单含可选 attestation/.well-known/agent-attestationGET返回加密证明记录无则 404/healthGET健康检查/proxyPOST主代理端点转发到后端 Agent/trace/{trace_id}GET检索 flight recorder 日志/quarantine/{trace_id}GET查询隔离会话/reputation/{agent_id}GET查询声誉分数/reputation/{agent_id}/slashPOST削减声誉cmvk 检测到幻觉时调用/reputation/export、/reputation/importGET/POST网络级声誉传播/proxy的处理顺序即参考架构的流水线解析 JSON失败返回 400→ 策略引擎校验失败 403blocked_by: policy_engine→ 隐私策略校验失败 403→ 合并策略与安全警告 → 有警告且无用户覆盖时返回449Retry With User Override→ 需要隔离且用户已覆盖时创建QuarantineSession→ 记录请求 → 转发后端超时 30s超时 504、异常 502并触发IATPRecoveryEngine恢复流程→ 记录响应与延迟 → 成功交易计入声誉。响应头携带X-Agent-Trace-ID、X-Agent-Latency-Ms、X-Agent-Trust-Score隔离时追加X-Agent-Quarantined: true。需要特别注意449 用户覆盖机制的安全加固调用方无法再通过裸传X-User-Override: true自我授权。_trusted_user_override()sidecar/init.py要求头部值必须与服务端IATP_TRUSTED_USER_OVERRIDE_TOKEN完全一致当环境变量未设置、为空、长度 16 或命中true/yes/admin等弱值时头部会被整体忽略——这也是参考架构“User override mechanism (X-User-Override header)”在 Python SDK 中的落地产物。遥测与审计日志参考架构要求 Telemetry 层生成 UUID trace ID、记录全部事件、落盘前清洗敏感数据并使用 JSONL 日志格式例如{type:request,trace_id:abc-123,timestamp:2026-01-23T12:34:56Z,payload:scrubbed} {type:response,trace_id:abc-123,timestamp:2026-01-23T12:34:57Z,latency_ms:1243.56} {type:error,trace_id:abc-123,timestamp:2026-01-23T12:34:57Z,error:timeout} {type:blocked,trace_id:abc-123,timestamp:2026-01-23T12:34:56Z,reason:credit_card_to_untrusted}仓库中的 telemetry/init.py 实现了FlightRecorder“黑匣子”每个 trace 对应一个${trace_id}.jsonl文件默认目录/tmp/iatp_logs与TraceIDGeneratorUUID v4。日志事件类型覆盖request/response/error/blocked/user_override且request、response、blocked三类日志中的 payload 都经过PrivacyScrubber清洗后再写入——对应参考架构中“Scrub sensitive data before logging”与“Provide trace retrieval API”/trace/{trace_id}两项要求。配置项环境变量参考架构给出的环境变量配置如下# Backend agent configuration IATP_BACKEND_URLhttp://localhost:8000 IATP_BACKEND_TIMEOUT30s # Sidecar server configuration IATP_PORT8001 IATP_LOG_LEVELinfo # Telemetry IATP_LOG_DIR/var/log/iatp IATP_OTEL_ENDPOINThttp://localhost:4318 IATP_METRICS_PORT9090 # Policy IATP_TRUST_THRESHOLD3 IATP_ALLOW_OVERRIDEtrue对照 Python SDK 实现可以确认IATP_BACKEND_URL对应create_sidecar(agent_url...)参数后端转发超时固定为 30ssidecar/init.py 中的timeout30.0IATP_PORT对应sidecar_port默认 8001用户覆盖开关在实现中被强化为服务端持有的IATP_TRUSTED_USER_OVERRIDE_TOKEN长度至少 16 字符弱值一律失效。YAML 配置文件参考架构同时提供 YAML 形式的完整配置模板iatp.yaml并给出了两条示例阻断规则——这正是“敏感数据 信任等级/留存策略”组合策略的声明式表达# iatp.yaml backend: url: http://localhost:8000 timeout: 30s server: port: 8001 log_level: info telemetry: log_dir: /var/log/iatp otel_endpoint: http://localhost:4318 metrics_port: 9090 policy: trust_threshold: 3 allow_override: true block_rules: - name: credit_card_to_untrusted condition: has_credit_card trust_level untrusted action: block - name: ssn_to_permanent condition: has_ssn retention permanent action: block其中credit_card_to_untrusted与ssn_to_permanent在 Python SDK 中的对应逻辑可见于SecurityValidator.validate_privacy_policy()信用卡 永久留存阻断、SSN 非临时留存阻断与IATPPolicyEngine的untrusted警告规则。部署模式参考架构给出三种部署形态均可按原样落地1. Kubernetes Sidecar 容器——在同一个 Pod 内与 Agent 容器并存Agent 暴露 8000 端口sidecar 暴露 8001 端口apiVersion: v1 kind: Pod metadata: name: booking-agent spec: containers: - name: agent image: my-agent:v1.0.0 ports: - containerPort: 8000 - name: iatp-sidecar image: iatp-sidecar:v1.0.0 ports: - containerPort: 8001 env: - name: IATP_BACKEND_URL value: http://localhost:8000 - name: IATP_PORT value: 80012. 独立二进制参考 Go 实现# Build go build -o iatp-sidecar ./cmd/sidecar # Run ./iatp-sidecar \ --backend-urlhttp://localhost:8000 \ --port8001 \ --manifest/etc/iatp/manifest.json3. systemd 服务[Unit] DescriptionIATP Sidecar Afternetwork.target [Service] Typesimple Useriatp ExecStart/usr/local/bin/iatp-sidecar \ --backend-urlhttp://localhost:8000 \ --port8001 \ --manifest/etc/iatp/manifest.json Restartalways [Install] WantedBymulti-user.target仓库中还提供了 Go 参考实现骨架sidecar/go/main.go、Python 版 sidecar 与 Agent 的 Dockerfiledocker/Dockerfile.sidecar-python、docker/Dockerfile.agent以及 docker-compose 编排docker-compose.yml可参照快速起一套本地环境。测试方法参考架构给出了单元、集成与压测三层测试建议仓库内亦有对应测试文件佐证iatp/tests/ 目录包含test_sidecar.py、test_policy_engine.py、test_security.py、test_telemetry.py、test_user_override_gate.py、test_attestation.py等。单元测试——验证信任分数计算注意 10 分上限的 clamp 行为func TestTrustScoreCalculation(t *testing.T) { manifest : CapabilityManifest{ TrustLevel: TrustLevelVerifiedPartner, Reversibility: Reversibility{Level: partial}, Privacy: Privacy{Retention: ephemeral}, } score : CalculateTrustScore(manifest) assert.Equal(t, 10, score) // 10 2 1 13, clamped to 10 }集成测试——启动 mock 后端经 Sidecar 代理后断言响应func TestProxyFlow(t *testing.T) { // Start mock backend backend : httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) w.Write([]byte({result:success})) })) defer backend.Close() // Start sidecar sidecar : NewSidecar(backend.URL, manifest) go sidecar.Run() // Make request resp, err : http.Post(http://localhost:8001/proxy, application/json, strings.NewReader({task:test})) assert.NoError(t, err) assert.Equal(t, 200, resp.StatusCode) }压测# Using Apache Bench ab -n 10000 -c 100 http://localhost:8001/proxy # Using vegeta echo POST http://localhost:8001/proxy | \ vegeta attack -duration60s -rate1000 | \ vegeta report仓库自带的端到端示例可先启动后端再拉起 sidecar 验证examples/backend_agent.py 与 examples/run_sidecar.py后者同时提供了“可信 Agent”与“不可信 Agent”两份 manifest 构造create_trusted_manifest/create_untrusted_manifest分别对应verified_partner ephemeral 幂等 partial 可逆与untrusted forever 留存 人工审查两个极端画像可用于观察信任分数与阻断行为的差异。安全考虑与监控可观测性参考架构明确的安全基线包括四项前两项在 Python SDK 中已有直接实现输入校验所有 JSON payload 按 schema 校验、拒绝超大请求默认 10MB可配置、清洗日志输出防止日志注入——对应/proxy的 JSON 解析失败返回 400以及PrivacyScrubber的日志清洗拒绝服务防护令牌桶限流、每 IP 连接数限制、请求超时强制——对应AgentCapabilities.rate_limit字段与后端 30s 超时身份认证支持 API Key自定义头、OAuth 2.0Bearer、双向 TLS证书、JWT——参考架构的设计要求Attestation 的 Ed25519 签名验证在 iatp/attestation.py 中实现依赖cryptography42.0.0缺失时校验失败关闭密钥管理绝不记录密钥、支持外部密钥存储Vault、AWS Secrets Manager、定期轮换。监控指标方面参考架构建议暴露 Prometheus 指标请求计数与延迟直方图、策略评估结果allow|warn|block计数、信任分数分布、日志写入量与 trace 存储字节数并定义 OpenTelemetry 追踪的 span 层级Span: iatp.proxy ├── Span: iatp.policy.evaluate │ ├── Span: iatp.policy.detect_sensitive_data │ └── Span: iatp.policy.calculate_trust_score ├── Span: iatp.proxy.forward └── Span: iatp.telemetry.log_request实施路线图参考架构给出为期约 8 周的四阶段实施路线可作为自建生产级 sidecar 的排期模板Phase 11-2 周最小可用HTTP 服务器 manifest 端点、基本代理转发、trace ID 生成、信任分数计算、stdout 简单日志Phase 23-4 周安全与隐私敏感数据检测信用卡 Luhn 校验、隐私规则评估、警告/阻断响应449/403、X-User-Override用户覆盖机制、JSONL flight recorderPhase 35-6 周生产加固OpenTelemetry 集成、Prometheus 指标、限流、连接池、优雅关闭、健康检查Phase 47-8 周高级特性gRPC 支持、sidecar 间 mTLS、manifest 缓存1 小时 TTL、分布式 saga 协调、Kubernetes 部署清单。仓库当前的 Python SDK 已覆盖 Phase 1、Phase 2 的全部能力并部分实现 Phase 3健康检查/health与 Phase 4声誉的导出/导入网络传播未来增强方向WebAssembly 插件策略、多区域部署、联邦信任网络、基于区块链的 manifest 验证、AI 异常检测仍在路线图中。小结IATP Reference Sidecar Architecture 给出了一套语言无关的“信任代理”蓝图用四个内聚组件Proxy / Policy / Telemetry / Core把信任计算、敏感数据检测、隐私策略、审计遥测与声誉管理全部从 Agent 进程剥离。仓库内的 Python SDKiatp/sidecar/init.py是该蓝图的可用实现Go 参考骨架位于 sidecar/go/协议细节可继续阅读 spec/001-handshake.md 与 spec/002-reversibility.md架构总览见 docs/ARCHITECTURE.md。对于希望为 Agent 增加零信任边界的团队最快捷的路径是复用 Python SDK按 examples/run_sidecar.py 的模板在现有 Agent 前挂载一个 IATP Sidecar。【免费下载链接】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），仅供参考 
长河君 · 2026/9/18 2:09:08 · 阅读 1.2k Agent Governance Toolkit IATP 参考 Sidecar 架构：为 AI Agent 构建生产级信任代理
Agent Governance Toolkit IATP 参考 Sidecar 架构为 AI Agent 构建生产级信任代理【免费下载链接】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 中 IATPInter-Agent Trust Protocol代理间信任协议的参考 Sidecar 架构文档为核心介绍如何像 Envoy 之于微服务那样将信任校验、策略执行、隐私保护与审计遥测从 Agent 中抽离到独立的 Sidecar 代理进程。读者读完将掌握 Sidecar 的四层组件划分Proxy / Policy / Telemetry / Core、参考实现的 Go 伪代码与配置项、部署形态Kubernetes / 独立二进制 / systemd以及仓库内 Python SDK 的真实实现与测试验证方式。IATP Sidecar 是什么IATP Sidecar 是一个轻量级二进制进程位于 Agent 之前扮演“信任网关”的角色。参考架构文档将其定位描述为与 Envoy 位于微服务之前一样它拦截所有入站请求、依据信任与隐私策略进行校验、将校验通过的请求代理给后端 Agent并对全部流量做日志记录以实现审计与可逆性reversibility。从仓库实现看这套设计对应 Python SDK 中的SidecarProxy类iatp/sidecar/init.py其 docstring 明确列出的职责包括能力清单capability manifest交换、Agent 证明attestation验证、声誉跟踪与削减slashing、安全校验、隐私检查、请求路由、遥测与追踪。之所以采用“减法扩展”Scale by Subtraction思路是因为把信任逻辑、策略检查和审计日志硬编码进每个 Agent 会导致紧耦合、脆弱且无法互操作将这些横切关注点下沉到 Sidecar 后Agent 退化为纯业务函数可靠性由基础设施承担。总体架构与组件划分参考架构将 Sidecar 划分为四个内聚组件Python SDK 的模块布局与之一一对应┌──────────────────────────────────────────────────────┐ │ IATP Sidecar │ ├──────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ Proxy │ │ Policy │ │ Telemetry │ │ │ │ Layer │ │ Engine │ │ │ │ │ └─────────────┘ └──────────────┘ └────────────┘ │ │ ▲ ▲ ▲ │ │ └────────────────┴──────────────────┘ │ │ │ │ │ ┌───────┴────────┐ │ │ │ Core Library │ │ │ │ - Manifest │ │ │ │ - Security │ │ │ │ - Trace │ │ │ └────────────────┘ │ └──────────────────────────────────────────────────────┘ ▼ ┌──────────────────┐ │ Your Agent │ │ (Any Language) │ └──────────────────┘Proxy Layer/proxy负责接受 HTTP/gRPC 连接、路由到策略引擎校验、转发校验通过的请求、返回带追踪头的响应。参考文件结构为server.go/router.go/middleware.go/manifest_handler.go提供/.well-known/agent-manifest端点。Policy Engine/policy加载并解析能力清单、计算信任分数、检测敏感数据信用卡、SSN 等、应用隐私规则、生成警告或阻断决策。参考文件为evaluator.go/trust_score.go/sensitive_data.go/privacy_rules.go/config.go。Telemetry Layer/telemetry生成唯一 trace IDUUID、记录请求/响应/错误/阻断事件、日志写入前清洗敏感数据、支持 OpenTelemetry 分布式追踪、提供 trace 检索 API。参考文件为flight_recorder.go/trace_id.go/scrubber.go/otel_bridge.go/metrics.go。Core Library/core共享的数据结构与工具包括CapabilityManifest、TrustLevel、可逆性类型、隐私策略类型与 manifest JSON 校验。参考文件为manifest.go/trust_levels.go/reversibility.go/privacy.go/validation.go。在仓库的 Python 实现中这四个组件分别对应 iatp/sidecar/init.pySidecarProxy、iatp/policy_engine.pyIATPPolicyEngine、iatp/telemetry/init.pyFlightRecorder / TraceIDGenerator与 iatp/models/init.py数据模型。参考架构还为生产级 Sidecar 给出了性能目标作为设计预算而非实测结论指标目标说明延迟 (p50) 1ms仅代理开销延迟 (p99) 5ms含策略评估吞吐 10k RPS2 核机器内存 50MB空闲内存 200MB负载10k RPSCPU 1%空闲CPU 50%10k RPS 时核心数据模型与信任评分算法CapabilityManifest 与 TrustLevel参考架构给出的 Go 结构体定义了CapabilityManifest的字段$schema、identity、trust_level、capabilities、reversibility、privacy、authentication、rate_limiting、protocol_version、manifest_version、updated_at其中TrustLevel为五档枚举TrustLevel 值BaseScoreverified_partner10trusted7standard5unknown2untrusted0仓库 Python 实现中models/init.py 的CapabilityManifest由agent_id、agent_version、trust_level、capabilitiesAgentCapabilities、privacy_contractPrivacyContract与scopesRBAC 权限域如repo:read、repo:write构成TrustLevel枚举与上表完全一致ReversibilityLevel分为full/partial/noneRetentionPolicy分为ephemeral/temporary/permanent/forever。可参考实际示例清单 examples/manifests/standard_agent.json{ agent_id: standard-agent, trust_level: standard, capabilities: { reversibility: partial, idempotency: true, rate_limit: 50, sla_latency: 3000ms }, privacy_contract: { retention: temporary, human_review: false } }信任分数计算参考架构给出了如下 Go 参考实现来自trust_score.go的设计示意func CalculateTrustScore(manifest *CapabilityManifest) int { score : manifest.TrustLevel.BaseScore() // 0-10 if manifest.Reversibility.Level ! none { score 2 } if manifest.Privacy.Retention ephemeral { score 1 } if manifest.Privacy.Retention permanent || manifest.Privacy.Retention forever { score - 1 } if manifest.Privacy.HumanInLoop { score - 2 } if manifest.Privacy.TrainingConsent { score - 1 } return clamp(score, 0, 10) }需要说明的是该算法属于参考架构的设计蓝图仓库内 Python SDK 已提供可运行的等价实现CapabilityManifest.calculate_trust_score()models/init.py其计分口径略有不同以中性分 5 为基准verified_partner3、trusted2、standard0、unknown-2、untrusted-5幂等 1、可逆性full/partial1ephemeral留存 2、permanent/forever留存 -2、无人工审查 1最终 clamp 到 [0, 10]。分数区间含义8-10 为高度可信受验证伙伴 强隐私5-7 为中等可信3-4 为低可信0-2 为极低可信需强警告。Policy Engine 策略引擎参考架构中的 Policy Engine 职责为加载解析能力清单、评估信任分数、检测敏感数据、应用隐私规则、生成警告或阻断。仓库的 policy_engine.py 提供了一个自包含、协议原生的IATPPolicyEngine核心设计为规则按序匹配、首个命中的规则决定动作动作包括allow/warn/deny默认规则WarnUntrustedAgenttrust_level untrusted时警告默认规则RequireReversibilityreversibility none时警告默认规则AllowEphemeralretention_policy ephemeral时放行。add_custom_rule()允许注入自定义规则name/action/conditions/description并插入规则列表头部以获得更高优先级。validate_handshake()则校验远程 Agent 的能力是否满足本地要求如reversibility、idempotency以及 RBAC scope 是否齐备这正是参考架构中“握手handshake”端点的协议层实现。与之配合的是 security/init.py 中的SecurityValidatordetect_sensitive_data()通过正则识别信用卡、SSN、邮箱信用卡号码额外用Luhn 算法校验实现见_luhn_checkvalidate_privacy_policy()信用卡数据 permanent/forever留存 → 阻断SSN 非ephemeral留存 → 阻断generate_warning_message()信任分数 5、无可逆性、无幂等、永久留存、人工审查等场景拼接警告should_quarantine()信任分数 3、或“无可逆性 永久留存”、或untrusted时进入隔离quarantine流程。PrivacyScrubber会在日志落盘前递归地把信用卡/SSN 替换为[CREDIT_CARD_REDACTED]/[SSN_REDACTED]对应参考架构 Telemetry 层的 scrubber 职责。代理层请求处理链路参考架构中 Proxy Layer 的典型流程是“接受连接 → 策略校验 → 转发 → 返回带追踪头的响应”。仓库内 SidecarProxy._setup_routes() 给出了完整的 FastAPI 端点实现端点方法作用/.well-known/agent-manifestGET握手端点返回能力清单含可选 attestation/.well-known/agent-attestationGET返回加密证明记录无则 404/healthGET健康检查/proxyPOST主代理端点转发到后端 Agent/trace/{trace_id}GET检索 flight recorder 日志/quarantine/{trace_id}GET查询隔离会话/reputation/{agent_id}GET查询声誉分数/reputation/{agent_id}/slashPOST削减声誉cmvk 检测到幻觉时调用/reputation/export、/reputation/importGET/POST网络级声誉传播/proxy的处理顺序即参考架构的流水线解析 JSON失败返回 400→ 策略引擎校验失败 403blocked_by: policy_engine→ 隐私策略校验失败 403→ 合并策略与安全警告 → 有警告且无用户覆盖时返回449Retry With User Override→ 需要隔离且用户已覆盖时创建QuarantineSession→ 记录请求 → 转发后端超时 30s超时 504、异常 502并触发IATPRecoveryEngine恢复流程→ 记录响应与延迟 → 成功交易计入声誉。响应头携带X-Agent-Trace-ID、X-Agent-Latency-Ms、X-Agent-Trust-Score隔离时追加X-Agent-Quarantined: true。需要特别注意449 用户覆盖机制的安全加固调用方无法再通过裸传X-User-Override: true自我授权。_trusted_user_override()sidecar/init.py要求头部值必须与服务端IATP_TRUSTED_USER_OVERRIDE_TOKEN完全一致当环境变量未设置、为空、长度 16 或命中true/yes/admin等弱值时头部会被整体忽略——这也是参考架构“User override mechanism (X-User-Override header)”在 Python SDK 中的落地产物。遥测与审计日志参考架构要求 Telemetry 层生成 UUID trace ID、记录全部事件、落盘前清洗敏感数据并使用 JSONL 日志格式例如{type:request,trace_id:abc-123,timestamp:2026-01-23T12:34:56Z,payload:scrubbed} {type:response,trace_id:abc-123,timestamp:2026-01-23T12:34:57Z,latency_ms:1243.56} {type:error,trace_id:abc-123,timestamp:2026-01-23T12:34:57Z,error:timeout} {type:blocked,trace_id:abc-123,timestamp:2026-01-23T12:34:56Z,reason:credit_card_to_untrusted}仓库中的 telemetry/init.py 实现了FlightRecorder“黑匣子”每个 trace 对应一个${trace_id}.jsonl文件默认目录/tmp/iatp_logs与TraceIDGeneratorUUID v4。日志事件类型覆盖request/response/error/blocked/user_override且request、response、blocked三类日志中的 payload 都经过PrivacyScrubber清洗后再写入——对应参考架构中“Scrub sensitive data before logging”与“Provide trace retrieval API”/trace/{trace_id}两项要求。配置项环境变量参考架构给出的环境变量配置如下# Backend agent configuration IATP_BACKEND_URLhttp://localhost:8000 IATP_BACKEND_TIMEOUT30s # Sidecar server configuration IATP_PORT8001 IATP_LOG_LEVELinfo # Telemetry IATP_LOG_DIR/var/log/iatp IATP_OTEL_ENDPOINThttp://localhost:4318 IATP_METRICS_PORT9090 # Policy IATP_TRUST_THRESHOLD3 IATP_ALLOW_OVERRIDEtrue对照 Python SDK 实现可以确认IATP_BACKEND_URL对应create_sidecar(agent_url...)参数后端转发超时固定为 30ssidecar/init.py 中的timeout30.0IATP_PORT对应sidecar_port默认 8001用户覆盖开关在实现中被强化为服务端持有的IATP_TRUSTED_USER_OVERRIDE_TOKEN长度至少 16 字符弱值一律失效。YAML 配置文件参考架构同时提供 YAML 形式的完整配置模板iatp.yaml并给出了两条示例阻断规则——这正是“敏感数据 信任等级/留存策略”组合策略的声明式表达# iatp.yaml backend: url: http://localhost:8000 timeout: 30s server: port: 8001 log_level: info telemetry: log_dir: /var/log/iatp otel_endpoint: http://localhost:4318 metrics_port: 9090 policy: trust_threshold: 3 allow_override: true block_rules: - name: credit_card_to_untrusted condition: has_credit_card trust_level untrusted action: block - name: ssn_to_permanent condition: has_ssn retention permanent action: block其中credit_card_to_untrusted与ssn_to_permanent在 Python SDK 中的对应逻辑可见于SecurityValidator.validate_privacy_policy()信用卡 永久留存阻断、SSN 非临时留存阻断与IATPPolicyEngine的untrusted警告规则。部署模式参考架构给出三种部署形态均可按原样落地1. Kubernetes Sidecar 容器——在同一个 Pod 内与 Agent 容器并存Agent 暴露 8000 端口sidecar 暴露 8001 端口apiVersion: v1 kind: Pod metadata: name: booking-agent spec: containers: - name: agent image: my-agent:v1.0.0 ports: - containerPort: 8000 - name: iatp-sidecar image: iatp-sidecar:v1.0.0 ports: - containerPort: 8001 env: - name: IATP_BACKEND_URL value: http://localhost:8000 - name: IATP_PORT value: 80012. 独立二进制参考 Go 实现# Build go build -o iatp-sidecar ./cmd/sidecar # Run ./iatp-sidecar \ --backend-urlhttp://localhost:8000 \ --port8001 \ --manifest/etc/iatp/manifest.json3. systemd 服务[Unit] DescriptionIATP Sidecar Afternetwork.target [Service] Typesimple Useriatp ExecStart/usr/local/bin/iatp-sidecar \ --backend-urlhttp://localhost:8000 \ --port8001 \ --manifest/etc/iatp/manifest.json Restartalways [Install] WantedBymulti-user.target仓库中还提供了 Go 参考实现骨架sidecar/go/main.go、Python 版 sidecar 与 Agent 的 Dockerfiledocker/Dockerfile.sidecar-python、docker/Dockerfile.agent以及 docker-compose 编排docker-compose.yml可参照快速起一套本地环境。测试方法参考架构给出了单元、集成与压测三层测试建议仓库内亦有对应测试文件佐证iatp/tests/ 目录包含test_sidecar.py、test_policy_engine.py、test_security.py、test_telemetry.py、test_user_override_gate.py、test_attestation.py等。单元测试——验证信任分数计算注意 10 分上限的 clamp 行为func TestTrustScoreCalculation(t *testing.T) { manifest : CapabilityManifest{ TrustLevel: TrustLevelVerifiedPartner, Reversibility: Reversibility{Level: partial}, Privacy: Privacy{Retention: ephemeral}, } score : CalculateTrustScore(manifest) assert.Equal(t, 10, score) // 10 2 1 13, clamped to 10 }集成测试——启动 mock 后端经 Sidecar 代理后断言响应func TestProxyFlow(t *testing.T) { // Start mock backend backend : httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) w.Write([]byte({result:success})) })) defer backend.Close() // Start sidecar sidecar : NewSidecar(backend.URL, manifest) go sidecar.Run() // Make request resp, err : http.Post(http://localhost:8001/proxy, application/json, strings.NewReader({task:test})) assert.NoError(t, err) assert.Equal(t, 200, resp.StatusCode) }压测# Using Apache Bench ab -n 10000 -c 100 http://localhost:8001/proxy # Using vegeta echo POST http://localhost:8001/proxy | \ vegeta attack -duration60s -rate1000 | \ vegeta report仓库自带的端到端示例可先启动后端再拉起 sidecar 验证examples/backend_agent.py 与 examples/run_sidecar.py后者同时提供了“可信 Agent”与“不可信 Agent”两份 manifest 构造create_trusted_manifest/create_untrusted_manifest分别对应verified_partner ephemeral 幂等 partial 可逆与untrusted forever 留存 人工审查两个极端画像可用于观察信任分数与阻断行为的差异。安全考虑与监控可观测性参考架构明确的安全基线包括四项前两项在 Python SDK 中已有直接实现输入校验所有 JSON payload 按 schema 校验、拒绝超大请求默认 10MB可配置、清洗日志输出防止日志注入——对应/proxy的 JSON 解析失败返回 400以及PrivacyScrubber的日志清洗拒绝服务防护令牌桶限流、每 IP 连接数限制、请求超时强制——对应AgentCapabilities.rate_limit字段与后端 30s 超时身份认证支持 API Key自定义头、OAuth 2.0Bearer、双向 TLS证书、JWT——参考架构的设计要求Attestation 的 Ed25519 签名验证在 iatp/attestation.py 中实现依赖cryptography42.0.0缺失时校验失败关闭密钥管理绝不记录密钥、支持外部密钥存储Vault、AWS Secrets Manager、定期轮换。监控指标方面参考架构建议暴露 Prometheus 指标请求计数与延迟直方图、策略评估结果allow|warn|block计数、信任分数分布、日志写入量与 trace 存储字节数并定义 OpenTelemetry 追踪的 span 层级Span: iatp.proxy ├── Span: iatp.policy.evaluate │ ├── Span: iatp.policy.detect_sensitive_data │ └── Span: iatp.policy.calculate_trust_score ├── Span: iatp.proxy.forward └── Span: iatp.telemetry.log_request实施路线图参考架构给出为期约 8 周的四阶段实施路线可作为自建生产级 sidecar 的排期模板Phase 11-2 周最小可用HTTP 服务器 manifest 端点、基本代理转发、trace ID 生成、信任分数计算、stdout 简单日志Phase 23-4 周安全与隐私敏感数据检测信用卡 Luhn 校验、隐私规则评估、警告/阻断响应449/403、X-User-Override用户覆盖机制、JSONL flight recorderPhase 35-6 周生产加固OpenTelemetry 集成、Prometheus 指标、限流、连接池、优雅关闭、健康检查Phase 47-8 周高级特性gRPC 支持、sidecar 间 mTLS、manifest 缓存1 小时 TTL、分布式 saga 协调、Kubernetes 部署清单。仓库当前的 Python SDK 已覆盖 Phase 1、Phase 2 的全部能力并部分实现 Phase 3健康检查/health与 Phase 4声誉的导出/导入网络传播未来增强方向WebAssembly 插件策略、多区域部署、联邦信任网络、基于区块链的 manifest 验证、AI 异常检测仍在路线图中。小结IATP Reference Sidecar Architecture 给出了一套语言无关的“信任代理”蓝图用四个内聚组件Proxy / Policy / Telemetry / Core把信任计算、敏感数据检测、隐私策略、审计遥测与声誉管理全部从 Agent 进程剥离。仓库内的 Python SDKiatp/sidecar/init.py是该蓝图的可用实现Go 参考骨架位于 sidecar/go/协议细节可继续阅读 spec/001-handshake.md 与 spec/002-reversibility.md架构总览见 docs/ARCHITECTURE.md。对于希望为 Agent 增加零信任边界的团队最快捷的路径是复用 Python SDK按 examples/run_sidecar.py 的模板在现有 Agent 前挂载一个 IATP Sidecar。【免费下载链接】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），仅供参考