文档首页/ 智果（AgentArts）智能体平台/ API参考/ API/ Managed Agents/ 环境/ 创建环境 - CreateCoreEnvironment
更新时间：2026-11-04 GMT+08:00
查看PDF
分享

创建环境 - CreateCoreEnvironment

功能介绍

创建一个新的环境实例。支持配置入网网关、出网配置和SessionStorage开关。

适用场景：

创建一个运行环境配置，定义入网网关ID、出网网络、SessionStorage开关。

创建后的环境可被多个智能体引用，实现环境配置复用。

架构说明：

环境与智能体正交解耦，环境定义"智能体在哪里跑"，智能体定义"智能体做什么"。

约束限制：

  • 环境可复用，可被多个智能体引用。

  • 未关联到智能体的环境支持修改。

  • 已关联到智能体的环境禁止修改。

  • 不支持版本。

调用方法

请参见如何调用API。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

agentarts:environment:createCoreEnvironment

Write

environment *

-

-

-

-

  • g:RequestTag/<tag-key>

  • g:TagKeys

URI

POST /v1/core/environments

请求参数

表1 请求Body参数

参数

是否必选

参数类型

描述

name

是

String

参数解释：

环境名称。

约束限制：

同一账号下名称不可重复。

取值范围：

长度为2-48个字符，可包含中文、字母、数字、下划线和中划线。

默认取值：

不涉及。

description

否

String

参数解释：

环境描述信息。

约束限制：

不涉及。

取值范围：

长度为0-4096个字符。

默认取值：

不涉及。

network_config

否

EnvironmentNetworkConfig object

参数解释：

网络配置。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

storage_config

否

EnvironmentStorageConfig object

参数解释：

环境存储配置，控制SFSTurbo挂载、Session存储和OBS挂载。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表2 EnvironmentNetworkConfig

参数

是否必选

参数类型

描述

network_mode

否

String

参数解释：

网络模式。

约束限制：

不涉及。

取值范围：

允许的值为：

  • PUBLIC：表示公网出口。

  • VPC：表示虚拟私有云出口。

默认取值：

PUBLIC

vpc_config

否

vpc_config object

参数解释：

VPC配置。network_mode为VPC时必填；network_mode为PUBLIC时忽略此字段（若传递返回400错误）。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表3 vpc_config

参数

是否必选

参数类型

描述

vpc_id

是

String

参数解释：

VPCID，可以通过VPC查询接口获取。

约束限制：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

默认取值：

不涉及。

subnet_id

是

String

参数解释：

子网ID，可以通过子网查询接口获取。

约束限制：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

默认取值：

不涉及。

security_group_ids

否

Array of strings

参数解释：

VPC关联的安全组ID列表，元素个数0-10个，每个安全组值的长度为1-36个字符。可以通过安全组查询接口获取。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表4 EnvironmentStorageConfig

参数

是否必选

参数类型

描述

sfs_turbo

否

Array of sfs_turbo objects

参数解释：

SFSTurbo存储挂载配置列表。

约束限制：

最多支持5个SFSTurbo挂载点。

取值范围：

不涉及。

默认取值：

不涉及。

session_storage

否

session_storage object

参数解释：

会话存储挂载配置。未配置时不提供Session临时存储。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

obs_bucket

否

Array of obs_bucket objects

参数解释：

OBS桶存储挂载配置列表。

约束限制：

最多支持5个OBS桶，10个挂载配置（每个桶可挂载多次）。

取值范围：

不涉及。

默认取值：

不涉及。
表5 sfs_turbo

参数

是否必选

参数类型

描述

sfs_turbo_id

是

String

参数解释：

SFSTurbo实例ID。可以通过SFSTurbo控制台或SFS查询接口获取。

约束限制：

不涉及。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

默认取值：

不涉及。

sfs_path

否

String

参数解释：

SFSTurbo存储的目录路径。

约束限制：

若有值则必须以'/'开头，不能包含'..'。

取值范围：

长度为0-4096个字符。

默认取值：

/

user_id

否

Long

参数解释：

挂载目录的用户ID（UID）。

约束限制：

不涉及。

取值范围：

