Skip to content

CORE.md

Latest commit

 

History

History
403 lines (323 loc) · 21.2 KB

CORE.md

File metadata and controls

403 lines (323 loc) · 21.2 KB
Raw

AgentMeasure Core Specification — Open Measurement Standard for AI-Agent Software Usage（Standard Compatibility agentmeasure-0.4 · Document revision 0.4.5）

Draft 0.4：Measurement Objects & Verification Decoupling。 0.3 解决了"怎么算"； 0.4 解决"算的是什么"——把测量对象扩展为完整的 Software Entity → Capability → Interaction Surface 模型，补齐 decision → operation → attempt → result/effect → outcome 的端到端谱系， 并把 Core 与 Verification Profile 解耦。

参考实现（reference/）与标准文档同仓演进。AgentMeasure 不定义谁是真相来源， 而定义什么证据、按照什么规则，可以支持什么结论。

0. 版本与治理

  • 版本路线：Draft 0.2（框架）→ 0.3（语义）→ 0.4（对象与质量） → 0.5（价值测量）→ 1.0
  • 指标变更走 AUP（proposals/）；AgentMeasure Metrics 是变更最频繁的文档，whitepaper 保持稳定
  • 毕业标准（不变）：2 独立实现 + 3 profiles + 2 tool-side + conformance + vectors + 5-10 项目 + discrepancy report + 双 review

1. 核心命题（不变）

Reach → Choice → Use → Utility → Value。五问不变。

规范语言（BCP 14）：本规范及所有 AgentMeasure 文档中，MUST / MUST NOT / SHOULD / SHOULD NOT / MAY 按 RFC 2119（BCP 14）解释。实现必须满足全部 MUST； SHOULD 是强烈建议，偏离 MUST 在 Measurement Label 中披露。

2. Measurement Objects（Draft 0.4：实体化）

2.0 三层结构

测量对象分三层：

  1. Software Entity（存在的软件）——被度量的"谁"
  2. Capability（能做什么）——实体的具名功能
  3. Interaction Surface（怎么交互）——可观察的调用界面

观察发生在 Interaction Surface 上；统计归属到 Entity。 Observer 直接看到的是 surface，不一定知道 entity——entity 身份由 registry 的 alias 归并推导 （见 AgentMeasure Entity）。无法归并时，实体归属 MUST 记为 UNKNOWN，绝不猜测。

2.1 Software Entity（实体类型）

类型 定义 示例
Tool 可执行的具名功能单元 MCP tool、CLI 命令、SDK 函数
Skill 打包的能力包（过程 + 提示 + 工具） Agent Skill 文件、自定义 skill 包
API 网络服务接口 REST/GraphQL endpoint、第三方 API
Data Source 结构化数据访问 搜索引擎、向量库、知识库
Agent 可被其他 Agent 调用的子 Agent sub-agent、delegated agent
Application 端到端应用 以 UI/API 形态被使用的完整应用
Runtime Capability 运行时内置能力 文件编辑、Bash、Web Fetch
unknown 无法判定 —

实体身份规则：

  • 每个 Entity 有且仅有一个规范标识 entity_id（registry 权威，见 AgentMeasure Entity）
  • 同一逻辑软件的不同形态（MCP server / CLI / skill）由 registry alias 归并； alias 归并前的观察 MUST NOT 跨形态合并计数（不变量 21）

2.2 Capability

  • Capability = Entity 的具名功能；标识 capability_id（<entity_id>:<name>）
  • Category 是版本化的 measurement construct（category_id + category_version）， 建立在 Capability 之上，不是永久真理（AgentMeasure Taxonomy，Draft 0.4 立项）
  • 同一 Capability 可经多个 Interaction Surface 暴露

2.3 Interaction Surface

  • Surface = 具体可调用界面；标识 surface_id
  • 类型：mcp_tool · cli_command · http_endpoint · function_call · skill_file · plugin_hook · runtime_builtin · unknown
  • 观察发生在 surface 层；surface → entity 映射由 registry 提供（见 AgentMeasure Entity）

2.4 行为对象（决策 → 执行谱系）

