Identity And Versioning

标识符

以下标识符均为不透明字符串：

orgId
agentId
agentRevisionId
toolId
toolRevisionId
releaseChannelId
protocolBindingId
runId
runLinkId
attemptId
runSpaceId
threadId
messageId
artifactId
checkpointId
interactionId
sessionId
runtimeConnectionId
eventId

实现 MUST NOT 从标识符的编码形式推导业务语义。

唯一性范围

orgId 在平台全局唯一
agentId 在平台全局唯一
agentRevisionId 在平台全局唯一
toolId 在平台全局唯一
toolRevisionId 在平台全局唯一
releaseChannelId 在平台全局唯一
protocolBindingId 在平台全局唯一
runId 在平台全局唯一
runLinkId 在平台全局唯一
attemptId 在所属 runId 内唯一；推荐仍全局唯一
runSpaceId 在平台全局唯一
sessionId 在平台全局唯一
runtimeConnectionId 在平台全局唯一
interactionId 在所属 runId 内唯一；推荐仍全局唯一
event.sequence 在所属 runId 内严格单调递增且唯一
messageId、artifactId、checkpointId 在所属 runId 内唯一

版本字段

可变资源 SHOULD 维护 version
读模型 SHOULD 维护独立 version
InteractionRequest.version SHOULD 在 prompt、options、status 或 response 更新时递增
run 的事件流位置使用 eventSequence
webhook 与读模型幂等判断应优先使用 version 与 eventId
不可变 revision SHOULD NOT 原地修改；如实现保留 version，它只用于存储层并发保护，不改变 revision 身份

Cursor 规则

stream cursor MUST 能唯一定位到某个 run 内的消费位置
v1 标准 cursor 为：
- runId
- threadId（如按线程消费）
- sequence
cursor MUST 可被客户端持久化后用于 resume
服务端 MUST 接受“已消费到某个 sequence”的请求并从下一个事件继续输出

版本兼容

路径级 API 使用 /v1/...
schema 使用 https://agent-service.spec/v1/... 作为逻辑 $id
transport protocolVersion 与 API 版本号解耦
protocolProfiles.*.protocolVersion 表示外部协议能力档案版本，而不是 AaaS 资源模型版本
ProtocolBinding.protocolVersion 表示实际对外暴露的协议版本