启动浏览器 Session - StartBrowserSession

browser_name

是

String

参数解释：

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

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

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

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

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

Authorization

是

String

参数解释：

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

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

约束限制：

不涉及。

取值范围：

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

默认取值：

不涉及。

X-Hw-Agentarts-Browser-Session-Id

否

String

参数解释：

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

约束限制：

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

取值范围：

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

默认取值：

不涉及。

X-Hw-Agentarts-Browser-Profile-Id

否

String

参数解释：

浏览器 Profile 的唯一标识符。由控制面创建并返回。

约束限制：

长度范围：1到128个字符。

取值范围：

长度1到128个字符。

默认取值：

不涉及。

name

是

String

参数解释：

浏览器会话的名称。此名称有助于识别和管理会话，名称无需唯一。

约束限制：

长度范围：1到128个字符。

取值范围：

符合正则条件 ^[a-zA-Z0-9_-]+$，即仅允许字母、数字、中划线、下划线组成，字符长度 1-128。

默认取值：

不涉及。

session_timeout

否

Integer

参数解释：

会话在无任何活动后自动终止的秒数。

约束限制：

60到86400。

取值范围：

最小 60 秒，最大 86400 秒（24 小时）。

默认取值：

900 秒（15 分钟）

viewport

否

Viewport object

参数解释：

浏览器视口尺寸配置。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

allowed_domains

否

Array of strings

参数解释：

域名白名单。仅白名单中的域可访问，其余被 CDP Fetch 拦截器阻断。

约束限制：

与 blocked_domains 互斥，不可同时传入。

取值范围：

支持精确匹配（如 example.com）和通配匹配（如 .example.com）。

默认取值：

不涉及（不传则不限制）。

blocked_domains

否

Array of strings

参数解释：

域名黑名单。黑名单中的域被 CDP Fetch 拦截器阻断，其余可访问。

约束限制：

与 allowed_domains 互斥，不可同时传入。

取值范围：

支持精确匹配和通配匹配，语法同 allowed_domains。

默认取值：

不涉及（不传则不限制）。

proxy_configuration

否

ProxyConfiguration object

参数解释：

浏览器代理配置。Session 创建时传入，整个 Session 生命周期内不可变。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

width

否

Integer

参数解释：

视口宽度（像素）。

约束限制：

800到3840。

取值范围：

最小 800，最大 3840。

默认取值：

1280

height

否

Integer

参数解释：

视口高度（像素）。

约束限制：

600到2160。

取值范围：

最小 600，最大 2160。

默认取值：

720

proxies

否

Array of ProxyEntry objects

参数解释：

代理服务器列表。支持为不同代理配置 domain_patterns 实现域名路由。

无 domain_patterns 的代理作为默认代理。

约束限制：

最多 5 个代理。

取值范围：

数组长度1到5个元素。

默认取值：

不涉及。

bypass

否

ProxyBypass object

参数解释：

代理 bypass 配置，命中的域名直连不走代理。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

server

是

String

参数解释：

代理服务器地址（域名或 IP）。

约束限制：

长度范围：1到256个字符。

取值范围：

长度1到256个字符。

默认取值：

不涉及。

port

是

Integer

参数解释：

代理服务器端口。

约束限制：

1到65535。

取值范围：

1 至 65535。

默认取值：

不涉及。

type

是

String

参数解释：

代理类型。

约束限制：

不涉及。

取值范围：

• http：HTTP 代理（标准 CONNECT 隧道）

• https：HTTPS 加密代理

• socks5：SOCKS5 代理

默认取值：

不涉及。

credential_id

否

String

参数解释：

代理认证凭据 ID，引用平台密钥管理服务中的密钥。

约束限制：

凭据通过平台密钥管理服务存储，不在 API 中明文传递用户名密码。

取值范围：

长度1到128个字符。

默认取值：

不涉及（无需认证时不传）。

domain_patterns

否

Array of strings

参数解释：

该代理适用的域名模式列表。匹配的请求走此代理。

约束限制：

每个代理最多 100 个域名模式。

取值范围：

支持精确匹配（如 example.com）和通配匹配（如 .example.com 匹配所有子域）。

默认取值：

不传则作为默认代理。

domain_patterns

否

Array of strings

参数解释：

bypass 域名模式列表，匹配的请求直连。

约束限制：

最多 100 个域名模式。

取值范围：

支持精确匹配和通配匹配，语法同 ProxyEntry.domain_patterns。

默认取值：

不涉及。

browser_name

String

参数解释：

浏览器工具的名称。

取值范围：

长度1到64个字符。

session_id

String

参数解释：

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

取值范围：

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

created_at

String

参数解释：

浏览器会话创建的时间（ISO 8601 格式）。

取值范围：

ISO 8601日期时间格式字符串。

name

String

参数解释：

浏览器会话的名称。

取值范围：

长度1到128个字符。

session_timeout

Integer

参数解释：

浏览器会话的超时时间（秒）。

取值范围：

60到86400。

viewport

Viewport object

参数解释：

浏览器视口尺寸配置。

取值范围：

不涉及。

streams

BrowserSessionStream object

参数解释：

浏览器会话关联的流信息集合，包含 automation 控制流和 liveView 观看流。

取值范围：

不涉及。

width

Integer

参数解释：

视口宽度（像素）。

取值范围：

最小 800，最大 3840。

height

Integer

参数解释：

视口高度（像素）。

取值范围：

最小 600，最大 2160。

automation_stream

AutomationStream object

参数解释：

Automation 控制流配置。提供 CDP 协议双向通信通道，用于 Agent 程序化控制浏览器。

通过 UpdateBrowserStream API 可将 stream_status 切换为 disabled（人工接管），

此时已有连接被断开，新连接和 invoke 请求被拒绝（HTTP 403）。

设回 enabled 后恢复正常。

取值范围：

不涉及。

live_view_stream

LiveViewStream object

参数解释：

LiveView 观看流配置。提供 RFB-over-WebSocket 实时画面流，

人工可通过 VNC 客户端观看并操作浏览器。

LiveView 是纯观看通道，连接不影响 automation/invoke 运行。

如需人工接管（禁用 automation），需通过 UpdateBrowserStream API 显式切换。

取值范围：

不涉及。

stream_endpoint

String

参数解释：

Automation 流的 WebSocket 端点 URL，用于建立 CDP 透传连接。

取值范围：

合法的 WSS URL。

stream_status

String

参数解释：

Automation 流的当前状态。通过 UpdateBrowserStream API 切换。

取值范围：

• enabled：流可用，可以建立 automation 连接和发送 invoke 请求

• disabled：流不可用（人工接管中），automation 连接被断开，

新连接和 invoke 请求返回 403

stream_endpoint

String

参数解释：

LiveView 流的 WebSocket 端点 URL，用于建立 RFB 实时画面连接。

取值范围：

合法的 WSS URL。

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

error_code

String

参数解释：

错误码。

取值范围：

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

error_msg

String

参数解释：

错误信息。

取值范围：

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

200

OK

400

请求参数错误

401

认证失败

403

权限不足

404

资源不存在

429

请求频率超限

500

内部系统错误