对象 定义 关键标识
Task 一次任务单位（Agent 为之工作的目标） task_id
Decision Opportunity 一次工具选择决策 decision_id
Candidate Set 该次决策中真正可供选择的集合 candidate_set_id
Tool Presentation 某 selectable 出现在该 Candidate Set presentation_id
Selection Agent 选择某 selectable selection_id
Operation 对某 Capability 的一次逻辑使用（为某 task 而用） operation_id
Delegation Agent 将子目标连同执行权交给另一 Agent 的边界事件（Agent → Agent 调用）；与 Operation 同层，作为 Task 的直接子节点 delegation_id
Attempt 标准执行对象：一次实际执行（API request / MCP call / CLI execution / Agent-to-Agent call 统一映射为 Attempt）。不可变事实对象（Draft 0.4.4） attempt_id（agentmeasure 自有 identity；外部 id 见 external_ids）
Result / Effect 执行产生的返回值 / 世界状态改变 —
Outcome Task 或 Operation 的最终结果 —

完整谱系（同 harness 内一条链路；Delegation 跨越 harness 时产生新的子链路）：

Task ──▶ Decision Opportunity ──▶ Selection
                                      │
                                      ▼
                                  Operation ──▶ Attempt 1 ──▶ Result / Effect
                                      │             │  (retry)
                                      │             ▼
                                      │          Attempt 2 ──▶ Result / Effect
                                      │
                                 Delegation ──▶ [Sub-agent scope:
                                      │            Operation → Attempt …]
                                      ▼
                                  Outcome

Operation / Attempt 拆分（Draft 0.4.3 最终形态）：

  • Operation = 逻辑使用（"为任务 T 使用能力 C"），是 M3.1 的计数对象； M3.1 只计已解析的 operation，无回退（不变量 25）
  • Attempt = 标准执行对象；invocation 只作为外部协议的原始概念 （如 MCP invocation），标准内统一为 Attempt（旧命名见 LEGACY-MIGRATION.md）
  • 重试 = 同一 Operation 的多个 Attempt：关系通过 operation_id / retry_of
  • attempt_id 与 protocol/tool_call_id 分离（Draft 0.4.4）：attempt_id 是 AgentMeasure 自有 canonical identity；tool_call_id / protocol_call_id / trace_id 是 observation surface 提供的外部证据，放 external_ids，用于 correlation，不得与事实对象 identity 混用： 
    attempt_id: am-attempt-123
external_ids:
  protocol_call_id: call_789
  trace_id: trace_456
  • Attempt Ledger 不可变（Draft 0.4.4）：attempts 是 append-only 事实账本；reconciliation / aggregation / evaluation 不得改写或合并原始 attempt 记录（DR-001）。消费性事实（tokens / cost / cache）属于真正消费它的 attempt（DR-003）。
  • Operation 是 derived semantic grouping（Draft 0.4.4）：由 attempt 解析而来（declared / correlated / inferred / unresolved），不是与 attempt 同层的执行对象；解析必须携带 provenance （status / method / rule_id / rule_version，见 CORR §3.1）。 表达，不再属于 validity
  • 无 Operation 证据时，观察只能形成 Attempt；Operation 归并 MUST 遵循 AgentMeasure Correlation 的确定性规则（不变量 23：无证据不归并）

Delegation（Agent → Agent 调用，Draft 0.4.5）：

定义：Delegation 是第四种语义对象，与 Operation 同层、作为 Task 的直接子节点： 一个 Agent（delegating_caller）把子目标连同执行权交给另一个 Agent（called_agent）的 边界事件。它记录"谁、为何、向谁、多深"，不记录子侧执行细节。

Delegation 不是：

  • Operation：没有对子侧 Capability 的直接逻辑 intent 表达；
  • Attempt：执行发生在子 harness，不在父侧；
  • Task：它是父 Task 内部的一个步骤，不是新的用户级目标。

标识与字段

