Agent Governance Toolkit 之 IATP CLI 实战能力清单校验与 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-toolkitIATPInter-Agent Trust Protocol代理间信任协议CLI 是 Agent Governance Toolkit 中面向开发者的命令行工具用于校验能力清单capability manifest文件、扫描运行中的 Agent 并计算信任评分。本文以agent-governance-python/agent-os/modules/iatp/docs/CLI_GUIDE.md为骨架结合iatp/cli.py与iatp/models/__init__.py的源码实现完整讲解iatp verify、iatp scan、iatp version三个命令的用法、信任评分计算原理与 CI/CD 集成方案帮助读者将 IATP 的信任治理能力接入自己的多 Agent 系统。IATP CLI 是什么IATP 是一个 sidecar 架构的代理间信任协议定位在 Agent OS 的 Layer 2Infrastructure通过标准的/.well-known/agent-manifest端点对外发布信任级别、可逆性保证、隐私契约与 SLA 承诺详见 IATP 主 README。IATP CLI 则是协议配套的开发者工具承担两类核心工作校验verify对能力清单文件做静态验证包括 JSON schema、必填字段、枚举值、逻辑矛盾与隐私隐患扫描scan连接运行中的 Agent抓取其能力清单端点并计算 0–100 的信任评分辅助调用方决定是否与之通信。CLI 的实现集中在 iatp/cli.py基于click框架构建命令组全部命令同时支持人类可读输出与机器可解析的--json输出。对应的行为契约由 iatp/tests/test_cli.py 中的用例锁定如合法清单返回 0、非法清单返回 1、--help包含verify/scan等。安装与命令行入口原文档给出的安装方式为pip install iatp需要说明的是以当前仓库源码为准包的实际定义名称为agent-governance-toolkit-trust-protocol见 pyproject.toml版本 5.0.0或inter-agent-trust-protocol见 setup.py两者都在安装后通过 entry point 暴露iatp命令。因此最稳妥的方式是从本仓库源码安装cd agent-governance-python/agent-os/modules/iatp pip install -e .安装完成后即可使用iatp --help # 查看命令组帮助 iatp verify --help # 查看 verify 子命令帮助 iatp scan --help # 查看 scan 子命令帮助从源码结构看命令行入口由 setup.py 中的entry_points.console_scriptsiatpiatp.cli:cli与 pyproject.toml 中的[project.scripts]共同声明指向iatp.cli模块的cli组函数。运行iatp version时打印的版本号来自 iatp/init.py 中的__version__当前源码为3.2.2。依赖方面CLI 的运行需要click、pydantic清单模型、httpx扫描时的网络请求等库这些已在 setup.py 的install_requires中声明。iatp verify能力清单静态校验用法与选项iatp verify manifest-path [OPTIONS]选项说明--verbose, -v显示详细的校验输出原始清单内容、可逆性、幂等性、限流、SLA、保留策略等--json以 JSON 格式输出结构化结果便于脚本解析源码新增选项见 iatp/cli.py典型用法# 基础校验 iatp verify ./manifest.json # 详细输出 iatp verify ./manifest.json --verbose # 机器可读输出 iatp verify ./manifest.json --json校验内容按 iatp/cli.py 的实现verify覆盖以下检查项✅ 合法 JSON schema通过 Pydantic 模型CapabilityManifest(**manifest_data)实例化校验✅ 必填字段存在如agent_id、capabilities、privacy_contract✅ 枚举值合法trust_level、reversibility、retention等取值必须落在枚举范围内⚠️ 逻辑矛盾检测⚠️ 隐私隐患检测。三类逻辑检查的源码细节除文档列出的两条规则外源码还实现了第三条检查见 iatp/cli.py保留策略 vs 信任级别当retention permanent永久保留且信任级别为verified_partner或standard时产生告警永久保留的受信代理应改用临时或会话级保留可逆性 vs 信任级别错误级当reversibility none不可逆且信任级别为untrusted时产生错误不受信且不可逆的代理属于高风险配置导致校验失败并退出码为 1人工审核 vs 高信任当human_review true且信任级别为verified_partner时产生告警对已验证合作伙伴启用人工审核可能没有必要。注意告警warning不会导致校验失败只有错误error会使命令以退出码 1 结束。示例输出 Validating manifest: examples/manifests/secure_bank.json ✅ Schema validation passed Agent ID: secure-bank-agent Trust Level: verified_partner Trust Score: 10/10 ✨ Manifest is valid and ready to use!--json模式则输出结构化结果字段包括status、agent_id、trust_level、trust_score、errors、warnings可供上层流水线直接消费。与示例清单的对照仓库提供了可直接试用的示例清单例如 secure_bank.jsonverified_partnerfull可逆 幂等 ephemeral保留 无人工审核评分 10/10与 untrusted_honeypot.jsonuntrustednone可逆 permanent保留 人工审核触发高风险错误。iatp/tests/test_cli.py 中的test_verify_valid_manifest与test_verify_invalid_manifest分别断言了这两种场景的输出。iatp scan运行时信任扫描用法与选项iatp scan agent-url [OPTIONS]选项说明--timeout, -t请求超时秒数默认 10--verbose, -v显示详细扫描输出抓取到的清单原文、性能保证等--json以 JSON 格式输出结构化结果典型用法# 扫描本地代理 iatp scan http://localhost:8001 # 自定义超时 iatp scan https://api.example.com/agent --timeout 30 # 详细扫描 iatp scan http://localhost:8001 --verbose工作流程按原文档与 iatp/cli.py 的实现scan依次执行规整 URL若传入的地址缺少http://或https://前缀自动补全为http://源码行为抓取清单向{agent_url}/.well-known/agent-manifest发起httpxGET 请求超时时间由--timeout控制解析清单将响应 JSON 解析为CapabilityManifest模型计算信任评分先得到 0–10 的内部评分再乘以 10 转为 0–100 的展示评分int(trust_score_10 * 10)显示安全指标幂等操作、可逆性支持、数据保留策略、人工审核状态给出建议评分低于 50 时提示使用X-User-Override: true请求头继续、避免发送敏感数据、监控隔离日志。示例输出 Scanning agent: http://localhost:8001 ✅ Trust Score: 100/100 ( LOW RISK) Agent Profile: Agent ID: secure-bank-agent Trust Level: verified_partner Reversibility: full Data Retention: ephemeral Security Indicators: ✅ Idempotent operations ✅ Reversibility support ✅ Limited data retention ✅ Automated processing风险分级源码中将 0–100 评分映射为三级风险80–100 LOW —— 高度可信可放心调用50–79 MEDIUM —— 谨慎使用注意风险0–49 HIGH —— 避免发送敏感数据需人工决策如携带X-User-Override: true头。--verbose模式下还会输出rate_limit每分钟请求数与sla_latency承诺延迟等性能保证信息。--json模式返回status、agent_id、trust_score、risk_level、trust_level、reversibility、retention等字段便于自动化消费。iatp version版本查询iatp version输出格式来自 iatp/cli.pyIATP CLI v3.2.2 Inter-Agent Trust Protocol同样支持--json返回name、version、description、url四个字段。版本号实际取自 iatp/init.py 的__version__常量。信任评分计算机制0–10 内部评分与 0–100 展示评分核心评分逻辑在 iatp/models/init.py 的CapabilityManifest.calculate_trust_score()中以5 分为中性基准依据信任级别、能力与隐私契约逐项加减最终钳制clamp在 [0, 10]。verify直接展示该 0–10 分数scan将其乘以 10 得到 0–100 分数因此原文档中的 0–100 评分因子表正是内部 0–10 分值的 10 倍映射。评分因子对照表因子0–100 影响0–10 内部分值来源Trust Level: verified_partner303模型枚举Trust Level: trusted202模型枚举Trust Level: standard00模型枚举Trust Level: unknown-20-2模型枚举Trust Level: untrusted-50-5模型枚举Idempotency 幂等启用101capabilitiesReversibility 可逆支持full/partial101capabilitiesEphemeral retention 会话级保留202privacy_contractPermanent retention 永久保留-20-2privacy_contract无人工审核纯自动化处理101privacy_contract相关枚举取值评分依赖的枚举定义同样位于 iatp/models/init.pyTrustLevelverified_partner/trusted/standard/unknown/untrustedReversibilityLevelfull完整回滚/partial受限回滚/none不支持回滚RetentionPolicyephemeral会话后删除/temporary短期保存如 30 天/permanent无限期保存/foreverpermanent 的兼容别名。手工推算示例以 secure_bank.json 为例基准 5 verified_partner(3) 幂等(1) 可逆(1) ephemeral(2) 无人工审核(1) 10/10对应 scan 的 100/100与示例输出一致以 untrusted_honeypot.json 为例基准 5 untrusted(-5) permanent(-2) -2钳制为0/10属于 HIGH RISK同时因不可逆 不受信组合在校验阶段即被判定为错误配置。退出码约定退出码含义0成功清单有效 / 扫描成功1校验失败或发生错误补充说明对于参数解析层面的使用错误例如verify传入不存在的文件路径click.Path(existsTrue)在参数阶段即拦截click 框架可能返回退出码 2这一行为已被 iatp/tests/test_cli.py 中的test_verify_nonexistent_file用例覆盖断言exit_code in [1, 2]。另外源码对异常信息做了消毒处理仅区分已知错误网络请求失败、JSON 解析失败、值错误、权限错误与内部错误避免向调用方泄露内部实现细节见 iatp/cli.py。集成实战在 CI/CD 中校验清单# GitHub Actions - name: Validate manifest run: iatp verify ./config/manifest.json把清单校验放进流水线可在代码合并前拦截高风险的 Agent 配置。预部署检查#!/bin/bash if iatp verify ./manifest.json; then echo ✅ Manifest valid, deploying... docker compose up -d else echo ❌ Manifest invalid, aborting exit 1 fi借助退出码语义将verify作为部署门禁。Agent 健康监控#!/bin/bash SCORE$(iatp scan http://localhost:8001 --verbose | grep Trust Score | awk {print $3} | cut -d/ -f1) if [ $SCORE -lt 50 ]; then echo ⚠️ Low trust score detected: $SCORE # Send alert fi轮询扫描运行中的 Agent当信任评分跌破阈值时触发告警。对接自动化平台使用--json输出可将结果直接喂给监控系统或自定义策略引擎无需解析彩色文本扫描到低分 Agent 时调用方可以依据输出决定拒绝请求或携带X-User-Override: true头人工接管。仓库 examples 目录提供了配套的运行示例例如 run_secure_bank_sidecar.py 可用于本地起一个带清单端点的侧车供scan实测。故障排查Manifest endpoint not foundAgent 未暴露/.well-known/agent-manifest端点。请确认Agent 已挂载 IATP sidecar参考 Docker 部署指南sidecar 正在运行扫描 URL 正确注意scan会在缺少协议前缀时自动补http://若目标实际是 HTTPS请显式写明https://。Connection errorAgent 不可达。请检查Agent 是否在运行网络连通性防火墙规则是否放行目标端口。Validation failed清单存在问题。先加--verbose查看详细原因iatp verify ./manifest.json --verbose重点排查枚举取值合法性、必填字段缺失以及不可逆 不受信这类逻辑矛盾告警类问题如永久保留、对已验证伙伴启用人工审核不会阻断校验但建议按提示整改以提升信任评分。延伸阅读IATP Docker 部署指南sidecar 的容器化部署方式IATP 主 README协议架构、attestation 与信誉削减机制的完整介绍IATP API 规范文档握手协议与可逆性规范iatp/cli.pyCLI 完整实现iatp/models/init.py能力清单模型与信任评分算法iatp/tests/test_cli.pyCLI 行为契约测试。【免费下载链接】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），仅供参考