---
orphan: true
---

# 加载智能体包

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

验证并加载 `.moiagent` 智能体包到目标工作区。

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agent-packages/load
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和要加载的 `.moiagent` 包文件。


## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-packages/load" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary "@$PACKAGE_FILE"
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `package_file` | binary | 是 | 要加载的 `.moiagent` 包文件内容。 |

:::
::::
:::::
::::::
:::::::

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-packages/load" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary "@$PACKAGE_FILE"
```

:::::
:::::{tab-item} 参数说明

::::{tab-set}
:::{tab-item} 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 加载目标工作区的 ID。 |

:::
::::
:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "plan": {
      "workspace_id": "ws_01",
      "agent_id": "agent_01",
      "agent_version": "1.0.0",
      "source_digest": "sha256:...",
      "status": "validated"
    },
    "version": {
      "agent_id": "agent_01",
      "version": "1.0.0",
      "status": "runnable"
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

成功时返回 `201`、加载计划和已加载的智能体版本。

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 0。 |

:::
:::{tab-item} 响应数据

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.plan` | object | 智能体包加载计划。 |
| `data.version` | object | 已加载的智能体版本。 |

:::
:::{tab-item} `plan` 配置

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.plan.workspace_id` | string | 目标工作区 ID。 |
| `data.plan.agent_id` | string | 智能体 ID。 |
| `data.plan.agent_version` | string | 包中声明的智能体版本。 |
| `data.plan.source_digest` | string | 包内容摘要。 |
| `data.plan.resource_files` | object | 包中资源文件的清单。 |
| `data.plan.status` | string | 加载计划状态。 |
| `data.plan.diagnostics` | array | 诊断信息；未产生诊断时不返回。 |

:::
:::{tab-item} `version` 配置

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.version.agent_id` | string | 已加载版本所属的智能体 ID。 |
| `data.version.version` | string | 已加载的版本标识。 |
| `data.version.source_digest` | string | 版本的包内容摘要。 |
| `data.version.min_moi_version` | string | 包要求的最低 MOI 版本。 |
| `data.version.manifest` | object | 包清单。 |
| `data.version.status` | string | 已加载版本状态。 |
| `data.version.diagnostics` | array | 版本诊断信息；未产生诊断时不返回。 |
| `data.version.loaded_by` | string | 加载该版本的用户 ID。 |
| `data.version.loaded_at` | string | 加载时间。 |

:::
::::
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 2,
  "message": "invalid agent package"
}
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 错误字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 错误代码。 |
| `message` | string | 错误说明。 |

:::
::::
:::::
::::::
:::::::