字段 必填 说明
delegation_id ✅ 委托方侧唯一标识（am-delegation-*）
delegating_caller ✅ 发起委托的 Agent entity_id
called_agent ✅ 被委托的 Agent entity_id
called_capability ✅ 被调用的被委托方 Capability（如 agent:accept_subtask）
parent_task_id ✅ 委托发生时的 task_id
depth ✅ 委托深度（顶层 = 0；子侧 depth = 父 depth + 1）
lineage ◻ 祖先链（delegation_id 序列）
subgoal ◻ 委托意图（prompt 摘要或 hash）
child_ref ◻ 子侧可关联标识（session_id / task_id）；跨侧 correlation 证据

计数纪律（Counting Discipline）

  1. Delegation 不进入 Operation Count 或 Attempt Count。Delegation 是独立计数对象， 新增指标 Delegations per Task、Delegation Depth Distribution。
  2. 一个 Delegation ≠ 一个 Operation。一个 Delegation 可能对应子侧的 0..N 个 Operation（子 harness 自行解析其 Operation 与 Attempt）；父侧不预测也不取代子侧计数。
  3. 计量图必须是 DAG。Delegation depth 有实现定义的上限（default MAX_DELEGATION_DEPTH）； 环状委托（A → B → A）MUST 被检测并拒绝。
  4. 计费归属：子侧 Attempt 的 cost 归属该 Attempt 本身（sum(attempts) = money 不变）； 父侧只聚合 cost，不重复计；aggregation MUST 标注为 aggregated。

跨侧跟踪（Cross-side Tracking）

  • Delegation 由委托方 harness 记录（只有委托方看得到决策上下文）； 被委托方按普通 Task / Operation / Attempt 记录自己的内部。
  • 跨侧关联至多 correlated（两个独立观察），永不声称为 corroborated （同一事件的重复确认）。
  • Delegation 的 outcome 是子侧 Task Outcome 的引用，证据等级 correlated； 父侧不得自行推断子任务成败。
  • 跨侧 cost attribution 由 lineage 追溯实现：父侧可聚合 sum(depth=N attempts.cost)， 但 attribution 声明 MUST 标注为 aggregated（非直接观测）。

与现有对象的关系

关系 说明
Task → Delegation Task 可包含 0..N 个 Delegation（以及 0..N 个 Operation）
Delegation → Operation（子侧） 子侧 Operation 由子侧 harness 独立记录，通过 child_ref 跨侧关联
Delegation → Attempt（子侧） 同上，跨侧关联
Delegation → Outcome Delegation Outcome 是子侧 Task Outcome 的 correlated 引用

2.5 Decision Authority（决策主体）

一次 Selection 由谁作出：

Authority 定义
model 模型自主选择
router 路由/编排层选择
workflow 预定义流程选择
user 用户直接指定
policy 策略/规则强制
platform 平台自动选择
unknown 无法判定

2.6 Selection Constraint（选择约束）

Constraint 定义
autonomous 完全自由选择
recommended 有推荐但可拒绝
required 必须使用（无替代）
user_requested 用户点名要求
fallback 作为回退被选
forced 被强制注入
unknown 无法判定

不变量：不同 authority / constraint 的 Selection 默认 MUST NOT 直接比较 Selection 类指标（或必须声明标准化方法）——required/forced 的"选择"不是偏好。

2.7 Interaction Classes（交互类别）

Capability 按交互性质分类，决定 Utility 的度量方式：

Class 定义 Result（返回值） Effect（世界改变）
Information 只读获取 返回数据 无（或上下文更新）
Action 对外部世界产生副作用 确认 / ack 状态改变
Transaction 多步原子操作 最终结果 全部或全无的状态改变
Computation 计算 / 处理 派生输出 无
Communication 消息 / 通知 投递确认 消息送达
Control 编排 / 控制流 后续执行指令 下游执行发生
Storage 持久化 写入确认 存储状态改变
Sensing 感知 / 输入 传感器数据 无
unknown 无法判定 — —

Result / Effect 双元 Utility（Draft 0.5 前置）：

  • Result = 能力返回的直接产物（可由 Consumption observation 观察）
  • Effect = 世界状态的实际改变（需要 Consumption 之外的验证）
  • Utility 指标 MUST 声明度量的是 Result 还是 Effect（不变量 22）

3. Measurement Grain（统计粒度）

