通用数据结构

本页说明跨资源复用的数据结构。各资源自己的对象结构在对应 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 的整体架构。

快速上手

构建 Agent

配置 Agent 环境

委派任务给 Agent

管理 Agent 上下文

最佳实践

API 参考

通用数据结构

Metadata 对象

分页列表

错误信封

时间戳

ID 前缀

下一步

概览

​Metadata 对象

​分页列表

​错误信封

​时间戳

​ID 前缀

​下一步

概览

Metadata 对象

分页列表

错误信封

时间戳

ID 前缀

下一步