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

使用说明

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

调用本接口时，存储桶以请求参数中传入的 TosBucket 为准；若需按配置动态切换存储桶，请使用 RunAgentTask 接口。

注意事项

如果您需要使用指定的对象存储（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。
UserPrompt	String	是	请帮我完成任务	用户提示词，长度上限为 10000 字节。若内容以中文为主，建议控制在 3000 字以内。
ThreadId	String	否	thread-123	线程 ID，自定义的随机字符串，用于标识一段对话。不传时由 CUA 自动生成，并在返回结果中返回。字节长度限制：1 ~ 63。
Ecsid	String	否	i-yeojjnlbe***	已接入 CUA 的节点 ECS（云服务器）ID。
AgentType	String	否	cua	Agent 任务类型，此处暂仅支持 cua。
MaxStep	Integer	否	100	任务执行过程中允许的最大操作步骤数，每完成一个独立操作（如点击、输入、滑动等）计为一步，达到上限后任务将自动停止。默认值为 100，取值： 1~500：设置步数。 -1：不限制步数。注意传入 -1 后任务将持续执行直至完成或超时，可能导致任务长时间运行，建议仅在明确需要不限步数的场景下使用，并配合 Timeout 参数控制最长运行时间。若 MaxStep 与 Timeout同时传入 -1，不限制步数及超时时间，CUA 将自动进行上下文压缩（即 CUA 自动对历史内容进行压缩以避免超出模型限制），任务可能会 7*24 小时持续运行，需要手动调用 CancelTask 终止任务，请谨慎操作。
Timeout	Integer	否	300	任务从开始执行到强制终止的最长等待时间，单位为秒，默认值为 1000，取值： 1~86400：设置超时时间。 -1：不限制超时时间。注意传入 -1 后任务将不受时间限制持续运行，可能导致资源长时间占用，建议仅在明确需要超长运行时间的场景下使用。若 MaxStep 与 Timeout同时传入 -1，不限制步数及超时时间，CUA 将自动进行上下文压缩（即 CUA 自动对历史内容进行压缩以避免超出模型限制），任务可能会 7*24 小时持续运行，需要手动调用 CancelTask 终止任务，请谨慎操作。
CallbackInfo	Dict	否	{}	回调配置，用于接收代理任务执行期间产生的回调事件。具体参数参考通用数据结构中的 CallbackInfo。
OutputSchema	String	否	{}	输出格式。JSON 字符串形式，具体参数参考通用数据结构中的 OutputSchema。
RetryLimit	Integer	否	3	任务执行失败后的自动重试次数，默认值为 3，取值：取值范围：0~10。 0：按默认值 3 处理。
SystemPrompt	String	否	You are a helpful assistant	系统提示词的具体内容，最多支持 20000 个字符。若不传入该参数，则不启用系统提示词。
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 工具配置（Model Context Protocol，一种开发协议，允许 CUA 通过标准化接口调用外部工具或服务），JSON 格式，目前仅支持通过 URL 接入。不传时不启用 MCP 工具。
MaxOutputTokens	Integer	否	100	MUA 单次生成回复允许输出的最大 Token 数量，取值：取值范围：0~65526，超出后回复将被截断。 0：（默认）不限制。
Execution	Object / JSON String	否	{"Type":"ChainRun","Nodes":[...]}	完整的任务执行配置。不能与 RunMode、ScriptId、ChainId、Script、File 或 Nodes 同时传入。
RunMode	String	否	ChainRun	任务运行模式，取值： AgentRun：根据任务目标自主规划执行。 ScriptRun：按固定脚本顺序执行。 ChainRun：引用指定编排资产，按其节点顺序执行。注意未使用 Execution 时，可通过该参数选择运行方式。
ScriptId / Script / File	Long / String / File	条件必选	1001	ScriptRun 模式下必须选择其中一种方式提供脚本，脚本资产必须属于当前账号。详情请参见 CreateAgentRunScript。取值：通过 ScriptId 指定脚本资产。通过 Script 传入脚本内容。通过 File 以文件形式上传。
ChainId / Nodes	Long / Array	条件必选	2001	ChainRun 模式下必须选择其中一种方式提供任务链，任务链资产必须属于当前账号。详情请参见 CreateAgentRunChain。取值：通过 ChainId 指定任务链资产。通过顶层 Nodes 传入节点列表。

返回参数

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

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

请求示例

返回示例

错误码

CUA OpenAPI 错误码请参见错误码。

云手机