Family Grain
Distribution Client / Client-Day
Choice Decision Opportunity
Execution Attempt（标准执行对象）
Delegation Delegation
Utility Result / Attempt
Outcome Task / Operation
Relationship Client × Project × Window

不变量：不同 Grain 的指标不可互换。 10 attempts ≠ 10 operations ≠ 10 delegations ≠ 10 decision opportunities ≠ 10 tasks。任何指标必须声明 Grain。

4. Observability States（可观测四态，不变）

观测结果不是二值。正式定义：

状态 含义
TRUE 确认发生
FALSE 有能力判断，并确认未发生
UNKNOWN 应该可以判断，但数据缺失/冲突
UNOBSERVABLE 当前 observation surface 根本无法观察

不变量：An unobservable outcome MUST NOT be interpreted as a negative outcome.

示例：Codex 的 Consumed 不可观察 → 记为 UNOBSERVABLE，不记 FALSE：

Consumption Rate = Consumed ÷ Consumption-observable eligible invocations

5. Metric Eligibility（指标资格，不变）

Qualified Usage ≠ Metric Eligible Sample。

  • Qualified Usage：这条数据是否值得统计的真实生产使用（Context × Validity × Policy）
  • Metric Eligibility：这条数据是否有资格进入这个具体指标的分母 （如：Presented 不可观察的 runtime 不进入 Observed Selection Rate 分母； Consumption 不可观察的不进入 Consumption Rate 分母）

6. Choice Mode、Decision Authority、Selection Constraint（三轴正交）

轴 回答 取值
Choice Mode 决策结构是什么 exclusive · multi_select · parallel · sequential · ordered_fallback · router_preselected · unknown
Decision Authority 谁作出决策 model · router · workflow · user · policy · platform · unknown
Selection Constraint 选择多自由 autonomous · recommended · required · user_requested · fallback · forced · unknown

不变量：不同 Choice Mode 默认不得直接比较 Observed Selection Rate / Share of Choice； authority 与 constraint 同样适用（不变量 24）。比较类指标 MUST 声明三轴。

7. Qualification：Context × Validity（不变）

Usage Context（数据来源环境）

production · development · test · benchmark · evaluation · synthetic · ci · demo · unknown

Attempt Validity（执行有效性，Draft 0.4.3 干净模型）

normal · duplicate · replay · health_check · load_test · suspected_invalid · unknown

retry 不是 validity：重试关系通过 operation_id / retry_of 表达 （LEGACY-MIGRATION.md 定义旧 validity=retry 值的迁移）。

Qualification Resolution（Attempt 级口径，Draft 0.4.3）

一次 Attempt 可有多条 observation（runtime + provider），各自带 context/validity。 Attempt 级口径由 collector 派生（derived_attempt_qualification）：

  • Attempt Context：全部一致取该值；部分 unknown 取最高权威已知值（partial）； 冲突（production vs test）→ inconsistent（不压平）
  • Attempt Validity：normal + unknown → partially_classified； normal + suspected_invalid → suspected_invalid（冲突保留）
  • 指标只查询派生列，禁止在统计 SQL 中临时 join 原始 observations 判定 （不变量 26）

口径定义

口径 组成 用途
Strict Qualified Usage production + validity=normal 公共 leaderboard / market metric 默认
Extended Observed Usage production + unknown 研究与内部诊断

同时公开：Unknown Context Share、Unknown Validity Share。 Unknown 默认不得进入 Strict 口径（避免"不知道是什么流量→报 unknown→进排行榜" 的激励漏洞）。

8. Measurement Label（Draft 0.4 补三轴与 grain 披露）

见 AgentMeasure Quality。每个指标除 label 外必须披露：Numerator / Denominator / Observable population / Qualified population / Runtime coverage / Choice mode （+ Draft 0.4：Decision authority / Selection constraint / Grain）。