0-4294967295。

默认取值：

1000

group_id

否

Long

参数解释：

挂载目录的用户组ID（GID）。

约束限制：

不涉及。

取值范围：

0-4294967295。

默认取值：

1000

mount_path

是

String

参数解释：

挂载到运行时的目录路径。

约束限制：

不同挂载目录之间，禁止相同或存在包含关系。

取值范围：

必须为/home,/mnt,/data,/tmp，或上述目录的子目录，不能包含'..'。

默认取值：

不涉及。

read_only

否

Boolean

参数解释：

是否以只读方式挂载。

约束限制：

不涉及。

取值范围：

  • true：以只读方式挂载。

  • false：以读写方式挂载。

默认取值：

false
表6 session_storage

参数

是否必选

参数类型

描述

mount_path

否

String

参数解释：

会话存储挂载到运行时的目录路径。

约束限制：

一旦配置后不可关闭。必须为/home,/mnt,/data,/tmp，或上述目录的子目录。不能包含相对路径段（'.'或'..'），不同挂载目录之间，禁止相同或存在包含关系。

取值范围：

长度2-4000字符。

默认取值：

不涉及。

uid

否

Integer

参数解释：

会话存储目录的用户ID（UID）。

约束限制：

不涉及。

取值范围：

0-65535。

默认取值：

不涉及。

gid

否

Integer

参数解释：

会话存储目录的用户组ID（GID）。

约束限制：

不涉及。

取值范围：

0-65535。

默认取值：

不涉及。

umask

否

String

参数解释：

会话存储目录的umask权限掩码。

约束限制：

3-4位八进制数。

取值范围：

符合正则^[0-7]{3,4}$。

默认取值：

不涉及。

default_permissions

否

Boolean

参数解释：

是否使用默认权限。

约束限制：

不涉及。

取值范围：

  • true：使用默认权限。

  • false：不使用默认权限。

默认取值：

不涉及。
表7 obs_bucket

参数

是否必选

参数类型

描述

bucket_name

是

String

参数解释：

OBS桶名称。

约束限制：

仅支持小写字母、数字、中划线（-）、英文句号（.），禁止以英文句号（.）和中划线（-）开头或结尾。

取值范围：

3-63个字符。

默认取值：

不涉及。

bucket_path

否

String

参数解释：

桶内路径，即挂载OBS桶内的指定子路径。

约束限制：

可以为空，为空时挂载整个桶，若有值则必须以'/'开头，不能包含'..'。

取值范围：

0-1024个字符。

默认取值：

空字符串。

mount_path

是

String

参数解释：

挂载到运行时的目录路径。

约束限制：

必须为/home,/mnt,/data,/tmp，或上述目录的子目录。不能包含'..'。不同挂载目录之间，禁止相同或存在包含关系。

取值范围：

2-4000个字符。

默认取值：

不涉及。

read_only

否

Boolean

参数解释：

是否以只读方式挂载。

约束限制：

不涉及。

取值范围：

  • true：以只读方式挂载。

  • false：以读写方式挂载。

默认取值：

false

响应参数

状态码：201

表8 响应Body参数

参数

参数类型

描述

environment_id

String

参数解释：

环境唯一标识，由系统自动生成。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

name

String

参数解释：

环境名称。

取值范围：

长度为2-48个字符，可包含中文、字母、数字、下划线和中划线。

description

String

参数解释：

环境描述信息。

取值范围：

长度为0-4096个字符。

network_config

EnvironmentNetworkConfig object

参数解释：

网络配置。

取值范围：

不涉及。

storage_config

EnvironmentStorageConfig object

参数解释：

环境存储配置，控制SFSTurbo挂载、Session存储和OBS挂载。

取值范围：

不涉及。

associated_agents

Array of EnvironmentAgentBinding objects

参数解释：

关联到此环境的智能体列表，元素个数0-100个，列表非空时该环境禁止删除（返回409）。

取值范围：

不涉及。

created_at

String

参数解释：

创建时间，UTC时间格式，格式为YYYY-MM-DDTHH:mm:ssZ，由系统自动生成。

取值范围：

不涉及。

updated_at

