---
orphan: true
---

# Load the agent package

Verify and load the `.moiagent` agent package into the target workspace.

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

## Before you call

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, passed through `X-Workspace-ID` Header.
- `$PACKAGE_FILE`: Local `.moiagent` agent package path, uploaded in binary request body.

## Request example

```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"
```

## Successful response

Returns `201`, load plan, and loaded agent version on success.

```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"
    }
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` on success. |
| `data.plan` | object | Agent package loading plan. |
| `data.plan.workspace_id` | string | Target workspace ID. |
| `data.plan.agent_id` | string | Agent ID. |
| `data.plan.agent_version` | string | The agent version declared in the package. |
| `data.plan.source_digest` | string | Summary of package contents. |
| `data.plan.resource_files` | object | List of resource files in the package. |
| `data.plan.status` | string | Load plan status. |
| `data.plan.diagnostics` | array | Diagnostic information; does not return when no diagnosis is generated. |
| `data.version` | object | The loaded agent version. |
| `data.version.agent_id` | string | The agent ID to which the loaded version belongs. |
| `data.version.version` | string | The loaded version identifier. |
| `data.version.source_digest` | string | A summary of the version's package contents. |
| `data.version.min_moi_version` | string | Minimum MOI version required by the package. |
| `data.version.manifest` | object | Package list. |
| `data.version.status` | string | Loaded version status. |
| `data.version.diagnostics` | array | Version diagnostic information; does not return when no diagnosis is generated. |
| `data.version.loaded_by` | string | The user ID who loaded this version. |
| `data.version.loaded_at` | string | Loading time. |

## Error response

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