Identity And Versioning

标识符

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

• orgId
• agentId
• toolId
• runId
• attemptId
• threadId
• messageId
• artifactId
• checkpointId
• sessionId
• eventId

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

唯一性范围

• orgId 在平台全局唯一
• agentId 在平台全局唯一
• toolId 在平台全局唯一
• runId 在平台全局唯一
• attemptId 在所属 runId 内唯一；推荐仍全局唯一
• event.sequence 在所属 runId 内严格单调递增且唯一
• messageId、artifactId、checkpointId 在所属 runId 内唯一

版本字段

• 可变资源 SHOULD 维护 version
• 读模型 SHOULD 维护独立 version
• run 的事件流位置使用 eventSequence
• webhook 与读模型幂等判断应优先使用 version 与 eventId

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 版本号解耦