本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 管理浏览器会话
<a name="browser-managing-sessions"></a>

## 启动浏览器会话
<a name="browser-start-session"></a>

创建浏览器后，您可以启动会话以与 Web 应用程序进行交互。

**Example**  

1. 要使用 Amazon CLI 启动浏览器会话，请使用以下`start-browser-session`命令：

   ```
    aws bedrock-agentcore start-browser-session \
     --region <Region> \
     --browser-identifier "my-browser" \
     --name "my-browser-session" \
     --session-timeout-seconds 900 \
     --view-port width=1456,height=819
   ```

1. 要使用 Amazon 适用于 Python 的软件开发工具包 (Boto3) 启动浏览器会话，请使用以下`start_browser_session`方法：

    **请求语法** 

   以下显示了请求语法：

   ```
   response = dp_client.start_browser_session(
       browserIdentifier="aws.browser.v1",
       name="browser-session-1",
       sessionTimeoutSeconds=3600,
       viewPort={
           'height': 819,
           'width': 1456
       }
   )
   ```

1. 要使用 BrowserClient 类启动浏览器会话以更好地控制会话生命周期，请执行以下操作：

   ```
   from bedrock_agentcore.tools.browser_client import BrowserClient
   
   # Create a browser client
   client = BrowserClient(region="us-west-2")
   
   # Start a browser session
   client.start()
   print(f"Session ID: {client.session_id}")
   
   try:
       # Generate WebSocket URL and headers
       url, headers = client.generate_ws_headers()
   
       # Perform browser operations with your preferred automation tool
   
   finally:
       # Always close the session when done
       client.stop()
   ```

1. 要使用 API 创建新的浏览器会话，请使用以下调用：

   ```
   # Using awscurl
   awscurl -X PUT \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/start" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region> \
     -d '{
       "name": "browser-session-abc12345",
       "description": "browser sandbox session",
       "sessionTimeoutSeconds": 300,
       "viewPort": {
          "height": 819,
          "width": 1456
       }
     }'
   ```

## 获取浏览器会话
<a name="browser-session-get"></a>

您可以获取有关您创建的浏览器会话的信息。

**Example**  

1. 要使用 Amazon CLI 获取有关浏览器会话的信息，请使用以下`get-browser-session`命令：

   ```
   aws bedrock-agentcore get-browser-session \
     --region <Region> \
     --browser-identifier "aws.browser.v1" \
     --session-id "<your-session-id>"
   ```

1. 要使用 Amazon 适用于 Python 的 SDK (Boto3) 获取有关浏览器会话的信息，请使用以下`get_browser_session`方法：

    **请求语法** 

   以下显示了请求语法：

   ```
   response = dp_client.get_browser_session(
       browserIdentifier="aws.browser.v1",
       sessionId="<your-session-id>"
   )
   ```

1. 要使用 API 获取有关浏览器会话的信息，请使用以下调用：

   ```
   # Using awscurl
   awscurl -X GET \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/get?sessionId=<your-session-id>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region>
   
   {
     "browserIdentifier": "aws.browser.v1",
     "createdAt": "2025-07-14T22:16:40.713152248Z",
     "lastUpdatedAt": "2025-07-14T22:16:40.713152248Z",
     "name": "testBrowserSession1752531400",
     "sessionId": "<your-session-id>",
     "sessionReplayArtifact": null,
     "sessionTimeoutSeconds": 900,
     "status": "TERMINATED",
     "streams": {
       "automationStream": {
         "streamEndpoint": "wss://bedrock-agentcore.<Region>.amazonaws.com/browser-streams/aws.browser.v1/sessions/<your-session-id>/automation",
         "streamStatus": "ENABLED"
       },
       "liveViewStream": {
         "streamEndpoint": "https://bedrock-agentcore.<Region>.amazonaws.com/browser-streams/aws.browser.v1/sessions/<your-session-id>/live-view"
       }
     },
     "viewPort": {
       "height": 819,
       "width": 1456
     }
   }
   ```