9. 标准不变量（Draft 0.4 完整版）

  1. Same input + same policy = same result
  2. One invocation counted at most once
  3. Duplicate observations never increase counts
  4. Evidence never self-declared
  5. Unsigned fields never affect authenticated claims
  6. Ambiguous observations never promoted to corroborated
  7. unknown never inferred as success
  8. Metrics always declare scope + policy + window + grain + label
  9. Public observations never contain user content
  10. Corroboration never assumes different strings = independent control
  11. Platform attestation UNSUPPORTED until verified
  12. Outcome conflicts preserved (inconsistent)
  13. Qualified usage never mixes with benchmark/test/synthetic/CI
  14. Attribution claims never stated as causation
  15. Observed Selection Rate denominator = Presented, not Available
  16. Different grains are not interchangeable
  17. Unobservable MUST NOT be interpreted as negative
  18. Presentations count per Decision Opportunity（presentation ≠ decision）
  19. Different Choice Modes are not directly comparable
  20. Strict Qualified Usage excludes unknown context/validity
  21. Surface 观察未经 alias 归并 MUST NOT 跨形态合并计数
  22. Utility 指标 MUST 声明度量 Result 还是 Effect
  23. 无 Operation 证据时 MUST NOT 把 Attempt 归并为逻辑调用（fail-closed 归并）
  24. M3.1 Operation Count 只计已解析 operation；无 0.3 回退（legacy 数据提供 Legacy Attempt-equivalent Count，绝不命名为 Operation Count）
  25. Attempt 级 qualification 由派生列决定；禁止统计 SQL 临时 join 判定
  26. 不同 decision_authority / selection_constraint 默认 MUST NOT 直接比较 Selection 类指标
  27. Delegation MUST NOT 被压平为调用方的 Operation。 Delegation 是独立的语义对象， 不得计入 Operation Count 或 Attempt Count（不变量 27 的补充）。
  28. Delegation 计数必须在 delegating_caller 与 called_agent 两侧均可追溯。 跨侧关联至多 correlated，不得声称 corroborated。
  29. Delegation Outcome 是子侧 Task Outcome 的 correlated 引用。 父侧 MUST NOT 自行推断子任务成败。
  30. 计量图 MUST 是 DAG。 环状委托 MUST 被检测并拒绝；delegation depth 有实现定义的上限（default MAX_DELEGATION_DEPTH）。
  31. 子侧 Attempt 的 cost 归属该 Attempt 本身。 父侧聚合 MUST 标注为 aggregated。

10. 分层：Core 与 Verification Profile 解耦（Draft 0.4）

层 内容 门槛
Core（本文） Objects、Grain、Observability、Eligibility、Qualification、Lineage、不变量 采用前置（MUST 满足）
Data Observation Envelope schema 采用前置
Reporting Measurement Label / Policy / Profiles 采用前置（公开指标 MUST）
Verified Measurement Profile Ed25519 签名、Evidence Profile（单词显示等级）、Signed Observation（可选认证载体） 高级符合性，非采用前置
Bindings OTel / MCP / CLI 映射 随实现

不变量（P0-7）：验证是高级符合性，不是采用前置条件。 一个不签名的采集器 也能产生有效的 AgentMeasure 指标——只是证据等级为 observed（最低显示等级），MUST 在 Label 中声明。

11. 文档结构（Draft 0.4）

文档 负责
AgentMeasure Core（本文） Objects、Grain、Observability、Eligibility、Qualification、分层、不变量
AgentMeasure Entity Entity 身份、alias 归并、registry 格式（Draft 0.4 新增）
AgentMeasure Data Observation Envelope（六类型）schema
AgentMeasure Metrics Metric Registry + 指标合同（变更最频繁）
AgentMeasure Trust Principal、Signature、Trust Domain、Evidence（Verified Profile）
AgentMeasure Correlation Observation → Attempt → Operation 确定性规则
AgentMeasure Quality Context/Validity/Coverage/Observability/Label
AgentMeasure Privacy / SECURITY / BIND / PROFILES 不变
AgentMeasure Taxonomy Category/Capability 分类（Draft 0.4 立项）
extensions/COMMERCIAL.md 经济语义（Offering / Billable Unit / Metering Policy）——Experimental / Informative，非规范性，不参与 conformance
proposals/ 指标与规范变更提案（AUP）
proposals/2026-08-21-delegation-graph.md Delegation 对象提案与设计决策记录