> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通用数据结构

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

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

## Metadata 对象

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

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

示例：

```json theme={null}
{
  "team": "docs",
  "project": "cloud-agents"
}
```

## 分页列表

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

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

## 错误信封

错误响应使用以下结构：

```json theme={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 前缀 |

## 下一步

<CardGroup cols={2}>
  <Card title="概览" icon="rocket" href="/zh/cloud-agents/overview">
    了解 Qoder Cloud Agents 的整体架构。
  </Card>
</CardGroup>