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

文档中心

立即注册

云手机

任务管理

一键运行代理任务 RunAgentTaskOneStep

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

使用说明

调用 Mobile Use OpenAPI 前，必须先访问跨服务访问请求为您的账号授权。
如果您需要在运行代理任务期间开启云手机录屏（IsScreenRecord 参数取值为 true），则必须在云手机控制台配置对象存储服务，用于存储录屏文件。
说明
该配置下录屏文件不会删除（由您自己维护），录屏链接有效期为 24 小时（可在运行代理任务后调用获取任务运行结果 GetAgentResult接口获取）。
1. 前往火山引擎对象存储服务创建存储桶。详情参考对象存储快速入门。
2. 为云手机开通对象存储访问权限。详情参考开通火山引擎对象存储访问权限。
3. 登录云手机控制台，进入实例所在的业务。
4. 在业务左侧导航栏，选择功能配置。
5. 在功能配置页面的对象存储配置区域，单击添加配置。
6. 填写对象存储的存储桶名称、存储服务区域以及存储服务地址，并设置录屏功能使用场景。
7. 您可以通过验证配置功能，验证对象存储配置是否正确，正确后保存配置即可。

注意事项

如果您需要使用指定的对象存储（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
Timeout	Integer	否	300	超时时间，单位：秒。取值范围：1 ~ 86400 默认值：120
CallbackInfo	dict	否	{}	回调配置，用于接收代理任务执行期间产生的回调事件。具体参数参考通用数据结构中的CallbackInfo。
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 区域。
IsScreenRecord	Boolean	否	false	是否开启云手机录屏。说明如果需要开启录屏（取值为 true），则必须先在云手机控制台配置对象存储服务，具体操作参见使用说明。

返回参数

公共返回参数信息请见返回结构，其中 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,
        "Timeout": 300,
        "CallbackInfo": {},
        "OutputSchema": "{}",
        "RetryLimit": 3,
        "SystemPrompt": "You are a helpful assistant",
        "TosBucket": "my-bucket",
        "TosEndpoint": "tos-s3-cn-beijing.volces.com",
        "TosRegion": "cn-beijing",
        "IsScreenRecord": true
}

返回示例

{
    "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"
    }
}

错误码

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

最近更新时间：2026.01.15 18:08:43

这个页面对您有帮助吗？

有用

无用

云手机

使用说明 #

注意事项 #

请求说明 #

请求参数 #

Query #

Body #

返回参数 #

请求示例 #

返回示例 #

错误码 #