# Browser SDK
#### 场景介绍
支持Browser生命周期管理、Browser Profile生命周期管理和Session生命周期管理。
#### 原理优势
用户空间已存在浏览器时，SDK支持快速拉起浏览器会话。
```
api_key = "your_actual_api_key"  # your api key
with browser_session("your_region", "your_browser_name", "your_session_name", api_key=api_key) as browser_client:
    response = browser_client.invoke(
        type="your_type",
        api_key=api_key,
        action={your_action}
    )
```
#### 前提条件
- 已开通AgentArts。

- 登录控制台获取AK/SK，和API_KEY信息，详情请参考[如何获取华为云AK/SK](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html#agentarts_10_047__section13365141032517)和[如何获取浏览器的API_KEY](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_225.html)。

- 已安装Python，且版本不低于3.10。查看Python版本的命令示例：python --version。
 
#### 操作步骤
1. 执行如下命令进行包安装。 
   ```
   # 安装agentarts-sdk包
   pip install agentarts-sdk
   # 安装langgraph包
   pip install langgraph
   # 安装langchain_openai包
   pip install langchain-openai
   ```
   
   
2. 配置环境变量： 
   ```
   # === 用于通过代码创建沙箱 ===
   export HUAWEICLOUD_SDK_AK="您的华为云AK"
   export HUAWEICLOUD_SDK_SK="您的华为云SK"
   export AGENTARTS_CONTROL_ENDPOINT="https://agentarts.cn-southwest-2.myhuaweicloud.com"
   export AGENTARTS_BROWSER_DATA_ENDPOINT="http://您的沙箱域名"
   export HUAWEICLOUD_SDK_BROWSER_API_KEY="您的沙箱 API Key"
   ```
   获取AK/SK请参考[如何获取华为云AK/SK](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html#agentarts_10_047__section13365141032517)。
   沙箱工具的域名、API Key获取方法如下：
   1. 单击沙箱工具名称。
   
   2. 进入"配置信息"页面后，获取域名。
      图1获取沙箱域名   
      ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002741252113.png "点击放大") 
   
   3. 单击"URN"链接，在弹出的窗口中获取沙箱的API Key。
      图2URN链接   
      ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002711693092.png "点击放大")
      图3获取沙箱API Key   
      ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002711533158.png "点击放大") 
   
   
   
   
3. 创建浏览器。 
   ```
   from agentarts.sdk.tools import Browser
   # auth_type为API_KEY时创建示例
   client = Browser(region="your_region", auth_type="API_KEY")
   browser = client.create_browser(
       name="your_browser_name",
       api_key_name="your_api_key_name"
   )
   # auth_type为IAM时创建示例
   client = Browser(region="your_region", auth_type="IAM")
   browser = client.create_browser(
       name="your_browser_name",
       auth_type="IAM"
   )
   ```
   
   
4. 配置工具，这里以导航工具为例。 
   - API_KEY的配置工具示例如下，用户自定义region信息和需要使用的浏览器，浏览器名称和API_KEY一一对应。
     ```
     import json
     from agentarts.sdk.tools import browser_session
     from langchain_core.tools import tool
     @tool
     def navigate_tool(url: str) -> str | None:
         """Navigate to a URL in the browser"""
         api_key = "your_actual_api_key"  # your api key
         with browser_session("cn-southwest-2", "your_browser_name", "your_session_name", api_key=api_key) as browser_client:
             response = browser_client.invoke(
                 type="navigate",
                 api_key=api_key,
                 action={
                     "url": url
                 }
             )
         return json.dumps(response)
     ```
     
   
   - IAM认证的配置工具示例：
     ```
     import json
     from agentarts.sdk.tools import browser_session
     from langchain_core.tools import tool
     @tool
     def navigate_tool(url: str) -> str | None:
         """Navigate to a URL in the browser"""
         with browser_session("cn-southwest-2", "your_browser_name", "your_session_name", auth_type="IAM") as browser_client:
             response = browser_client.invoke(
                 type="navigate",
                 action={
                     "url": url
                 }
             )
         return json.dumps(response)
     ```
     
   
   
   
   
5. 集成配置的工具，以如下导航为例。 
   ```
   from langchain_openai import ChatOpenAI
   # 创建Agent
   llm = ChatOpenAI(
       model="deepseek-v4-flash",
       api_key=os.environ.get("MODEL_API_KEY", ""),
       base_url=os.environ.get("BASE_URL", ""),
       max_tokens=1000,
       temperature=0.7,
   )
   # 创建工具列表
   tools = [navigate_tool]
   # 工具绑定Agent
   llm = llm.bind_tools(tools)
   ```
   
   
 
通过SDK可调用的管理面方法请参考[表1]，详细使用指导请参考[工具使用方法指引](https://github.com/huaweicloud/agentarts-sdk-python/blob/main/docs/cn/sdk_user_guide/tools_user_guide.md)。
 表1管理面方法 
| 方法                       | 说明        |
|:---|:---|
| create_browser            | 创建浏览器    |
| list_browsers           | 查询浏览器列表  |
| update_browser          | 更新浏览器      |
| get_browser              | 获取浏览器详情   |
| delete_browser          | 删除浏览器   |
| create_browser_profile  | 创建浏览器配置  |
| list_browser_profiles   | 查询浏览器配置列表 |
| get_browser_profile   | 获取浏览器配置详情  |
| delete_browser_profile | 删除浏览器配置   |
   
通过SDK可调用的数据面方法请参考[表2]，详细使用指导请参考[工具使用方法指引](https://github.com/huaweicloud/agentarts-sdk-python/blob/main/docs/cn/sdk_user_guide/tools_user_guide.md)。
 表2数据面方法 
| 方法                     | 说明                        |
|:---|:---|
| start_session          | 启动浏览器会话                 |
| get_session          | 获取浏览器会话详情               |
| stop_session          | 停止当前浏览器会话               |
| invoke                 | 调用浏览器操作                  |
| save_profile         | 保存当前浏览器会话状态到配置           |
| update_stream         | 更新浏览器会话流状态              |
| take_control             | 获取浏览器人工控制权（禁用自动化）      |
| release_control        | 释放人工控制权（启用自动化）          |
| generate_automation_url | 生成自动化流的WebSocket URL和请求头  |
| generate_live_view_url   | 生成实时查看流的WebSocket URL和请求头 |
| mouse_click            | 鼠标点击                       |
| left_mouse_click      | 鼠标左键点击                    |
| right_mouse_click     | 鼠标右键点击                   |
| double_mouse_click    | 鼠标双击                      |
| mouse_move            | 鼠标移动                     |
| mouse_drag              | 鼠标拖拽                      |
| mouse_scroll          | 鼠标滚动                     |
| key_press              | 按键                       |
| key_type               | 输入文本                     |
| key_shortcut             | 按键组合                     |
| navigate               | 导航到指定URL                |
| go_back                 | 返回上一页                    |
| go_forward            | 前进到下一页                    |
| refresh                | 刷新当前页面                  |
| get_page_info         | 获取当前页面信息               |
| screenshot             | 截图                        |
| wait                   | 等待                       |
| list_tabs             | 列出所有标签页                  |
| switch_tab             | 切换标签页                   |
| close_tab                | 关闭标签页                      |
| new_tab                    | 打开新标签页                    |
| browser_session         | 上下文管理器                      |