文档中心

AgentKit

Sandbox Tool

CreateSession - 创建工具会话实例

创建工具的会话实例。

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：CreateSession

要执行的操作，取值：CreateSession。

Version string 必选示例值：2025-10-30

API的版本，取值：2025-10-30。

ToolId string 必选示例值：t-3tigy72q3u3vj0x2****

工具ID。

Envs.N.Key string[] 必选示例值：LOG_LEVEL

环境变量的Key（键）。

只能包含字母、数字、下划线，且只能以下划线字母开头。

长度限制为1 ~ 63个字符。

Ttl integer 可选示例值：1800

会话实例存活时长，即工具在一次 “用户 - 工具交互会话” 中，保持用户状态、操作上下文不丢失的有效时长。会话过期后，只需重新登录或重启操作即可。

单位：秒。

取值范围：60～86400。

默认值为：1800。

TosMountPoints.N.BucketName string[] 可选示例值：bucket01

TOS存储桶名称。

Envs.N.Value string[] 可选示例值：info

环境变量的值，长度限制为8192个字符。

TtlUnit string 可选示例值：second

会话实例存活时长的单位，取值：

minute：分。

second（默认）：秒。

TosMountPoints.N.BucketPath string[] 可选示例值：http://tos-cn-beijing.ivolces.com

TOS存储桶路径。

ImageInfo.Command string 必选示例值：python app.py

启动时执行的命令。

UserSessionId string 可选示例值：session01

用户会话信息。

支持大小写英文字母、数字、中划线（-）、下划线(_)。

长度限制为 0~200 个字符。

TosMountPoints.N.LocalMountPath string[] 可选示例值：/home/app

待挂载的工具实例本地目录。

ImageInfo.Image string 必选示例值：registry.example.com/my-app:v1.0.0

镜像的完整 URL，包含镜像的版本号。

ImageInfo.Port integer 必选示例值：8080

镜像对外暴露的端口号（整数）。

Metadata.N.Key string[] 必选示例值：env

元数据的标签键，如env、version等自定义标识。

参数 - N：表示标签Key的序号，取值范围：1～10。

单个Key的长度限制为128个字符。

多个字段名之间用&分隔，且不可重复。

Metadata.N.Type string[] 可选示例值：String

元数据的标签类型，用于声明标签值（Value）的数据类型，如String、Int等。

参数 - N：表示标签类型的序号，取值范围：1～10。

多个字段名之间用&分隔。

Metadata.N.Value string[] 可选示例值：production

元数据的标签值。

参数 - N：表示标签值的序号，取值范围：1～10。

单个值的长度限制为 256个字符，多个字段名之间用&分隔。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

Endpoint string 示例值：https://sd391h67itqkq7brr****.apigateway-cn-beijing.volceapi.com

会话公网访问端点。

InternalEndpoint string 示例值：https://sd391h67itqkq7brr****.apigateway-cn-beijing-inner.volceapi.com

会话私网访问端点。

SessionId string 示例值：s-3tigy72q3u3vj0x2****

会话ID。

UserSessionId string 示例值：session1

会话信息。

请求示例

POST https://agentkit.cn-beijing.volcengineapi.com?Action=CreateSession&Version=2025-10-30 HTTP/1.1​
Content-Type: application/json​
{​
    "ToolId": "t-ye6xzwchkwoaroxxxxxx",​
    "Ttl": 1440​
}​
​

返回示例

{​
  "ResponseMetadata": {​
    "RequestId": "20251027144356FBC64212879D5D3A****",​
    "Action": "CreateSession",​
    "Version": "2025-10-30",​
    "Service": "agentkit",​
    "Region": "cn-beijing"​
  },​
  "Result": {​
    "SessionId": "s-ye7sfdm2o0c1kdto****",​
    "UserSessionId": "",​
    "Endpoint": "http://sd3s4ng567ui2e1ad****.apigateway-cn-beijing.volceapi.com/?faasInstanceName=vefaas-bf5xfrv4-qa6b0ee7db-d3vh9b033fo44gohgrj0-sandbox",​
    "InternalEndpoint": ""​
  }​
}​

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidKey.Malformed	The specified Key is malformed.	指定的Key不合法。
400	InvalidUserSessionId.Malformed	The specified UserSessionId is malformed.	指定的UserSessionId不合法。
400	MissingParameter.Command	The required parameter Command is not supplied.	参数Command不能为空。
400	MissingParameter.Image	The required parameter Image is not supplied.	参数镜像不能为空。
400	MissingParameter.Key	The required parameter Key is not supplied.	参数Key不能为空。
400	MissingParameter.Port	The required parameter Port is not supplied.	参数Port不能为空。
400	MissingParameter.ToolId	The required parameter ToolId is not supplied.	tool id不能为空。
400	InvalidParameter.DuplicateUserSessionId	The specified user_session_id already exists.	会话信息已存在。
400	InvalidParameter.Ttl	The specified parameter Ttl is invalid.	指定的Ttl参数无效。
400	InvalidResourceStatus	The status of the specified resource does not support this request.	当前资源的状态不支持此操作。
400	ErrCreateSessionFail	Session start fail, please check console log.	创建session失败，请查看控制台日志进一步排查。
400	QuotaExceeded.ToolSessions	You've reached the limit on the session number of tool that you can create, please submit ticket or sign-on to the Console to request an increase in [tool/sessions] quota.	工具配额超限，请到配额中心申请tool/sessions配额。
404	InvalidResource.NotFound	The specified resource does not exist.	资源不存在。

最近更新时间：2026.07.21 19:16:37

这个页面对您有帮助吗？

有用

无用