文档中心

AgentKit

Sandbox Tool

AsyncExecCommand - 在工具中异步执行一条Shell命令

在沙箱工具实例中异步执行一条Shell命令，用于需要执行耗时较长或无需实时等待结果的后台任务，例如执行编译、运行脚本、数据处理等操作。

接口说明

本接口为异步调用，仅返回任务创建状态，不直接返回命令执行结果，您可以使用本接口返回的任务ID通过ViewAsyncCommand接口查询命令的执行结果。

注意事项

注意

调用本接口时，服务地址与其他接口不同，请区分不同地域使用https://agentkit.<regionid>.volces.com。

请求参数

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

参数	类型	是否必选	示例值	描述
ToolId	String	是	t-yebi0bt****	工具ID。
Command	String	是	ls -la /	要执行的Shell命令。命令内容需要符合目标操作系统的语法。
UserSessionId	String	否	session-1	指定执行请求的用户会话信息，用于追踪和管理同一用户的多次连续请求，系统会尽量将会话路由到同一个沙箱实例中。传入参数且传入取值时：根据传入的会话信息执行请求，如果会话信息不存在则创建一个新的会话。传入参数但不传入取值时：创建一个新的会话。说明如果SessionId和UserSessionId都不传入，则默认创建新的UserSessionId。建议使用UserSessionId来关联同一用户的多次请求，以复用沙箱实例，避免不必要的冷启动开销。
SessionId	String	否	s-yecrzeybt****	指定执行请求的会话ID，用于将请求路由到指定的沙箱实例。说明如果SessionId和UserSessionId都不传入，则默认创建新的UserSessionId。建议使用UserSessionId来关联同一用户的多次请求，以复用沙箱实例，避免不必要的冷启动开销。
TaskId	String	否	task-e8a4g****	自定义任务ID。用于唯一标识一次异步执行。说明如果不传入，则默认创建新的TaskId。
ExecDir	String	否	/home/gem	命令执行的起始目录。说明如果未指定，默认为沙箱环境的默认工作目录（例如 /或 /home/work）。
Ttl	Integer	否	1800	会话实例存活时长，即工具在一次 “用户 - 工具交互会话” 中，保持用户状态、操作上下文不丢失的有效时长。说明会话过期后，只需重新登录或重启操作即可。如果在指定时间内无任何请求，实例将被自动销毁。单位：秒。取值范围：60～86400。默认值为：1800。

返回参数

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

参数	类型	示例值	描述
ToolId	String	t-yebi0bt****	执行命令的工具 ID。
UserSessionId	String	session-1	执行请求的用户会话信息。
SessionId	String	s-yecrbt****	执行请求的会话ID。
TaskId	String	task-e8a4g****	本次异步执行的任务ID，可用于后续查询。
Status	String	Running	任务的初始状态。通常为Running，表示命令已提交执行。
Command	String	ls -la /	执行的Shell命令。
ExecDir	String	/home/gem	命令执行的起码目录。

请求示例

POST https://agentkit.cn-beijing.volces.com?Action=AsyncExecCommand&Version=2025-10-30 HTTP/1.1​
Content-Type: application/json​
​
{​
    "ToolId": "t-yebi0bt****",​
    "UserSessionId": "session-1",​
    "Command": "sleep 5 && echo 'Hello, World!'",​
    "ExecDir": "/home/gem"​
}​

返回示例

{​
    "ResponseMetadata": {​
        "RequestId": "20240122163000010225****",​
        "Action": "AsyncExecCommand",​
        "Version": "2025-10-30",​
        "Service": "agentkit",​
        "Region": "cn-beijing"​
    },​
    "Result": {​
        "ToolId": "t-yebi0bt****",​
        "UserSessionId": "session-1",​
        "SessionId": "s-yecrbt****",​
        "TaskId": "task-e8a4g****",​
        "Status": "Running",​
        "Command": "sleep 5 && echo 'Hello, World!'",​
        "ExecDir": "/home/gem"​
    }​
}​

错误码

HttpCode	错误码	错误信息	描述
400	MissingParameter.ToolId	The required parameter ToolId is not supplied.	请求中缺少必要的ToolId参数。请检查并提供。
400	MissingParameter.Command	The required parameter Command is not supplied.	请求中缺少必要的Command参数。请检查并提供。

最近更新时间：2026.05.14 20:39:46

这个页面对您有帮助吗？

有用

无用