一键运行代理任务 RunAgentTaskOneStep--云手机-火山引擎

文档中心

立即注册

导航

一键运行代理任务 RunAgentTaskOneStep

最近更新时间：2025.12.05 17:54:55首次发布时间：2025.12.05 17:54:55

启动一个新的代理任务执行。该接口无需创建代理运行配置，传入请求参数后可直接运行代理任务。

使用说明

调用 Mobile Use OpenAPI 前，必须先访问跨服务访问请求为您的账号授权。

注意事项

如果您需要使用指定的对象存储（TOS），则需同时传入 TosBucket、TosEndpoint、TosRegion 参数。
如果不传入 TosBucket、TosEndpoint、TosRegion 参数，会使用默认的 TOS，默认 TOS 不会持久化存储任务的截屏信息，任务完成后会立马删除。
本接口整体 QPS 限制为 50 次/秒、单用户 QPS 限制为 10 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=RunAgentTaskOneStep&Version=2023-08-01

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`RunAgentTaskOneStep`	接口名称。当前 API 的名称为 `RunAgentTaskOneStep`。
Version	String	是	`2023-08-01`	接口版本。当前 API 的版本为 `2023-08-01`。

Body

参数	类型	是否必选	示例值	描述
RunName	String	是	test-run	运行名称。字符长度限制：1 ~ 127
PodId	String	是	pod-789	Pod ID。字符长度限制：1 ~ 63
ProductId	String	是	product-001	产品 ID。字符长度限制：1 ~ 63
UserPrompt	String	是	请帮我完成任务	用户提示词。字符长度上限 10000。
ThreadId	String	否	thread-123	线程 ID。字符长度限制：1 ~ 63
UseBase64Screenshot	Boolean	否	true	是否使用 base64 编码传输截屏。默认为 false。
MaxStep	Integer	否	100	代理运行的最大步骤数。取值范围：1 ~ 500 默认值：100
CallbackUrl	String	否	https://example.com/callback	回调 URL 地址，支持 HTTP/HTTPS，代理任务执行期间产生的回调会发送到该地址。回调包括：任务状态更新回调任务执行失败回调任务中断回调
OutputSchema	String	否	{}	输出格式。JSON 字符串形式，具体参数参考通用数据结构中的 OutputSchema。
RetryLimit	Integer	否	3	AI 在调用失败场景下的重试次数限制。取值范围：1 ~ 10 默认值：3
SystemPrompt	String	否	You are a helpful assistant	系统提示词。
TosBucket	String	否	my-bucket	对象存储 TOS 存储桶名称。
TosEndpoint	String	否	tos-s3-cn-beijing.volces.com	对象存储 TOS 端点地址。
TosRegion	String	否	cn-beijing	对象存储 TOS 区域。

返回参数

公共返回参数信息请见返回结构，其中 Result 包含的参数说明如下。

参数名称	类型	示例值	描述
RunId	String	756729984938989****	运行 ID
RunName	String	test-run	运行名称
ThreadId	String	thread-123	线程 ID

请求示例

POST https://open.volcengineapi.com?Action=RunAgentTaskOneStep&Version=2023-08-01
{
        "RunName": "test-run",
        "PodId": "pod-789",
        "ProductId": "product-001",
        "UserPrompt": "请帮我完成任务",
        "ThreadId": "thread-123",
        "UseBase64Screenshot": false,
        "MaxStep": 100,
        "CallbackUrl": "https://www.example.com/callback",
        "OutputSchema": "{}",
        "RetryLimit": 3,
        "SystemPrompt": "You are a helpful assistant",
        "TosBucket": "my-bucket",
        "TosEndpoint": "tos-s3-cn-beijing.volces.com",
        "TosRegion": "cn-beijing"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "RunAgentTaskOneStep",
        "Version": "2023-08-01",
        "Service": "ipaas",
        "Region": "cn-north-1"
    },
    "Result":{
        "RunId":"756729984938989****",
        "RunName":"test-run",
        "ThreadId":"thread-123"
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。