用 OpenAgent DefinitionOAD为 AI Agent 定义标准接口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-toolkit 仓库中self-evaluating示例的 OpenAgent DefinitionOAD实现展开OAD 是一套面向 AI Agent 的接口定义语言IDL其定位类似 Swagger/OpenAPI 之于 REST API。文章会从问题动机、数据模型、DoerAgent 集成、测试验证、使用模式到未来演进完整讲解如何用 Capabilities、Constraints、IO Contract、Trust Score 四要素为 Agent 建立可发现、可组合、可信赖的标准接口。背景为什么 Agent 需要自己的 OpenAPI在传统的单体 Agent 时代开发者常被告知直接读 system prompt 就能知道 Agent 能做什么。 这在单个 Agent 的场景下尚可接受但当 Agent 生态走向市场化和规模化时这条路径立刻失效从市场Marketplace拉取一个专用 Agent例如 GitHub Coder 或 OpenAI Analyst时我们无法靠猜测来得知如何与它对话多个 Agent 需要协作时彼此的输入输出没有可校验的契约平台方无法对 Agent 的能力声明、性能表现进行客观比较与审计。这正是 OpenAgent DefinitionOAD要解决的问题。在 IMPLEMENTATION_SUMMARY_OAD.md 中OAD 被定义为 AI 的 USB 接口时刻——谁定义了标准 Agent 协议谁就赢得平台之争。其核心是要求生态中的每个 Agent 发布一份Metadata Manifest元数据清单包含四类信息要素含义示例CapabilitiesCan-DoAgent 能做什么我能编写 Python 3.9 代码我能解析 CSVConstraintsWont-DoAgent 不能/不会做什么我没有联网能力我有 4k token 上限IO Contract输入输出契约我接收 CodeContext 对象返回 Diff 对象Trust Score性能与可靠性指标我的代码编译通过率 95%数据模型dataclass 驱动的五类核心对象OAD 的完整实现位于 src/agent_metadata.py全部采用 Pythondataclass设计以获得类型安全、自动__init__与干净的序列化能力。整个模块共 565 行定义了 5 个数据类和 1 个管理类。1. Capability能力声明dataclass class Capability: name: str description: str tags: List[str] field(default_factorylist) version: Optional[str] None def to_dict(self) - Dict[str, Any]: return asdict(self)tags用于能力检索与过滤如[math, calculations]version用于能力级版本管理。2. Constraint限制声明dataclass class Constraint: type: str # 例如 access、resource、security description: str severity: str high # low / medium / highseverity字段会在后续的兼容性校验中被读取高严重度约束会触发validate_compatibility()的告警相当于给编排器一个此 Agent 受限较大的信号。3. IOContract输入输出契约dataclass class IOContract: input_schema: Dict[str, Any] output_schema: Dict[str, Any] examples: List[Dict[str, Any]] field(default_factorylist)input_schema与output_schema直接复用 JSON Schema 风格的字典结构type、properties、required、enum等这使得 OAD 与既有 API 工具链天然兼容examples提供可执行的示例对方便下游消费方理解与测试。4. TrustScore真实性能指标dataclass class TrustScore: success_rate: float # 0.0 ~ 1.0 avg_latency_ms: Optional[float] None total_executions: int 0 last_updated: str field(default_factorylambda: datetime.now().isoformat()) metrics: Dict[str, Any] field(default_factorydict)metrics是开放扩展点可放入任意自定义指标例如默认清单中的code_compilation_rate、task_completion_rate、user_satisfaction等。5. AgentMetadata清单容器dataclass class AgentMetadata: agent_id: str name: str version: str description: str capabilities: List[Capability] field(default_factorylist) constraints: List[Constraint] field(default_factorylist) io_contract: Optional[IOContract] None trust_score: Optional[TrustScore] None metadata: Dict[str, Any] field(default_factorydict) created_at: str field(default_factorylambda: datetime.now().isoformat()) updated_at: str field(default_factorylambda: datetime.now().isoformat())容器暴露的领域方法均在每次变更时刷新updated_atadd_capability(name, description, tagsNone, versionNone)add_constraint(type, description, severityhigh)set_io_contract(input_schema, output_schema, examplesNone)set_trust_score(success_rate, avg_latency_msNone, total_executions0, metricsNone)update_trust_score(success, latency_msNone)核心动态指标更新逻辑to_dict()/to_json(indent2)/from_dict()/from_json()完整序列化链路6. AgentMetadataManager清单生命周期管理AgentMetadataManager负责清单的加载、保存与发布默认清单文件名为agent_manifest.jsonload_manifest()从磁盘读取文件不存在或 JSON 损坏时返回Nonesave_manifest(metadata)写入磁盘indent2 的可读 JSONcreate_manifest(agent_id, name, version, description)内存中新建get_manifest()若内存为空则自动触发load_manifest()publish_manifest()返回{status: published, manifest: {...}, published_at: ISO时间戳}——在生产系统中此方法应对接市场或注册中心discover_agents(capability_filterNone)按能力过滤的发现接口当前为演示级 mock 实现会返回当前清单中能力名列表validate_compatibility(other_manifest)与另一份清单做兼容性校验返回{compatible: bool, warnings: [...], errors: [...]}。validate_compatibility的现有逻辑可从 src/agent_metadata.py 查看做两件事一是对比本地output_schema与目标input_schema是否一致不一致给出 warning二是对本地的 high 严重度约束给出提示。源码注释也明确指出生产环境应替换为深度 schema 校验。7. 默认清单工厂create_default_manifest模块还提供create_default_manifest()工厂函数src/agent_metadata.py为示例中的自演化 Agent 生成开箱即用的完整清单包含4 项能力mathematical_calculations、time_queries、string_operations、self_improvement4 项约束无直接联网high、4096 token 上限medium、禁止任意 shell 命令high、执行期只读文件系统medium完整的 IO 契约输入为{query, user_id?, conversation_id?}query必填输出为{response, instructions_version, telemetry_emitted}并附带 2 条输入输出示例初始信任分success_rate0.95、avg_latency_ms1200.0以及编译通过率、任务完成率、用户满意度等扩展指标。这份默认清单的价值在于开箱即用任何 Agent 即使不手写元数据也能立即获得一份符合 OAD 格式的清单。Trust Score 动态更新真实指标而非营销话术OAD 设计的关键原则之一是信任分必须反映真实执行表现而非营销宣传。update_trust_score()采用**运行平均running average**算法total self.trust_score.total_executions current_rate self.trust_score.success_rate new_success_value 1.0 if success else 0.0 self.trust_score.success_rate (current_rate * total new_success_value) / (total 1) self.trust_score.total_executions 1 # 平均延迟同理(current_avg * total latency_ms) / (total 1)该算法在 tests/test_agent_metadata.py 中有精确断言初始success_rate0.5, total_executions2追加一次成功与一次失败延迟分别为 1000ms 与 2000ms后avg_latency_ms必须等于(1000*3 2000*1)/4 1250.0——这说明更新逻辑对历史权重的处理是可复现、可验证的。与 DoerAgent 的集成零改动获得 OAD 能力OAD 系统的价值在 src/agent.py 中通过DoerAgent得到了直接体现。DoerAgent新增了两个可选参数def __init__(self, ..., enable_metadata: bool True, # 默认开启 manifest_file: str agent_manifest.json):初始化时的集成流程src/agent.py若enable_metadataTrue创建AgentMetadataManager(manifest_file)尝试load_manifest()若磁盘上没有现成清单则调用create_default_manifest(agent_iddoer-agent, nameDoer Agent (Self-Evolving), version1.0.0)并保存——实现开箱即得 OAD若导入失败如缺少依赖打印警告并优雅降级enable_metadataFalse不影响 Agent 其余功能——体现可选集成、向后兼容的设计决策。每次run()执行结束后src/agent.pyAgent 会success not agent_response.startswith(Error) # 以Error开头视为失败 metadata self.metadata_manager.get_manifest() if metadata: metadata.update_trust_score(successsuccess, latency_mslatency_ms) self.metadata_manager.save_manifest(metadata)即每次执行都会把真实结果与延迟写回清单让 Trust Score 随使用持续演化。对外暴露的两个新方法get_metadata_manifest()返回AgentMetadata.to_dict()形式的完整清单src/agent.pypublish_manifest()委托给AgentMetadataManager.publish_manifest()在真实系统中将注册到市场或注册中心src/agent.py。完整清单的 JSON 形态一份发布态的 OAD 清单最终落地为agent_manifest.json其标准结构如下完整示例见 docs/OPENAGENT_DEFINITION.md{ agent_id: self-evolving-agent, name: Self-Evolving Agent, version: 1.0.0, description: A self-evolving AI agent..., capabilities: [ { name: mathematical_calculations, description: Can evaluate mathematical expressions, tags: [math, calculations], version: 1.0 } ], constraints: [ { type: resource, description: No direct internet access, severity: high } ], io_contract: { input_schema: { type: object, properties: { query: {type: string} } }, output_schema: { type: object, properties: { response: {type: string} } } }, trust_score: { success_rate: 0.95, avg_latency_ms: 1200.0, total_executions: 1547, metrics: { code_compilation_rate: 0.95 } } }JSON 作为统一交换格式的原因在 IMPLEMENTATION_SUMMARY_OAD.md 中被明确总结通用、人类可读、工具友好便于共享、解析并集成到既有系统。五种实战用法从单 Agent 到流水线用法 1带元数据的基础 Agentfrom agent import DoerAgent # Agent 自动发布 OAD 清单enable_metadata 默认为 True doer DoerAgent(enable_metadataTrue) # 获取清单 manifest doer.get_metadata_manifest() print(fAgent: {manifest[name]}) print(fTrust: {manifest[trust_score][success_rate]:.1%}) # 运行任务后信任分会自动更新 result doer.run(What is 10 20?)用法 2自定义元数据from agent_metadata import AgentMetadata, AgentMetadataManager # 创建自定义元数据 metadata AgentMetadata( agent_idcustom-agent, nameCustom Agent, version1.0.0, descriptionSpecialized agent ) metadata.add_capability(custom_feature, Does custom thing) metadata.add_constraint(resource, Custom limitation, high) # 保存并发布 manager AgentMetadataManager() manager.save_manifest(metadata) manager.publish_manifest()用法 3Agent 发现与选择# 按能力在市场中发现 Agent agents marketplace.search(capabilitypython_code_generation) # 按信任分比较选出最优 best max(agents, keylambda a: a.trust_score.success_rate) # 使用选中的 Agent result best.run(task)用法 4流水线组合# 加载各 Agent 清单 agent1 load_agent(data-fetcher) agent2 load_agent(data-transformer) agent3 load_agent(report-generator) # 校验 IO 兼容性output 应匹配下游 input validate_pipeline([agent1, agent2, agent3]) # 执行流水线 data agent1.run(url) transformed agent2.run(data) report agent3.run(transformed)组合场景的典型契约链docs/OPENAGENT_DEFINITION.md 中给出Data Fetcher 输出{data: [...], format: json}Data Transformer 输入{data: [...], format: ...}、输出{cleaned_data: [...], summary: {...}}Report Generator 输入{cleaned_data: [...], summary: {...}}、输出{report: ..., format: pdf}。由于每段的输入 Schema 恰好是上一段的输出 Schema这条链可以在运行时之前就被静态校验通过。运行演示与测试验证环境准备示例位于 examples/self-evaluating依赖极简见 requirements.txtpip install -r requirements.txt核心仅两个依赖openai1.0.0与python-dotenv1.2.2。若需以包方式安装可使用 setup.pypip install -e .要求 Python 3.8。测试验证单元测试无需 API Keypython tests/test_agent_metadata.py测试文件 tests/test_agent_metadata.py 共 497 行覆盖 19 个用例19/19 全部通过覆盖点包括✓ Capability、Constraint、IOContract、TrustScore 的创建与to_dict✓ AgentMetadata CRUD 操作✓ 添加能力与约束✓ 设置 IO 契约与信任分✓ 动态信任分更新含加权平均的精确断言✓ JSON 序列化/反序列化to_dict/from_dict、to_json/from_json✓ Manager 操作create、save、load、get 自动加载✓ 清单发布publish_manifest返回published状态✓ 兼容性校验validate_compatibility✓ 默认清单创建校验特定能力与约束的存在集成测试需要 API Keypython -c from agent import DoerAgent; ...验证 DoerAgent 元数据集成、清单创建与加载、信任分自动更新。演示示例python examples/example_agent_metadata.pyexample_agent_metadata.py 共 497 行串行演示 5 个场景基础清单创建为 GitHub Coder Agent 定义 3 项能力python_code_generation、git_operations、code_review、3 项约束access/resource/security 类型、带enum的 IO 契约与含code_compilation_rate等指标的信任分市场发现模拟 3 个候选 Agent按 python 能力关键字过滤出匹配项并展示信任分Agent 组合构建 Data Fetcher → Data Transformer → Report Generator 三段流水线用output_schema与input_schema的属性键做交集校验输出每段的兼容性结论信任分动态更新初始 success_rate0.80模拟 5 次成功 2 次失败后展示指标实时升降持久化保存默认清单到demo_manifest.json再用新 Manager 实例加载验证跨进程/跨上下文恢复。回归测试python tests/test_agent.py原有测试全部通过确认enable_metadata采用可选集成后未破坏既有代码——这正是设计决策中向后兼容、渐进采用的实证。五项关键设计决策IMPLEMENTATION_SUMMARY_OAD.md 总结了 OAD 实现中的五项关键决策其依据均可从源码中找到对应dataclass 设计类型安全、自动生成__init__、序列化干净结果就是健壮可维护、接口清晰的代码见 src/agent_metadata.py 的 6 个 dataclass/类。信任分自动更新信任分必须反映真实性能而非营销声明结果是每次执行后实时更新的指标见DoerAgent.run()末尾的更新代码。JSON 清单格式通用、可读、工具友好便于共享、解析、与既有系统集成。可选集成向后兼容、渐进采用enable_metadata默认开启但导入失败时优雅降级旧代码不受影响。默认清单创建降低使用摩擦、提供可运行示例Agent 开箱即得 OAD 能力create_default_manifestDoerAgent初始化自动落盘。使用场景与收益四个典型使用场景Agent 市场按能力搜索marketplace.search(capabilitypython_code_generation)、按信任分挑选最优max(results, keylambda a: a.trust_score.success_rate)、实例化使用多 Agent 编排加载 coder → reviewer → deployer 清单先validate_pipeline(...)再执行动态 Agent 选择按success_rate 0.90过滤可靠候选再按avg_latency_ms选出最快者契约强制Contract Enforcement消费方定义required_contract对 Agent 清单做validates_contract(agent_manifest.io_contract, required_contract)校验不满足则抛出ContractViolationError。五项核心收益可发现性Discoverability市场可按标准格式搜索与过滤无需猜测Agent 能力可组合性ComposabilityIO 契约保证 Agent 能协作运行时之前即可校验兼容性从而放心构建复杂流水线透明性Transparency能力与约束清晰声明性能指标真实可见标准化Standardization跨 Agent 的统一格式、平台无关协议是 Agent 生态的基础信任Trust真实指标而非营销话术动态更新、可客观对比。未来演进方向IMPLEMENTATION_SUMMARY_OAD.md 与 docs/OPENAGENT_DEFINITION.md 共同描绘了 OAD 的演进蓝图Agent 注册中心/市场清单的集中仓库、搜索与发现 API、Agent 版本管理与更新高级兼容性检查深度 schema 校验、自动适配器生成、兼容性评分计算Agent 认证验证能力声明、校验约束、对信任分做基准评测组合工具可视化流水线构建器、自动 Agent 选择、性能优化多 Agent 协议标准通信模式、Agent 协商协议、协作任务执行。总结OpenAgent Definition 在 agent-governance-toolkit 的 self-evaluating 示例 中已交付一套完整且经过测试的实现定义 Agent 能力与约束Capabilities / Constraints标准化 Agent 接口IO Contract支持 Agent 发现与组合Marketplace / Pipeline提供真实性能指标Trust Score 动态更新为 Agent 市场奠定基础。当前状态✅ 完整且已测试。原问题陈述中的全部需求均已落地——CapabilitiesCan-Do、ConstraintsWont-Do、IO Contract、Trust Score 四要素齐备19/19 测试通过、5 个示例可用、DoerAgent 零破坏集成。这套系统即为 AI Agent 提供的 USB 接口它让任何 Agent 都能以统一格式被描述、被发现、被组合、被审计也为平台方提供了构建 Agent 生态的标准基石。读者可以基于 src/agent_metadata.py 与 tests/test_agent_metadata.py 直接上手实践并结合 docs/OPENAGENT_DEFINITION.md 的完整规范继续深入。【免费下载链接】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 17:43:33 · 阅读 1.2k 用 OpenAgent Definition（OAD）为 AI Agent 定义标准接口：agent-governance-toolkit 元数据清单系统实战
用 OpenAgent DefinitionOAD为 AI Agent 定义标准接口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-toolkit 仓库中self-evaluating示例的 OpenAgent DefinitionOAD实现展开OAD 是一套面向 AI Agent 的接口定义语言IDL其定位类似 Swagger/OpenAPI 之于 REST API。文章会从问题动机、数据模型、DoerAgent 集成、测试验证、使用模式到未来演进完整讲解如何用 Capabilities、Constraints、IO Contract、Trust Score 四要素为 Agent 建立可发现、可组合、可信赖的标准接口。背景为什么 Agent 需要自己的 OpenAPI在传统的单体 Agent 时代开发者常被告知直接读 system prompt 就能知道 Agent 能做什么。 这在单个 Agent 的场景下尚可接受但当 Agent 生态走向市场化和规模化时这条路径立刻失效从市场Marketplace拉取一个专用 Agent例如 GitHub Coder 或 OpenAI Analyst时我们无法靠猜测来得知如何与它对话多个 Agent 需要协作时彼此的输入输出没有可校验的契约平台方无法对 Agent 的能力声明、性能表现进行客观比较与审计。这正是 OpenAgent DefinitionOAD要解决的问题。在 IMPLEMENTATION_SUMMARY_OAD.md 中OAD 被定义为 AI 的 USB 接口时刻——谁定义了标准 Agent 协议谁就赢得平台之争。其核心是要求生态中的每个 Agent 发布一份Metadata Manifest元数据清单包含四类信息要素含义示例CapabilitiesCan-DoAgent 能做什么我能编写 Python 3.9 代码我能解析 CSVConstraintsWont-DoAgent 不能/不会做什么我没有联网能力我有 4k token 上限IO Contract输入输出契约我接收 CodeContext 对象返回 Diff 对象Trust Score性能与可靠性指标我的代码编译通过率 95%数据模型dataclass 驱动的五类核心对象OAD 的完整实现位于 src/agent_metadata.py全部采用 Pythondataclass设计以获得类型安全、自动__init__与干净的序列化能力。整个模块共 565 行定义了 5 个数据类和 1 个管理类。1. Capability能力声明dataclass class Capability: name: str description: str tags: List[str] field(default_factorylist) version: Optional[str] None def to_dict(self) - Dict[str, Any]: return asdict(self)tags用于能力检索与过滤如[math, calculations]version用于能力级版本管理。2. Constraint限制声明dataclass class Constraint: type: str # 例如 access、resource、security description: str severity: str high # low / medium / highseverity字段会在后续的兼容性校验中被读取高严重度约束会触发validate_compatibility()的告警相当于给编排器一个此 Agent 受限较大的信号。3. IOContract输入输出契约dataclass class IOContract: input_schema: Dict[str, Any] output_schema: Dict[str, Any] examples: List[Dict[str, Any]] field(default_factorylist)input_schema与output_schema直接复用 JSON Schema 风格的字典结构type、properties、required、enum等这使得 OAD 与既有 API 工具链天然兼容examples提供可执行的示例对方便下游消费方理解与测试。4. TrustScore真实性能指标dataclass class TrustScore: success_rate: float # 0.0 ~ 1.0 avg_latency_ms: Optional[float] None total_executions: int 0 last_updated: str field(default_factorylambda: datetime.now().isoformat()) metrics: Dict[str, Any] field(default_factorydict)metrics是开放扩展点可放入任意自定义指标例如默认清单中的code_compilation_rate、task_completion_rate、user_satisfaction等。5. AgentMetadata清单容器dataclass class AgentMetadata: agent_id: str name: str version: str description: str capabilities: List[Capability] field(default_factorylist) constraints: List[Constraint] field(default_factorylist) io_contract: Optional[IOContract] None trust_score: Optional[TrustScore] None metadata: Dict[str, Any] field(default_factorydict) created_at: str field(default_factorylambda: datetime.now().isoformat()) updated_at: str field(default_factorylambda: datetime.now().isoformat())容器暴露的领域方法均在每次变更时刷新updated_atadd_capability(name, description, tagsNone, versionNone)add_constraint(type, description, severityhigh)set_io_contract(input_schema, output_schema, examplesNone)set_trust_score(success_rate, avg_latency_msNone, total_executions0, metricsNone)update_trust_score(success, latency_msNone)核心动态指标更新逻辑to_dict()/to_json(indent2)/from_dict()/from_json()完整序列化链路6. AgentMetadataManager清单生命周期管理AgentMetadataManager负责清单的加载、保存与发布默认清单文件名为agent_manifest.jsonload_manifest()从磁盘读取文件不存在或 JSON 损坏时返回Nonesave_manifest(metadata)写入磁盘indent2 的可读 JSONcreate_manifest(agent_id, name, version, description)内存中新建get_manifest()若内存为空则自动触发load_manifest()publish_manifest()返回{status: published, manifest: {...}, published_at: ISO时间戳}——在生产系统中此方法应对接市场或注册中心discover_agents(capability_filterNone)按能力过滤的发现接口当前为演示级 mock 实现会返回当前清单中能力名列表validate_compatibility(other_manifest)与另一份清单做兼容性校验返回{compatible: bool, warnings: [...], errors: [...]}。validate_compatibility的现有逻辑可从 src/agent_metadata.py 查看做两件事一是对比本地output_schema与目标input_schema是否一致不一致给出 warning二是对本地的 high 严重度约束给出提示。源码注释也明确指出生产环境应替换为深度 schema 校验。7. 默认清单工厂create_default_manifest模块还提供create_default_manifest()工厂函数src/agent_metadata.py为示例中的自演化 Agent 生成开箱即用的完整清单包含4 项能力mathematical_calculations、time_queries、string_operations、self_improvement4 项约束无直接联网high、4096 token 上限medium、禁止任意 shell 命令high、执行期只读文件系统medium完整的 IO 契约输入为{query, user_id?, conversation_id?}query必填输出为{response, instructions_version, telemetry_emitted}并附带 2 条输入输出示例初始信任分success_rate0.95、avg_latency_ms1200.0以及编译通过率、任务完成率、用户满意度等扩展指标。这份默认清单的价值在于开箱即用任何 Agent 即使不手写元数据也能立即获得一份符合 OAD 格式的清单。Trust Score 动态更新真实指标而非营销话术OAD 设计的关键原则之一是信任分必须反映真实执行表现而非营销宣传。update_trust_score()采用**运行平均running average**算法total self.trust_score.total_executions current_rate self.trust_score.success_rate new_success_value 1.0 if success else 0.0 self.trust_score.success_rate (current_rate * total new_success_value) / (total 1) self.trust_score.total_executions 1 # 平均延迟同理(current_avg * total latency_ms) / (total 1)该算法在 tests/test_agent_metadata.py 中有精确断言初始success_rate0.5, total_executions2追加一次成功与一次失败延迟分别为 1000ms 与 2000ms后avg_latency_ms必须等于(1000*3 2000*1)/4 1250.0——这说明更新逻辑对历史权重的处理是可复现、可验证的。与 DoerAgent 的集成零改动获得 OAD 能力OAD 系统的价值在 src/agent.py 中通过DoerAgent得到了直接体现。DoerAgent新增了两个可选参数def __init__(self, ..., enable_metadata: bool True, # 默认开启 manifest_file: str agent_manifest.json):初始化时的集成流程src/agent.py若enable_metadataTrue创建AgentMetadataManager(manifest_file)尝试load_manifest()若磁盘上没有现成清单则调用create_default_manifest(agent_iddoer-agent, nameDoer Agent (Self-Evolving), version1.0.0)并保存——实现开箱即得 OAD若导入失败如缺少依赖打印警告并优雅降级enable_metadataFalse不影响 Agent 其余功能——体现可选集成、向后兼容的设计决策。每次run()执行结束后src/agent.pyAgent 会success not agent_response.startswith(Error) # 以Error开头视为失败 metadata self.metadata_manager.get_manifest() if metadata: metadata.update_trust_score(successsuccess, latency_mslatency_ms) self.metadata_manager.save_manifest(metadata)即每次执行都会把真实结果与延迟写回清单让 Trust Score 随使用持续演化。对外暴露的两个新方法get_metadata_manifest()返回AgentMetadata.to_dict()形式的完整清单src/agent.pypublish_manifest()委托给AgentMetadataManager.publish_manifest()在真实系统中将注册到市场或注册中心src/agent.py。完整清单的 JSON 形态一份发布态的 OAD 清单最终落地为agent_manifest.json其标准结构如下完整示例见 docs/OPENAGENT_DEFINITION.md{ agent_id: self-evolving-agent, name: Self-Evolving Agent, version: 1.0.0, description: A self-evolving AI agent..., capabilities: [ { name: mathematical_calculations, description: Can evaluate mathematical expressions, tags: [math, calculations], version: 1.0 } ], constraints: [ { type: resource, description: No direct internet access, severity: high } ], io_contract: { input_schema: { type: object, properties: { query: {type: string} } }, output_schema: { type: object, properties: { response: {type: string} } } }, trust_score: { success_rate: 0.95, avg_latency_ms: 1200.0, total_executions: 1547, metrics: { code_compilation_rate: 0.95 } } }JSON 作为统一交换格式的原因在 IMPLEMENTATION_SUMMARY_OAD.md 中被明确总结通用、人类可读、工具友好便于共享、解析并集成到既有系统。五种实战用法从单 Agent 到流水线用法 1带元数据的基础 Agentfrom agent import DoerAgent # Agent 自动发布 OAD 清单enable_metadata 默认为 True doer DoerAgent(enable_metadataTrue) # 获取清单 manifest doer.get_metadata_manifest() print(fAgent: {manifest[name]}) print(fTrust: {manifest[trust_score][success_rate]:.1%}) # 运行任务后信任分会自动更新 result doer.run(What is 10 20?)用法 2自定义元数据from agent_metadata import AgentMetadata, AgentMetadataManager # 创建自定义元数据 metadata AgentMetadata( agent_idcustom-agent, nameCustom Agent, version1.0.0, descriptionSpecialized agent ) metadata.add_capability(custom_feature, Does custom thing) metadata.add_constraint(resource, Custom limitation, high) # 保存并发布 manager AgentMetadataManager() manager.save_manifest(metadata) manager.publish_manifest()用法 3Agent 发现与选择# 按能力在市场中发现 Agent agents marketplace.search(capabilitypython_code_generation) # 按信任分比较选出最优 best max(agents, keylambda a: a.trust_score.success_rate) # 使用选中的 Agent result best.run(task)用法 4流水线组合# 加载各 Agent 清单 agent1 load_agent(data-fetcher) agent2 load_agent(data-transformer) agent3 load_agent(report-generator) # 校验 IO 兼容性output 应匹配下游 input validate_pipeline([agent1, agent2, agent3]) # 执行流水线 data agent1.run(url) transformed agent2.run(data) report agent3.run(transformed)组合场景的典型契约链docs/OPENAGENT_DEFINITION.md 中给出Data Fetcher 输出{data: [...], format: json}Data Transformer 输入{data: [...], format: ...}、输出{cleaned_data: [...], summary: {...}}Report Generator 输入{cleaned_data: [...], summary: {...}}、输出{report: ..., format: pdf}。由于每段的输入 Schema 恰好是上一段的输出 Schema这条链可以在运行时之前就被静态校验通过。运行演示与测试验证环境准备示例位于 examples/self-evaluating依赖极简见 requirements.txtpip install -r requirements.txt核心仅两个依赖openai1.0.0与python-dotenv1.2.2。若需以包方式安装可使用 setup.pypip install -e .要求 Python 3.8。测试验证单元测试无需 API Keypython tests/test_agent_metadata.py测试文件 tests/test_agent_metadata.py 共 497 行覆盖 19 个用例19/19 全部通过覆盖点包括✓ Capability、Constraint、IOContract、TrustScore 的创建与to_dict✓ AgentMetadata CRUD 操作✓ 添加能力与约束✓ 设置 IO 契约与信任分✓ 动态信任分更新含加权平均的精确断言✓ JSON 序列化/反序列化to_dict/from_dict、to_json/from_json✓ Manager 操作create、save、load、get 自动加载✓ 清单发布publish_manifest返回published状态✓ 兼容性校验validate_compatibility✓ 默认清单创建校验特定能力与约束的存在集成测试需要 API Keypython -c from agent import DoerAgent; ...验证 DoerAgent 元数据集成、清单创建与加载、信任分自动更新。演示示例python examples/example_agent_metadata.pyexample_agent_metadata.py 共 497 行串行演示 5 个场景基础清单创建为 GitHub Coder Agent 定义 3 项能力python_code_generation、git_operations、code_review、3 项约束access/resource/security 类型、带enum的 IO 契约与含code_compilation_rate等指标的信任分市场发现模拟 3 个候选 Agent按 python 能力关键字过滤出匹配项并展示信任分Agent 组合构建 Data Fetcher → Data Transformer → Report Generator 三段流水线用output_schema与input_schema的属性键做交集校验输出每段的兼容性结论信任分动态更新初始 success_rate0.80模拟 5 次成功 2 次失败后展示指标实时升降持久化保存默认清单到demo_manifest.json再用新 Manager 实例加载验证跨进程/跨上下文恢复。回归测试python tests/test_agent.py原有测试全部通过确认enable_metadata采用可选集成后未破坏既有代码——这正是设计决策中向后兼容、渐进采用的实证。五项关键设计决策IMPLEMENTATION_SUMMARY_OAD.md 总结了 OAD 实现中的五项关键决策其依据均可从源码中找到对应dataclass 设计类型安全、自动生成__init__、序列化干净结果就是健壮可维护、接口清晰的代码见 src/agent_metadata.py 的 6 个 dataclass/类。信任分自动更新信任分必须反映真实性能而非营销声明结果是每次执行后实时更新的指标见DoerAgent.run()末尾的更新代码。JSON 清单格式通用、可读、工具友好便于共享、解析、与既有系统集成。可选集成向后兼容、渐进采用enable_metadata默认开启但导入失败时优雅降级旧代码不受影响。默认清单创建降低使用摩擦、提供可运行示例Agent 开箱即得 OAD 能力create_default_manifestDoerAgent初始化自动落盘。使用场景与收益四个典型使用场景Agent 市场按能力搜索marketplace.search(capabilitypython_code_generation)、按信任分挑选最优max(results, keylambda a: a.trust_score.success_rate)、实例化使用多 Agent 编排加载 coder → reviewer → deployer 清单先validate_pipeline(...)再执行动态 Agent 选择按success_rate 0.90过滤可靠候选再按avg_latency_ms选出最快者契约强制Contract Enforcement消费方定义required_contract对 Agent 清单做validates_contract(agent_manifest.io_contract, required_contract)校验不满足则抛出ContractViolationError。五项核心收益可发现性Discoverability市场可按标准格式搜索与过滤无需猜测Agent 能力可组合性ComposabilityIO 契约保证 Agent 能协作运行时之前即可校验兼容性从而放心构建复杂流水线透明性Transparency能力与约束清晰声明性能指标真实可见标准化Standardization跨 Agent 的统一格式、平台无关协议是 Agent 生态的基础信任Trust真实指标而非营销话术动态更新、可客观对比。未来演进方向IMPLEMENTATION_SUMMARY_OAD.md 与 docs/OPENAGENT_DEFINITION.md 共同描绘了 OAD 的演进蓝图Agent 注册中心/市场清单的集中仓库、搜索与发现 API、Agent 版本管理与更新高级兼容性检查深度 schema 校验、自动适配器生成、兼容性评分计算Agent 认证验证能力声明、校验约束、对信任分做基准评测组合工具可视化流水线构建器、自动 Agent 选择、性能优化多 Agent 协议标准通信模式、Agent 协商协议、协作任务执行。总结OpenAgent Definition 在 agent-governance-toolkit 的 self-evaluating 示例 中已交付一套完整且经过测试的实现定义 Agent 能力与约束Capabilities / Constraints标准化 Agent 接口IO Contract支持 Agent 发现与组合Marketplace / Pipeline提供真实性能指标Trust Score 动态更新为 Agent 市场奠定基础。当前状态✅ 完整且已测试。原问题陈述中的全部需求均已落地——CapabilitiesCan-Do、ConstraintsWont-Do、IO Contract、Trust Score 四要素齐备19/19 测试通过、5 个示例可用、DoerAgent 零破坏集成。这套系统即为 AI Agent 提供的 USB 接口它让任何 Agent 都能以统一格式被描述、被发现、被组合、被审计也为平台方提供了构建 Agent 生态的标准基石。读者可以基于 src/agent_metadata.py 与 tests/test_agent_metadata.py 直接上手实践并结合 docs/OPENAGENT_DEFINITION.md 的完整规范继续深入。【免费下载链接】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），仅供参考