加载智能体包

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

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-packages/load

调用前准备

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

• 创建新智能体：需要智能体创建权限。

• 更新已有智能体：需要智能体更新权限。

• 读取包内资源：需要关联卷和知识库的读取权限。

确认包中的资源引用有效。工作区访问权限不能替代关联资源的读取权限。

请求体

上传的智能体包正文上限为 128 MiB。超过上限或无法解析的包会被拒绝。客户端应保留原始包及失败信息，不能把失败响应当作没有产生加载记录。

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/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"

参数说明

路径参数

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

请求体

请求体为完整的 .moiagent 包文件二进制内容。使用 application/octet-stream 提交，不使用 JSON 对象或 package_file 字段封装文件内容。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "plan": {
      "workspace_id": "ws_01",
      "agent_id": "agent_01",
      "agent_version": "1.0.0",
      "source_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "resource_files": {},
      "status": "validated"
    },
    "version": {
      "workspace_id": "ws_01",
      "agent_id": "agent_01",
      "version": "1.0.0",
      "source_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "min_moi_version": "5.0.0",
      "manifest": {
        "schemaVersion": 1,
        "id": "agent_01",
        "version": "1.0.0",
        "name": "摘要助手",
        "model": "model-example",
        "instruction": {
          "path": "instructions/main.md"
        },
        "moiResourceRefs": {
          "tools": [],
          "skills": [],
          "knowledgeBases": [],
          "channelBindings": []
        }
      },
      "status": "runnable",
      "loaded_by": "user_01",
      "loaded_at": "2026-10-14T00:00:00Z"
    }
  }
}

字段说明

字段	类型	说明
code	integer	请求处理成功时为 0。
data	object	响应数据。
data.plan	object	智能体包加载计划。
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.resource_files.instruction	string	智能体指令。未设置时可省略。
data.plan.resource_files.custom_tool_dirs	string（字符串数组）	自定义工具目录。未设置时可省略。
data.plan.resource_files.custom_skill_dirs	string（字符串数组）	自定义技能目录。未设置时可省略。
data.plan.status	string	加载计划状态。
data.plan.diagnostics	object（对象数组）	诊断信息。未产生诊断时不返回。未设置时可省略。
data.plan.diagnostics[].severity	string	提示级别。取值：pending、error。
data.plan.diagnostics[].code	string	错误代码。
data.plan.diagnostics[].message	string	操作说明。
data.plan.diagnostics[].ref	string	资源引用。未设置时可省略。
data.version	object	已加载的智能体版本。
data.version.workspace_id	string	所属工作区 ID。
data.version.agent_id	string	已加载版本所属的智能体 ID。
data.version.version	string	已加载的版本标识。
data.version.foundation_ref	string	基础智能体版本引用。未设置时可省略。
data.version.source_digest	string	版本的包内容摘要。
data.version.min_moi_version	string	包要求的最低 MOI 版本。
data.version.manifest	object	包清单。
data.version.manifest.schemaVersion	integer	包清单结构版本。
data.version.manifest.id	string	对象 ID。
data.version.manifest.version	string	当前版本号。
data.version.manifest.name	string	名称。
data.version.manifest.description	string	说明。未设置时可省略。
data.version.manifest.model	string	关联模型。
data.version.manifest.model_config_ref	string	模型配置引用。未设置时可省略。
data.version.manifest.minMOIVersion	string	包要求的最低 MOI 版本。未设置时可省略。
data.version.manifest.instruction	object	智能体指令。
data.version.manifest.instruction.path	string	包内相对路径。
data.version.manifest.moiResourceRefs	object	关联的 MOI 资源引用。
data.version.manifest.moiResourceRefs.tools	object（对象数组）	发现的工具列表。
data.version.manifest.moiResourceRefs.tools[].name	string	名称。
data.version.manifest.moiResourceRefs.tools[].workspace_id	string	所属工作区 ID。未设置时可省略。
data.version.manifest.moiResourceRefs.skills	object（对象数组）	技能清单。
data.version.manifest.moiResourceRefs.skills[].name	string	名称。
data.version.manifest.moiResourceRefs.skills[].workspace_id	string	所属工作区 ID。未设置时可省略。
data.version.manifest.moiResourceRefs.knowledgeBases	object（对象数组）	关联知识库清单。
data.version.manifest.moiResourceRefs.knowledgeBases[].name	string	名称。
data.version.manifest.moiResourceRefs.knowledgeBases[].workspace_id	string	所属工作区 ID。未设置时可省略。
data.version.manifest.moiResourceRefs.catalogFiles	object（对象数组）	包内关联的 Catalog 文件。未设置时可省略。
data.version.manifest.moiResourceRefs.catalogFiles[].workspaceID	string	资源所在工作区 ID。
data.version.manifest.moiResourceRefs.catalogFiles[].volumeID	integer	卷 ID。
data.version.manifest.moiResourceRefs.catalogFiles[].fileID	string	关联文件 ID。
data.version.manifest.moiResourceRefs.channelBindings	object（对象数组）	通道绑定清单。
data.version.manifest.moiResourceRefs.channelBindings[].toolName	string	工具名称。未设置时可省略。
data.version.manifest.moiResourceRefs.channelBindings[].toolWorkspaceID	string	工具所在工作区 ID。未设置时可省略。
data.version.manifest.moiResourceRefs.channelBindings[].skillName	string	技能名称。未设置时可省略。
data.version.manifest.moiResourceRefs.channelBindings[].skillWorkspaceID	string	技能所在工作区 ID。未设置时可省略。
data.version.manifest.moiResourceRefs.channelBindings[].provider	string	提供商标识。未设置时可省略。
data.version.manifest.moiResourceRefs.channelBindings[].workspaceID	string	资源所在工作区 ID。
data.version.manifest.moiResourceRefs.channelBindings[].instanceID	string	通道实例 ID。
data.version.status	string	已加载版本状态。
data.version.diagnostics	object（对象数组）	版本诊断信息。未产生诊断时不返回。未设置时可省略。
data.version.diagnostics[].severity	string	提示级别。取值：pending、error。
data.version.diagnostics[].code	string	错误代码。
data.version.diagnostics[].message	string	操作说明。
data.version.diagnostics[].ref	string	资源引用。未设置时可省略。
data.version.loaded_by	string	加载该版本的用户 ID。
data.version.loaded_at	string	加载时间。
data.version.disabled_by	string	停用者标识。未设置时可省略。
data.version.disabled_at	string	停用时间。未设置时可省略。

错误响应

响应示例

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

字段说明

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

版本加载保存成功后，仍可能在操作记录写入阶段返回错误。遇到此类错误，先查询目标智能体和版本是否已存在，不要直接重复加载。

最后更新于 2026 年 10 月 19 日