## 与浏览器会话交互
<a name="browser-interact"></a>

启动浏览器会话后，您可以使用 WebSocket API 与其进行交互。您还可以使用 InvokeBrowser API 进行直接的操作系统级控制，包括鼠标点击、键盘输入和全屏屏幕截图。有关更多信息，请参阅[浏览器操作系统操作](browser-invoke.md)。

**Example**  

1. ===== 使用控制台与浏览器会话进行交互

1. 导航到您的活动浏览器会话。

1. 使用浏览器界面浏览网站、与 Web 元素交互以及执行其他浏览器操作。

1. 您可以通过实时查看功能实时查看浏览器活动。

1. 要以编程方式与浏览器会话进行交互，请使用具有以下 URL 格式的 WebSocket-based 直播 API：

   ```
   https://bedrock-agentcore.<Region>.amazonaws.com/browser-streams/{browser_id}/sessions/{session_id}/automation
   ```

   您可以使用像 Playwright 这样的库与建立连接 WebSocket 并控制浏览器。示例如下：

   ```
   from playwright.sync_api import sync_playwright, Playwright, BrowserType
   import os
   import base64
   from bedrock_agentcore.tools.browser_client import browser_session
   
   def main(playwright: Playwright):
       # Keep browser session alive during usage
       with browser_session('us-west-2') as client:
   
           # Generate CDP endpoint and headers
           ws_url, headers = client.generate_ws_headers()
   
           # Connect to browser using headers
           chromium: BrowserType = playwright.chromium
           browser = chromium.connect_over_cdp(ws_url, headers=headers)
   
           # Use the first available context or create one
           context = browser.contexts[0] if browser.contexts else browser.new_context()
           page = context.pages[0] if context.pages else context.new_page()
   
           page.goto("https://amazon.com/")
           print("Navigated to Amazon")
   
           # Create CDP session for screenshot
           cdp_client = context.new_cdp_session(page)
           screenshot_data = cdp_client.send("Page.captureScreenshot", {
               "format": "jpeg",
               "quality": 80,
               "captureBeyondViewport": True
           })
   
           # Decode and save screenshot
           image_data = base64.b64decode(screenshot_data['data'])
           with open("screenshot.jpeg", "wb") as f:
               f.write(image_data)
   
           print("✅ Screenshot saved as screenshot.jpeg")
           page.close()
           browser.close()
   
   with sync_playwright() as p:
       main(p)
   ```

   以下示例代码显示了如何使用 WebSocket-based 流式传输 API 执行实时取景。

   ```
   https://bedrock-agentcore.<Region>.amazonaws.com/browser-streams/{browser_id}/sessions/{session_id}/live-view
   ```

   以下是代码。

   ```
   import time
   from rich.console import Console
   from bedrock_agentcore.tools.browser_client import browser_session
   from browser_viewer import BrowserViewerServer
   
   console = Console()
   
   def main():
       try:
            # Step 1: Create browser session
           with browser_session('us-west-2') as client:
               print("\r   ✅ Browser ready!                    ")
               ws_url, headers = client.generate_ws_headers()
   
               # Step 2: Start viewer server
               console.print("\n[cyan]Step 3: Starting viewer server...[/cyan]")
               viewer = BrowserViewerServer(client, port=8005)
               viewer_url = viewer.start(open_browser=True)
   
               # Keep running
               while True:
                   time.sleep(1)
   
       except KeyboardInterrupt:
           console.print("\n\n[yellow]Shutting down...[/yellow]")
           if 'client' in locals():
               client.stop()
               console.print("✅ Browser session terminated")
       except Exception as e:
           console.print(f"\n[red]Error: {e}[/red]")
           import traceback
           traceback.print_exc()
   
   if __name__ == "__main__":
       main()
   ```

## 列出浏览器会话
<a name="browser-list-sessions"></a>