String

参数解释：

更新时间，UTC时间格式，格式为YYYY-MM-DDTHH:mm:ssZ，由系统自动生成。

取值范围：

不涉及。
表9 EnvironmentNetworkConfig

参数

参数类型

描述

network_mode

String

参数解释：

网络模式。

取值范围：

允许的值为：

  • PUBLIC：表示公网出口。

  • VPC：表示虚拟私有云出口。

vpc_config

vpc_config object

参数解释：

VPC配置。network_mode为VPC时必填；network_mode为PUBLIC时忽略此字段（若传递返回400错误）。

取值范围：

不涉及。
表10 vpc_config

参数

参数类型

描述

vpc_id

String

参数解释：

VPCID，可以通过VPC查询接口获取。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

subnet_id

String

参数解释：

子网ID，可以通过子网查询接口获取。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

security_group_ids

Array of strings

参数解释：

VPC关联的安全组ID列表，元素个数0-10个，每个安全组值的长度为1-36个字符。可以通过安全组查询接口获取。

取值范围：

不涉及。
表11 EnvironmentStorageConfig

参数

参数类型

描述

sfs_turbo

Array of sfs_turbo objects

参数解释：

SFSTurbo存储挂载配置列表。

取值范围：

不涉及。

session_storage

session_storage object

参数解释：

会话存储挂载配置。未配置时不提供Session临时存储。

取值范围：

不涉及。

obs_bucket

Array of obs_bucket objects

参数解释：

OBS桶存储挂载配置列表。

取值范围：

不涉及。
表12 sfs_turbo

参数

参数类型

描述

sfs_turbo_id

String

参数解释：

SFSTurbo实例ID。可以通过SFSTurbo控制台或SFS查询接口获取。

取值范围：

匹配标准的UUID格式（8-4-4-4-12的十六进制数字串，由连字符分隔），例如0451ff49-3c47-4049-851c-51c23fe7fe69。

sfs_path

String

参数解释：

SFSTurbo存储的目录路径。

取值范围：

长度为0-4096个字符。

user_id

Long

参数解释：

挂载目录的用户ID（UID）。

取值范围：

0-4294967295。

group_id

Long

参数解释：

挂载目录的用户组ID（GID）。

取值范围：

0-4294967295。

mount_path

String

参数解释：

挂载到运行时的目录路径。

取值范围：

必须为/home,/mnt,/data,/tmp，或上述目录的子目录，不能包含'..'。

read_only

Boolean

参数解释：

是否以只读方式挂载。

取值范围：

  • true：以只读方式挂载。

  • false：以读写方式挂载。
表13 session_storage

参数

参数类型

描述

mount_path

String

参数解释：

会话存储挂载到运行时的目录路径。

取值范围：

长度2-4000字符。

uid

Integer

参数解释：

会话存储目录的用户ID（UID）。

取值范围：

0-65535。

gid

Integer

参数解释：

会话存储目录的用户组ID（GID）。

取值范围：

0-65535。

umask

String

参数解释：

会话存储目录的umask权限掩码。

取值范围：

符合正则^[0-7]{3,4}$。

default_permissions

Boolean

参数解释：

是否使用默认权限。

取值范围：

  • true：使用默认权限。

  • false：不使用默认权限。
表14 obs_bucket

参数

参数类型

描述

bucket_name

String

参数解释：

OBS桶名称。

取值范围：

3-63个字符。

bucket_path

String

参数解释：

桶内路径，即挂载OBS桶内的指定子路径。

取值范围：

0-1024个字符。

mount_path

String

参数解释：

挂载到运行时的目录路径。

取值范围：

2-4000个字符。

read_only

Boolean

参数解释：

是否以只读方式挂载。

取值范围：

  • true：以只读方式挂载。

  • false：以读写方式挂载。
表15 EnvironmentAgentBinding

参数

参数类型

描述

agent_id

String

参数解释：

关联的智能体ID，用于唯一标识一个智能体实例。具体参见查询智能体列表。

取值范围：

长度为0-128个字符。

agent_name

String

参数解释：

关联的智能体名称。

取值范围：

长度为0-64个字符。

