通用数据结构

Cloud Agents API 多个资源共用的响应信封与基础对象。

本页说明跨资源复用的数据结构。各资源自己的对象结构在对应 API 子目录的“数据结构”页面中说明。

​

Metadata 对象

metadata 是调用方自定义的扁平字符串键值对象。

规则	说明
结构	JSON object，所有 value 都必须是 string
最大键数量	16
key 最大长度	64 个 Unicode 字符
value 最大长度	512 个 Unicode 字符
默认值	省略时为 {}

示例：

{
  "team": "docs",
  "project": "cloud-agents"
}

​

分页列表

列表接口返回统一的游标分页信封。

字段	类型	说明
data	array	当前页的资源对象数组
has_more	boolean	是否还有更多数据
first_id	string | null	当前页第一条记录的游标 ID；data 为空时为 null
last_id	string | null	当前页最后一条记录的游标 ID；data 为空时为 null

​

错误信封

错误响应使用以下结构：

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'name' is required."
  }
}

字段	类型	说明
type	string	固定为 "error"
error.type	string	错误类别，如 invalid_request_error、authentication_error、permission_error、not_found_error、conflict_error、api_error
error.message	string	人类可读的错误信息

​

时间戳

时间字段是 UTC 的 ISO 8601 / RFC 3339 字符串，例如 "2026-05-18T15:26:39.61669Z"。部分字段可以为 null，具体以各资源结构说明为准。

​

ID 前缀

资源	前缀
Agent	agent_
Environment	env_
Session	sess_
Session event	evt_
Session thread	sthr_
Turn	turn_
File	file_
Vault	vault_
Vault credential	vcred_
Skill	skill_
Memory store	memstore_
Memory entry	mem_
Memory version	memver_
Work item	work_
Forward template	tmpl_
Forward identity	idn_
Forward identity config	cfg_
Forward channel	channel_
Forward QR session	qr_
Forward schedule	sched_
Forward schedule run	srun_
Forward resource	复用已注册资源自身的 ID 前缀

​

下一步

概览

了解 Qoder Cloud Agents 的整体架构。