您可以列出所有活跃的浏览器会话来监控和管理您的资源。这对于跟踪活动会话、识别长时间运行的会话或查找需要停止的会话很有用。

**Example**  

1. 要使用 Amazon CLI 列出浏览器会话，请使用以下`list-browser-sessions`命令：

   ```
   aws bedrock-agentcore list-browser-sessions \
     --region <Region> \
     --browser-id "<your-browser-id>" \
     --max-results 10
   ```

   您还可以按状态筛选会话：

   ```
   aws bedrock-agentcore list-browser-sessions \
     --region <Region> \
     --browser-id "<your-browser-id>" \
     --status "READY"
   ```

1. 要使用 Amazon 适用于 Python 的软件开发工具包 (Boto3) 列出浏览器会话，请使用以下`list_browser_sessions`方法：

    **请求语法** 

   以下显示了请求语法：

   ```
   response = dp_client.list_browser_sessions(
       browserIdentifier="aws.browser.v1"
   )
   ```

   您还可以按状态筛选会话：

   ```
   # List only active sessions
   filtered_response = dp_client.list_browser_sessions(
       browserIdentifier="aws.browser.v1",
       status="READY"
   )
   
   # Print filtered session information
   for session in filtered_response['items']:
       print(f"Ready Session ID: {session['sessionId']}")
       print(f"Name: {session['name']}")
       print("---")
   ```

1. 要使用 API 列出浏览器会话，请使用以下调用：

   ```
   # Using awscurl
   awscurl -X POST \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/<your-browser-id>/sessions/list" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region> \
     -d '{
       "maxResults": 10
     }'
   ```

   您还可以按状态筛选会话：

   ```
   # Using awscurl
   awscurl -X POST \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/list" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region> \
     -d '{
       "maxResults": 10,
       "status": "READY"
     }'
   ```

## 停止浏览器会话
<a name="browser-stop-session"></a>

使用完浏览器会话后，应停止它以释放资源并避免不必要的费用。

**Example**  

1. 要使用 Amazon CLI 停止浏览器会话，请使用以下`stop-browser-session`命令：

   ```
   aws bedrock-agentcore stop-browser-session \
     --region <Region> \
     --browser-id "<your-browser-id>" \
     --session-id "<your-session-id>"
   ```

1. 要使用 Amazon 适用于 Python 的软件开发工具包 (Boto3) 停止浏览器会话，请使用以下`stop_browser_session`方法：

    **请求语法** 

   以下显示了请求语法：

   ```
   response = dp_client.stop_browser_session(
           browserIdentifier="aws.browser.v1",
           sessionId="<your-session-id>",
       )
   ```

1. 要停止使用 API 的浏览器会话，请使用以下调用：

   ```
   # Using awscurl
   awscurl -X PUT \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/stop?sessionId=<your-session-id>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region>
   ```

## 更新浏览器直播
<a name="browser-update-stream"></a>

您可以更新浏览器流以启用或禁用自动化。当您需要输入敏感信息（例如不希望代理看到的登录凭据）时，这很有用。

**Example**  

1. 

   ```
   response = dp_client.update_browser_stream(
       browserIdentifier="aws.browser.v1",
       sessionId="<your-session-id>",
       streamUpdate={
           "automationStreamUpdate": {
               "streamStatus": "DISABLED"  # or "ENABLED"
           }
       }
   )
   ```

1. 

   ```
   awscurl -X PUT \
     "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/streams/update?sessionId=<your-session-id>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --service bedrock-agentcore \
     --region <Region> \
     -d '{
       "streamUpdate": {
               "automationStreamUpdate": {
                 "streamStatus": "ENABLED"
               }
             }
     }'
   ```

1. 

   ```
   aws bedrock-agentcore update-browser-stream \
     --region <Region> \
     --browser-id "<your-browser-id>" \
     --session-id "<your-session-id>" \
     --stream-update automationStreamUpdate={streamStatus=ENABLED}
   ```