状态码：400

表16 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000400表示客户端请求参数错误。

取值范围：

固定值：AgentArts.03000400。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

状态码：401

表17 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000401表示未授权（认证令牌缺失、无效或已过期）。

取值范围：

固定值：AgentArts.03000401。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

状态码：403

表18 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000403表示禁止访问（认证后权限不足）。

取值范围：

固定值：AgentArts.03000403。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

coded_authorization_message

String

参数解释：

当API无访问权限时报错信息。

取值范围：

长度为1-1024个字符。

details

Array of ManagedAgentErrorDetail objects

参数解释：

依赖的下游服务错误信息列表。

取值范围：

最小数量0，最大数量10。
表19 ManagedAgentErrorDetail

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

长度为18个字符。

error_msg

String

参数解释：

错误信息。

取值范围：

长度为1-1024个字符。

状态码：409

表20 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000409表示资源冲突。

取值范围：

固定值：AgentArts.03000409。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

状态码：429

表21 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000429表示请求过于频繁（触发限流）。

取值范围：

固定值：AgentArts.03000429。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

状态码：500

表22 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。枚举值说明：AgentArts.03000500表示服务器内部错误。

取值范围：

固定值：AgentArts.03000500。

error_msg

String

参数解释：

错误详细信息。

取值范围：

长度为1-512个字符。

请求示例

创建VPC网络环境

POST https://{Endpoint}/v1/core/environments

{
  "name" : "python-data-analysis",
  "description" : "生产环境VPC网络配置",
  "network_config" : {
    "network_mode" : "VPC",
    "vpc_config" : {
      "vpc_id" : "1a2ac6ec-c5ae-40f9-9677-bd73f37c0de5",
      "subnet_id" : "2e79ba05-8e10-41f6-9650-00fea3ca24cc",
      "security_group_ids" : [ "a6f126ca-cb81-4323-9597-72eee3de4439" ]
    }
  },
  "storage_config" : {
    "sfs_turbo" : [ {
      "sfs_turbo_id" : "a8f6b2e1-1111-1111-1111-123456789012",
      "sfs_path" : "/shared/knowledge_base",
      "mount_path" : "/mnt/kb",
      "read_only" : false
    } ],
    "session_storage" : {
      "mount_path" : "/mnt/sessions"
    },
    "obs_bucket" : [ {
      "bucket_name" : "test",
      "bucket_path" : "/",
      "mount_path" : "/home/test",
      "read_only" : false
    } ]
  }
}

响应示例

状态码：201

{
  "environment_id" : "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name" : "python-data-analysis",
  "description" : "生产环境VPC网络配置",
  "network_config" : {
    "network_mode" : "VPC",
    "vpc_config" : {
      "vpc_id" : "1a2ac6ec-c5ae-40f9-9677-bd73f37c0de5",
      "subnet_id" : "2e79ba05-8e10-41f6-9650-00fea3ca24cc",
      "security_group_ids" : [ "a6f126ca-cb81-4323-9597-72eee3de4439" ]
    }
  },
  "storage_config" : {
    "sfs_turbo" : [ {
      "sfs_turbo_id" : "a8f6b2e1-1111-1111-1111-123456789012",
      "sfs_path" : "/shared/knowledge_base",
      "mount_path" : "/mnt/kb",
      "read_only" : false
    } ],
    "session_storage" : {
      "mount_path" : "/mnt/sessions"
    },
    "obs_bucket" : [ {
      "bucket_name" : "test",
      "bucket_path" : "/",
      "mount_path" : "/home/test",
      "read_only" : false
    } ]
  },
  "associated_agents" : [ ],
  "created_at" : "2024-05-20T14:30:00Z",
  "updated_at" : "2024-05-20T14:30:00Z"
}

状态码

状态码

描述

201

创建成功，返回环境详细信息。

400

请求参数错误。

401

未授权（认证令牌缺失、无效或已过期）。

403

禁止访问（认证后权限不足）。

409

资源冲突（如环境名称已存在）。

429

请求过于频繁（触发限流）。

500

服务器内部错误。

错误码

请参见错误码。

父主题： 环境

相关文档