# 智能体产物对象

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

智能体产物使用artifact_id与version定位，文件使用file_id，挂载使用placement_id与volume_id。读取版本后继续保留完整引用。

<span id="prepare"></span>

## 调用前准备

从同一环境取得产品API基地址、个人访问令牌、工作区ID和卷访问范围。示例使用BASE_URL、MOI_KEY、WORKSPACE_ID；BASE_URL已包含产品前缀。ARTIFACT_ID和ARTIFACT_VERSION来自列表，不从文件名、下载URL或消息中的其他ID重建。

列表、版本读取、解析和回填使用volume.read集合过滤，批量删除使用volume.write集合过滤。父卷、当前挂载和来源生命周期仍影响结果，身份认证或知道file_id不能替代卷授权。

<span id="responses"></span>

## 版本详情

以下字段在当前HTTP DTO中均有键；来源不可见时，部分来源字段返回空字符串或0，不因空值解释为文件不存在。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `workspace_id` | string | 产物所属工作区。 |
| `artifact_id` | string | 产物ID。 |
| `version` | integer | 正整数版本。 |
| `artifact_kind` | string | 产物类型，示例为file。 |
| `status` | string | processing/completed/failed/deleted/expired；当前详情只选择completed。 |
| `file_id` | string | 当前关联文件ID。 |
| `placement_id` | integer | 当前权限范围内选定的Catalog文件挂载记录。 |
| `volume_id` | integer | 该挂载所属卷。 |
| `file_path`、`file_name` | string | 当前挂载中的路径与文件名。 |
| `content_type` | string | 文件MIME类型。 |
| `file_category` | string | image/document/spreadsheet/audio/video/archive/other。 |
| `size` | integer | 文件字节数。 |
| `md5` | string | 当前文件MD5。 |
| `agent_workspace_id`、`agent_id` | string | 来源智能体的定义工作区和ID。 |
| `agent_name` | string | 可解析的来源智能体显示名称；无法解析时可为空。 |
| `conversation_id`、`conversation_title` | string | 可向当前用户展示的来源会话ID及标题。 |
| `task_id` | string | 可展示的来源任务ID。 |
| `call_id`、`tool_id` | string | 可展示的来源调用和工具标识。 |
| `created_by`、`creator_name` | string | 文件创建者及可解析显示名称。 |
| `source_event_id`、`source_event_seq` | string、integer | 可展示的来源事件标识与序号。 |
| `generated_at` | string | 产物生成时间，RFC3339Nano。 |
| `created_at`、`updated_at` | string | 记录创建/更新时间，RFC3339Nano。 |

产物读取会按稳定file_id解析当前可读卷中的挂载，取确定的最新挂载记录；文件移动或改名后，返回位置可变化。产物version不等于挂载版本，不能保存旧placement_id后一直假设有效。

## 列表对象

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items` | array（版本详情数组） | 当前页产物版本。 |
| `total` | integer | 当前可访问及筛选条件下的记录总数。 |
| `page`、`page_size` | integer | 当前页码与页大小，默认1和10。 |
| `snapshot_at` | string | 本请求的快照时间，RFC3339Nano；没有跨页传回该值的输入。 |
| `agent_sources` | array（来源引用数组） | agent_workspace_id/agent_id候选。 |
| `creator_sources` | array（创建者候选数组） | created_by/creator_name候选，名称未解析时可为空。 |

候选来源来自筛选基线，范围可大于本页items；created_by候选在应用自身筛选前收集，agent候选在应用自身筛选前收集。部分隐藏系统智能体不进入来源候选，其产物行仍可列出。候选缺少某项不能直接证明没有该产物。

## 批量引用与逐项结果

每项输入为 `{"artifact_id":"artifact-example","version":1}`。两个标识来自同一次读取；不会用省略version表示最新版本。

删除返回succeeded引用数组及failed数组。解析返回items和failed；解析项包含artifact_id、version、file_id、volume_id、placement_id、file_name、content_type、size、status。failed项包含artifact_id、version、reason，HTTP200不代表每项成功。

## 回填统计

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `scanned` | integer | 所选范围内本次取出的候选数。 |
| `inserted` | integer | 实际新增记录数；dry_run时为0。 |
| `skipped` | integer | 跳过数；dry_run时等于scanned，含义与实际执行时不同。 |
| `failed` | integer | 逐候选写入失败计数；整体失败仍可能返回HTTP错误。 |
| `dry_run` | boolean | 本次是否仅检查候选。 |
