启动一个新的代理任务执行。该接口无需创建代理运行配置，传入请求参数后可直接运行代理任务。 ## 使用说明 * 调用 Computer Use Agent OpenAPI 前，必须先访问 [跨服务访问请求](https://console.volcengine.com/iam/service/attach_role/?ServiceName=ipaas) 为您的账号授权。 * 调用本接口时，存储桶以请求参数中传入的 `TosBucket` 为准；若需按配置动态切换存储桶，请使用 [RunAgentTask](https://www.volcengine.com/docs/6394/2556368) 接口。 ## 注意事项 * 如果您需要使用指定的对象存储（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 ## 请求参数下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见 [公共参数](https://www.volcengine.com/docs/6369/67268)。 ### Query |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Action |String |是 |RunAgentTaskOneStep |接口名称。当前 API 的名称为 `RunAgentTaskOneStep`。 | |Version |String |是 |2023\-08\-01 |接口版本。当前 API 的版本为 `2023-08-01`。 | ### Body |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |RunName |String |是 |test\-run |运行名称。字符长度限制：1 ~ 127 | |UserPrompt |String |是 |请帮我完成任务 |用户提示词。字符长度上限 10000。 | |ThreadId |String |否 |thread\-123 |线程 ID。字符长度限制：1 ~ 63 | |Ecsid |String |否 |i\-yeojjnlbexxxxxxxx |已接入 CUA 的节点 ECS（云服务器）ID。 | |AgentType |String |否 |cua |任务类型，不传入时由服务器按照默认逻辑处理。

* mua：Mobile Use Agent 任务类型。

* cua：Computer Use Agent 任务类型。 | |MaxStep |Integer |否 |100 |代理运行的最大步骤数。

* 取值范围：1 ~ 500

* 默认值：100 | |Timeout |Integer |否 |300 |超时时间，单位：秒。

* 取值范围：1 ~ 86400

* 默认值：120 | |CallbackInfo |Dict |否 |{} |回调配置，用于接收代理任务执行期间产生的回调事件。具体参数参考通用数据结构中的 [CallbackInfo](https://www.volcengine.com/docs/6394/1953040#04d665b2)。 | |OutputSchema |String |否 |{} |输出格式。JSON 字符串形式，具体参数参考通用数据结构中的 [OutputSchema](https://www.volcengine.com/docs/6394/1953040#09a9762e)。 | |RetryLimit |Integer |否 |3 |AI 在调用失败场景下的重试次数限制。

* 取值范围：1 ~ 10

* 默认值：3 | |SystemPrompt |String |否 |You are a helpful assistant |系统提示词。 | |TosBucket |String |否 |my\-bucket |对象存储 TOS 存储桶名称。本接口以请求参数中传入的 TosBucket 为准，不根据代理运行配置切换存储桶。 | |TosEndpoint |String |否 |tos\-s3\-cn\-beijing.volces.com |对象存储 TOS 端点地址。 | |TosRegion |String |否 |cn\-beijing |对象存储 TOS 区域。 | |McpJson |String |否 |{"mcpServers":{"amap\-maps":{"url":"https://mcp.amap.com/mcp?key=xxx","transport":"streamable_http"}}} |第三方 MCP 工具配置，目前仅支持 URL。 | |MaxOutputTokens |Integer |否 |100 |模型单次响应的最大输出 Token 数限制，默认无限制。 | ## 返回参数公共返回参数信息请见[返回结构](https://www.volcengine.com/docs/6394/75713#%E8%BF%94%E5%9B%9E%E7%BB%93%E6%9E%9C)，其中 `Result` 包含的参数说明如下。 |**参数名称** |**类型** |**示例值** |**描述** | |---|---|---|---| |RunId |String |756729984938989\*\*\*\* |运行 ID。 | |RunName |String |test\-run |运行名称。 | |ThreadId |String |thread\-123 |线程 ID。 | ## 请求示例 ```JSON POST https://open.volcengineapi.com?Action=RunAgentTaskOneStep&Version=2023-08-01 { "RunName": "test-run", "UserPrompt": "请帮我完成任务", "ThreadId": "thread-123", "AgentType": "cua", "Ecsid": "i-yeojjnlbexxxxxxxx", "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" } ``` ## 返回示例 ```JSON { "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" } } ``` ## 错误码 Computer Use Agent OpenAPI 错误码请参见 [错误码](https://www.volcengine.com/docs/6394/2558652)。

云手机