文档首页/ 智果（AgentArts）智能体平台/ API参考/ API/ 沙箱工具/ 浏览器数据面接口/ 创建 Automation CDP WebSocket 流 - CreateAutomationStream
更新时间：2026-11-04 GMT+08:00
查看PDF
分享

创建 Automation CDP WebSocket 流 - CreateAutomationStream

功能介绍

该接口通过 WebSocket 协议透传 Chrome DevTools Protocol（CDP）消息，

供 Agent 或 SDK 以程序化方式控制浏览器。

协议： CDP over WebSocket（JSON 文本帧）

连接条件：

  • Session 的 automation_stream_status 必须为 enabled；

  • Session 内必须存在可调试的页面 Target；否则以关闭码 1011 拒绝。

若为 disabled（人工接管中），服务端以关闭码 1008 拒绝升级。

关闭码说明：

  • 1000：正常关闭

  • 1008：Session ID 不匹配 / automation 流已禁用

  • 1011：CDP 不可用（无页面 Target 或 DevTools URL 为空）

调用方法

请参见如何调用API。

授权信息

当前API调用无需身份策略权限。

URI

GET https://agentarts.com/v1/browsers/{browser_name}/automation

表1 路径参数

参数

是否必选

参数类型

描述

browser_name

是

String

参数解释：

与会话关联的浏览器工具的唯一标识符。

浏览器工具名称获取方式：

1.进入 AgentArts 平台，在左侧导航栏选择"托管与运行 > 浏览器"。

2.在浏览器工具列表中"浏览器工具名称/ID"处获取名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Authorization

是

String

参数解释：

本次智能体工具调用对应的身份认证凭据。需要根据实际的智能体工具的入站身份认证方式获取对应的身份认证凭据。

API Key认证、IAM认证及OAuth 2.0认证具体请参见认证鉴权。

约束限制：

不涉及。

取值范围：

1-4096个字符，由字母、数字及特殊字符组成。

默认取值：

不涉及。

X-Hw-Agentarts-Browser-Session-Id

是

String

参数解释：

要使用的浏览器会话的唯一标识符。

约束限制：

必须是通过 StartBrowserSession 创建的活跃会话。如果会话已过期或已停止，请求将失败。

取值范围：

符合正则：^[a-zA-Z0-9_-]+$。

默认取值：

不涉及。

Upgrade

是

String

参数解释：

固定为 websocket，表示从 HTTP 协议升级为 WebSocket 协议。

约束限制：

不涉及。

取值范围：

websocket。

默认取值：

不涉及。

Connection

是

String

参数解释：

固定为 Upgrade，表示客户端请求升级连接协议。

约束限制：

不涉及。

取值范围：

Upgrade。

默认取值：

不涉及。

Sec-Websocket-Key

是

String

参数解释：

随机 Base64 字符串（24 字符），用于生成 Sec-WebSocket-Accept 响应头。

约束限制：

不涉及。

取值范围：

24个字符的Base64字符串。

默认取值：

不涉及。

Sec-Websocket-Version

是

String

参数解释：

WebSocket 协议版本，固定传 13（RFC 6455 规定的当前版本号）。

约束限制：

不涉及。

取值范围：

13。

默认取值：

不涉及。

响应参数

状态码：101

表3 响应Header参数

参数

参数类型

描述

Upgrade

String

参数解释：

固定为 websocket，表示从 HTTP 协议升级为 WebSocket 协议。

约束限制：

不涉及。

取值范围：

websocket。

默认取值：

不涉及。

Connection

String

参数解释：

固定为 Upgrade，表示客户端请求升级连接协议。

约束限制：

不涉及。

取值范围：

Upgrade。

默认取值：

不涉及。

Sec-WebSocket-Accept

String

参数解释：

由服务端基于Sec-WebSocket-Key计算并返回。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

状态码：200

表4 响应Body参数

参数

参数类型

描述

id

Long

参数解释：

消息 ID，用于匹配请求与响应。响应消息中 id 与对应请求相同；事件消息无此字段。

取值范围：

1 至 9007199254740991（JavaScript Number.MAX_SAFE_INTEGER）。

method

String

参数解释：

CDP 命令或事件名称，格式为 Domain.methodName（如 Runtime.evaluate、Page.navigate）。

取值范围：

长度1到256个字符。

params

Object

参数解释：

CDP 命令参数或事件数据，结构由具体 method 定义。

取值范围：

不涉及。

result

Object

参数解释：

CDP 命令执行结果，仅响应消息包含此字段。

取值范围：

不涉及。

error

CdpError object

参数解释：

CDP 错误对象，命令执行失败时出现在响应消息中。

取值范围：

不涉及。
表5 CdpError

参数

参数类型

描述

code

Integer

参数解释：

CDP 错误码（JSON-RPC 2.0 错误码体系）。服务端保留错误码范围为 -32099 至 -32000。

取值范围：

-2147483648 至 -1。

message

String

参数解释：

错误描述信息。

取值范围：

长度1到1024个字符。

状态码：401

表6 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

满足正则规则 ^AgentArts.0402\d{4}$

error_msg

String

参数解释：

错误信息。

取值范围：

符合正则：^[a-zA-Z0-9\s一-鿿.,!?;:()'"-。，！？；：（）]+$。

状态码：403

表7 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

满足正则规则 ^AgentArts.0402\d{4}$

error_msg

String

参数解释：

错误信息。

取值范围：

符合正则：^[a-zA-Z0-9\s一-鿿.,!?;:()'"-。，！？；：（）]+$。

状态码：404

表8 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

满足正则规则 ^AgentArts.0402\d{4}$

error_msg

String

参数解释：

错误信息。

取值范围：

符合正则：^[a-zA-Z0-9\s一-鿿.,!?;:()'"-。，！？；：（）]+$。

状态码：500

表9 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

满足正则规则 ^AgentArts.0402\d{4}$

error_msg

String

参数解释：

错误信息。

取值范围：

符合正则：^[a-zA-Z0-9\s一-鿿.,!?;:()'"-。，！？；：（）]+$。

请求示例

无

响应示例

状态码：200

{
  "id" : 1,
  "method" : "Runtime.evaluate",
  "params" : {
    "expression" : "document.title"
  }
}

状态码：401

{
  "error_code" : "AgentArts.04020002",
  "error_msg" : "Authentication failed: invalid token"
}

状态码：403

{
  "error_code" : "AgentArts.04020003",
  "error_msg" : "Authentication failed: you have no permission."
}

状态码：404

{
  "error_code" : "AgentArts.04020004",
  "error_msg" : "Resource not found: session_id=sess-xxx"
}

状态码：500

{
  "error_code" : "AgentArts.04020000",
  "error_msg" : "System error. Please retry."
}

状态码

状态码

描述

101

Switching Protocols —— 连接升级成功，开始双向 CDP 消息透传。

200

WebSocket 消息帧 —— 升级后的双向 CDP JSON 消息。

每帧为一条完整的 Chrome DevTools Protocol JSON 文本消息。

401

认证失败

403

权限不足

404

资源不存在

500

内部系统错误

错误码

请参见错误码。

相关文档