> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon Bedrock AgentCore 浏览器集成

> 使用 LangChain 集成 Amazon Bedrock AgentCore 浏览器工具。

[Amazon Bedrock AgentCore 浏览器](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html) 使智能体能够通过管理的 Chrome 浏览器与网页交互。智能体可以浏览网站、提取内容、填写表单、点击元素，并在安全、受管理的环境中进行屏幕截图。

## 概述

### 集成细节

| 类 | 包 | 可序列化 | [JS 支持](https://langchain-docs-zh.mintlify.site/langchain/oss/javascript/integrations/tools.md) | 版本 |
| :- | :- | :-: | :-: | :-: |
| [`BrowserToolkit`](https://github.com/langchain-ai/langchain-aws/tree/main/libs/aws/langchain_aws/tools) | [`langchain-aws`](https://pypi.org/project/langchain-aws/) | ❌ | ❌ | ![PyPI - 版本](https://img.shields.io/pypi/v/langchain-aws?style=flat-square\&label=%20) |

### 工具特性

| [返回工件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md) | 原生异步 | 支持浏览器交互 | 定价 |
| :-: | :-: | :-: | :-: |
| ✅ | ✅ | ✅ | 按量付费 (AWS) |

### 可用工具

工具包提供了多种用于浏览器自动化的工具：

| 工具 | 描述 |
| :- | :- |
| `navigate_browser` | 导航到 URL |
| `click_element` | 使用 CSS 选择器点击元素 |
| `type_text` | 将文本输入到输入字段 |
| `extract_text` | 从页面提取所有文本内容 |
| `extract_hyperlinks` | 从页面提取所有超链接 |
| `get_elements` | 获取匹配 CSS 选择器的元素 |
| `current_webpage` | 获取当前页面 URL 和标题 |
| `navigate_back` | 返回到上一页 |
| `take_screenshot` | 对页面进行屏幕截图 |
| `scroll_page` | 在指定方向上滚动页面 |
| `wait_for_element` | 等待元素出现 |

## 设置

集成位于 `langchain-aws` 包中。它还需要 `playwright` 和 `beautifulsoup4` 用于浏览器自动化和 HTML 解析。

```bash pip theme={null}
pip install -U langchain-aws bedrock-agentcore playwright beautifulsoup4
playwright install chromium
```

```bash uv theme={null}
uv add langchain-aws bedrock-agentcore playwright beautifulsoup4
playwright install chromium
```

### 凭证

您需要配置具有 Bedrock AgentCore 浏览器权限的 AWS 凭证。有关所需的 IAM 权限，请参阅 [Amazon Bedrock AgentCore 文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html)。

设置 LangSmith（但不是必需的）以获得最佳级别的可观察性：

```python theme={null}
import os

os.environ["LANGSMITH_API_KEY"] = "your-api-key"
os.environ["LANGSMITH_TRACING"] = "true"
```

## 实例化

工具包使用工厂函数创建。最简单的情况下，只需要 AWS 区域：

```python theme={null}
from langchain_aws.tools import create_browser_toolkit

# Create toolkit and get tools
toolkit, browser_tools = create_browser_toolkit(region="us-west-2")
```

工厂函数还接受用于 [代理配置](#代理配置)、[浏览器扩展](#浏览器扩展) 和 [浏览器配置文件](#浏览器配置文件) 的可选参数。有关详细信息，请参阅下文。

## 代理配置

使用 `proxy_configuration` 参数将浏览器流量路由到外部代理。这对于地理位置定位、IP 旋转或访问区域限制内容很有用。

```python theme={null}
from langchain_aws.tools import create_browser_toolkit

toolkit, browser_tools = create_browser_toolkit(
    region="us-west-2",
    proxy_configuration={
        "proxies": [{
            "externalProxy": {
                "server": "proxy.example.com",
                "port": 8080,
                "credentials": {
                    "basicAuth": {
                        "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:proxy-creds"
                    }
                },
            }
        }],
    },
)
```

`proxy_configuration` 参数接受来自 `bedrock-agentcore` 的 `ProxyConfiguration` 数据类或等效字典，包含 `proxies` 和可选的 `bypass` 键。代理凭证安全地存储在 AWS Secrets Manager 中。

有关更多详细信息，请参阅 [AWS 关于浏览器代理的文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-proxies.html)。

## 浏览器扩展

使用 `extensions` 参数将 S3 中的浏览器扩展加载到受管理的浏览器会话中。扩展作为 ZIP 文件打包并托管在 S3 存储桶中。

```python theme={null}
from langchain_aws.tools import create_browser_toolkit

toolkit, browser_tools = create_browser_toolkit(
    region="us-west-2",
    extensions=[{
        "location": {
            "s3": {"bucket": "my-extensions-bucket", "prefix": "my-extension.zip"}
        }
    }],
)
```

`extensions` 参数接受一组 `BrowserExtension` 数据类或等效字典，每个字典都有一个指定存储桶和前缀的 S3 `location`。

有关更多详细信息，请参阅 [AWS 关于浏览器扩展的文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-extensions.html)。

## 浏览器配置文件

使用 `profile_configuration` 参数跨会话持久化浏览器状态（Cookie、本地存储、缓存数据）。这允许智能体在离开的地方继续，而无需重新身份验证或丢失上下文。

使用 AWS CLI 或 Boto3 创建配置文件，然后将返回的配置文件 ID 传递：

```python theme={null}
from langchain_aws.tools import create_browser_toolkit

toolkit, browser_tools = create_browser_toolkit(
    region="us-west-2",
    profile_configuration={
        "profileIdentifier": "my_profile-AbC1234567"
    },
)
```

`profile_configuration` 参数接受来自 `bedrock-agentcore` 的 `ProfileConfiguration` 数据类或等效字典，包含 `profileIdentifier` 键。配置文件 ID 采用格式 `<name>-<10-char-suffix>`，通过 Bedrock AgentCore 控制平面 API 创建配置文件时返回。

有关更多详细信息，请参阅 [AWS 关于浏览器配置文件的文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-profiles.html)。

## 组合配置选项

所有三个配置选项可以一起使用：

```python theme={null}
from langchain_aws.tools import create_browser_toolkit

toolkit, browser_tools = create_browser_toolkit(
    region="us-west-2",
    proxy_configuration={
        "proxies": [{
            "externalProxy": {
                "server": "proxy.example.com",
                "port": 8080,
                "credentials": {
                    "basicAuth": {
                        "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:proxy-creds"
                    }
                },
            }
        }],
    },
    extensions=[{
        "location": {
            "s3": {"bucket": "my-extensions-bucket", "prefix": "my-extension.zip"}
        }
    }],
    profile_configuration={
        "profileIdentifier": "my_profile-AbC1234567"
    },
)
```

## 调用

### 直接工具使用

获取特定工具并调用它们：

```python theme={null}
# Get tools by name
tools_by_name = toolkit.get_tools_by_name()

# Navigate to a URL (requires config with thread_id)
config = {"configurable": {"thread_id": "session-123"}}

result = tools_by_name["navigate_browser"].invoke(
    {"url": "https://example.com"},
    config=config
)
print(result)

# Extract text from the page
text = tools_by_name["extract_text"].invoke({}, config=config)
print(text)
```

### 在智能体中使用

```python theme={null}
import asyncio
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_aws.tools import create_browser_toolkit

async def main():
    # Create toolkit
    toolkit, browser_tools = create_browser_toolkit(region="us-west-2")

    # Initialize chat model
    llm = init_chat_model(
        "us.anthropic.claude-sonnet-4-20250514-v1:0",
        model_provider="bedrock_converse",
    )

    # Create agent with browser tools
    agent = create_agent(
        model=llm,
        tools=browser_tools,
    )

    # Create config with thread_id for session isolation
    config = {"configurable": {"thread_id": "research-session"}}

    # Run the agent
    result = await agent.ainvoke(
        {"messages": [{
            "role": "user",
            "content": "Navigate to https://example.com and tell me the main heading"
        }]},
        config=config
    )
    print(result["messages"][-1].content)

    # Clean up when done
    await toolkit.cleanup()

asyncio.run(main())
```

## 基于线程的会话隔离

工具包为每个 `thread_id` 维护单独的浏览器会话。这允许并发使用而不会相互干扰：

```python theme={null}
# Each thread gets its own browser session
config_user1 = {"configurable": {"thread_id": "user-1"}}
config_user2 = {"configurable": {"thread_id": "user-2"}}

# User 1 navigates to site A
tools_by_name["navigate_browser"].invoke(
    {"url": "https://site-a.com"},
    config=config_user1
)

# User 2 navigates to site B (different browser session)
tools_by_name["navigate_browser"].invoke(
    {"url": "https://site-b.com"},
    config=config_user2
)
```

## 浏览器操作

### 导航

```python theme={null}
config = {"configurable": {"thread_id": "session-123"}}

# Navigate to URL
tools_by_name["navigate_browser"].invoke({"url": "https://example.com"}, config=config)

# Go back
tools_by_name["navigate_back"].invoke({}, config=config)

# Get current page info
current = tools_by_name["current_webpage"].invoke({}, config=config)
print(current)  # URL and title
```

### 与元素交互

```python theme={null}
# Click an element
tools_by_name["click_element"].invoke({"selector": "#submit-button"}, config=config)

# Type into an input field
tools_by_name["type_text"].invoke({
    "selector": "input[name='search']",
    "text": "search query"
}, config=config)

# Wait for element to appear
tools_by_name["wait_for_element"].invoke({
    "selector": ".results",
    "timeout": 10000,  # 10 seconds
    "state": "visible"
}, config=config)
```

### 提取内容

```python theme={null}
# Extract all text
text = tools_by_name["extract_text"].invoke({}, config=config)

# Extract all hyperlinks
links = tools_by_name["extract_hyperlinks"].invoke({}, config=config)

# Get specific elements
elements = tools_by_name["get_elements"].invoke(
    {"selector": "article h2"},
    config=config
)
```

### 屏幕截图和滚动

```python theme={null}
# Take screenshot of visible viewport (returns base64 image)
screenshot = tools_by_name["take_screenshot"].invoke(
    {"capture_type": "viewport"},
    config=config
)

# Take screenshot of entire scrollable page
full_screenshot = tools_by_name["take_screenshot"].invoke(
    {"capture_type": "full_page"},
    config=config
)

# Scroll the page
tools_by_name["scroll_page"].invoke({
    "direction": "down",
    "amount": 500  # pixels
}, config=config)
```

## 会话清理

完成时始终清理浏览器会话以释放资源：

```python theme={null}
# Clean up all browser sessions
await toolkit.cleanup()
```

> **注意:** 虽然 `create_browser_toolkit()` 是同步的，但 `cleanup()` 方法是异步的，必须等待。

## 并发保护

工具包包括内置的并发保护。每个浏览器会话都与特定的 `thread_id` 关联，如果尝试在会话正在使用时访问它，将引发 `RuntimeError`。为并发操作使用不同的 `thread_id` 值。

```python theme={null}
# Good: Different thread IDs for concurrent operations
config_a = {"configurable": {"thread_id": "task-a"}}
config_b = {"configurable": {"thread_id": "task-b"}}

# These can run concurrently without conflicts
await asyncio.gather(
    agent.ainvoke({"messages": [...]}, config=config_a),
    agent.ainvoke({"messages": [...]}, config=config_b),
)
```

***

## API 参考

有关所有功能和配置的详细文档，请参阅：

* [langchain-aws API 参考](https://reference.langchain.com/python/langchain-aws)
* [Amazon Bedrock AgentCore 文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html)
* [浏览器代理](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-proxies.html)
* [浏览器扩展](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-extensions.html)
* [浏览器配置文件](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-profiles.html)

***

> 官方原文：[src/oss/python/integrations/tools/bedrock\_agentcore\_browser.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/tools/bedrock_agentcore_browser.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.