更新时间：2026-09-14 GMT+08:00

启动浏览器 Session - StartBrowserSession

功能介绍

该 API 用于启动一个浏览器 Session。Gateway 拉起 Sandbox 容器后调用此接口，

容器内 browser-server 启动 Chrome 及相关组件，轮询 /ping 直到状态非 Initing 即视为就绪。

支持可选配置：视口大小、浏览器 Profile 加载、代理配置、域名白/黑名单。

调用方法

请参见如何调用API。

授权信息

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

URI

PUT https://agentarts.com/v1/browsers/{browser_name}/sessions-start

表1 路径参数
参数	是否必选	参数类型	描述
browser_name	是	String	参数解释：与会话关联的浏览器工具的唯一标识符。浏览器工具名称获取方式：进入 AgentArts 平台，在左侧导航栏选择"组件库 > 沙箱工具"。在浏览器工具列表中"浏览器工具名称/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_-]+$。默认取值：不涉及。

响应参数

状态码：200

无

请求示例

/v1/browsers/my-browser/sessions-start

{
  "name" : "browser-session-1",
  "session_timeout" : 900,
  "viewport" : {
    "width" : 1280,
    "height" : 720
  },
  "profile_configuration" : {
    "profile_id" : "profile-abc123"
  }
}

响应示例

无

状态码

状态码	描述
200	OK
400	请求参数错误
401	认证失败
403	权限不足
404	资源不存在
429	请求频率超限
500	内部系统错误

错误码

请参见错误码。

父主题： 浏览器数据面接口