通过 Bright Data 与 Composio 集成构建 AI Agent

在本教程中，你将了解：

Composio 是什么，以及它在 AI Agent 构建方面的独特能力。
为什么要通过 Composio 将 AI Agent 连接到 Bright Data。
Composio 中可用的 Bright Data 工具列表。
如何使用 Composio 与 OpenAI Agents 让 Bright Data 为 AI Agent 赋能。

让我们开始吧！

什么是 Composio？

Composio 是一个一体化平台，使 AI Agent 与 LLM 能够与真实世界的工具进行交互。具体来说，它提供与 870+ 工具包的即插即用集成，并为你处理身份验证、触发器与 API 映射。

Composio 基于云基础设施构建，同时提供开源的 Python 与 TypeScript SDK，可在 GitHub 仓库（26.4k stars）中获取。这展示了这种新颖的 AI Agent 构建方式在开发者社区中的流行度与采用度。

Composio 兼容多种框架下的 Agent，确保工具调用准确，并提供实时可观测性。相关功能包括多 Agent 支持、可进化技能（随着 Agent 使用不断提升）、用于扩展的托管 MCP 网关，以及符合 SOC 2 的安全合规能力。

为什么要通过 Composio 将 AI Agent 连接到 Bright Data

Composio 这类解决方案的意义很简单：LLM 天生存在局限。毕竟，如果没有提供特定工具，它们无法直接与外部世界交互。这正是 Composio 的用武之地！

Composio 极大简化了 AI Agent 对来自数百家提供商工具的发现、接入与使用。现在，LLM 最大的两个缺点是：

它们只能基于自身的训练数据进行工作，而模型一旦发布，这些数据很快就会过时。
它们无法直接与 Web 交互，而当今大多数信息与价值都产生在 Web 上。

这两个问题可以通过让 Bright Data 为 AI Agent 赋能来解决——Bright Data 是 Composio 中官方提供的工具包之一。

Bright Data 解决方案让 AI Agent 能够搜索 Web、获取最新信息并与之交互。这得益于以下能力：

SERP API：从 Google、Bing、Yandex 等搜索引擎大规模获取搜索结果，并避免被封禁。
Web Unlocker API：访问任意网站并获得干净的 HTML 或 Markdown，自动处理代理、IP 轮换、指纹与验证码（CAPTCHA）。
Web Scraping APIs：从 Amazon、LinkedIn、Yahoo Finance、Instagram 等主流平台以及 100+ 更多来源获取结构化数据。
以及其他解决方案……

这些服务被封装为 Composio 专用工具，你可以使用任意受支持的 AI Agent 技术轻松将它们接入你的 AI Agent。

Composio–Bright Data 连接：工具列表

Composio 中可用的 Bright Data 工具包括：

工具	标识符	说明
触发站点抓取（Trigger Site Crawl）	`BRIGHTDATA_CRAWL_API`	用于触发站点抓取任务，从多页面或整个域名中提取内容。当你需要针对某个数据集与 URL 列表启动抓取时使用。
浏览可用 Scraper（Browse Available Scrapers）	`BRIGHTDATA_DATASET_LIST`	列出 Bright Data Marketplace 中所有可用的预制 Scraper（数据集）。当你需要浏览可用于结构化抓取的数据源时使用。
筛选数据集（Filter Dataset）	`BRIGHTDATA_FILTER_DATASET`	对 Marketplace 数据集应用自定义筛选条件（BETA）。在选择数据集后使用，以生成筛选后的快照。
获取可用城市（Get Available Cities）	`BRIGHTDATA_GET_LIST_OF_AVAILABLE_CITIES`	获取指定国家/地区可用的静态网络城市。当你在选择国家/地区后需要配置静态代理端点时使用。
获取可用国家/地区（Get Available Countries）	`BRIGHTDATA_GET_LIST_OF_AVAILABLE_COUNTRIES`	列出可用国家/地区及其 ISO 3166-1 alpha-2 代码。当你在创建代理前需要用有效的国家代码配置 Zone 时使用。
下载已抓取数据（Download Scraped Data）	`BRIGHTDATA_GET_SNAPSHOT_RESULTS`	通过快照 ID 获取已完成抓取任务的数据。在触发抓取或筛选数据集后使用，以下载采集到的数据。
检查抓取状态（Check Crawl Status）	`BRIGHTDATA_GET_SNAPSHOT_STATUS`	通过快照 ID 检查抓取任务的处理状态。在尝试下载结果前调用，以确保采集已完成。
列出 Unlocker Zone（List Unlocker Zones）	`BRIGHTDATA_LIST_WEB_UNLOCKER_ZONES`	列出你已配置的 Web Unlocker zone 与代理端点。用于查看可用于网页抓取与绕过反爬的可用 Zone。
SERP 搜索（SERP Search）	`BRIGHTDATA_SERP_SEARCH`	通过 Bright Data 的 SERP Scrape API 在不同搜索引擎上执行 SERP（搜索引擎结果页）搜索。用于获取搜索结果、热门趋势或竞品分析数据。该动作提交异步请求，并返回用于追踪的响应 ID。
Web Unlocker	`BRIGHTDATA_WEB_UNLOCKER`	绕过机器人检测、验证码以及其他反爬机制以提取网页内容。当你需要抓取会阻止自动化访问或需要 JavaScript 渲染的网站时使用。

如何在 Composio 中构建由 Bright Data 驱动的 AI Agent

在本分步章节中，你将学习如何使用 Composio 将 Bright Data 集成到 AI Agent 中。具体来说，你将了解如何在 Python 中使用 OpenAI Agents 构建 AI Agent，并通过 Composio SDK 将其连接到 Bright Data。

请按以下说明操作！

先决条件

为完成本教程，请确保你具备以下条件：

本地已安装 Python 3.9。
一个 Composio 账号。
一个 OpenAI API key。
一个已设置 API key 的 Bright Data 账号。

关于如何创建 Bright Data 账号并生成 API key 的更多指引，请参考 Bright Data 官方文档。

步骤 #1：使用 OpenAI Agents 在 Composio 快速开始

如果你还没有账号，请注册 Composio，或直接登录。你将进入“Overview（概览）”页面：
Composio 的 “Overview” 页面
该页面包含使用 OpenAI Agents 配置一个与 Composio 集成的简单 AI Agent 的说明。Web 控制台还提供 Claude Agents、LangChain、Vercel AI 以及其他多个框架的示例。

在本指南中，我们将使用 OpenAI Agents SDK 构建一个通过 Composio 连接 Bright Data 的 AI Agent。当然，你也可以很容易将下面的示例改写为任意其他受支持的 AI Agent 框架。

注意：也可以看看如何将 Bright Data 直接集成到 OpenAI Agents SDK。

首先创建项目文件夹并进入：

mkdir composio-bright-data-ai-agent
cd composio-bright-data-ai-agent

接着，初始化虚拟环境：

python -m venv .venv

在项目根目录新增一个名为 agent.py 的文件。此时目录结构如下：

composio-bright-data-ai-agent/
├── .venv/
└── agent.py

agent.py 将包含 AI Agent 的定义逻辑。

用你喜欢的 Python IDE 打开项目文件夹，例如 PyCharm Community Edition 或 Visual Studio Code + Python 扩展。

现在激活刚创建的虚拟环境。Linux 或 macOS 运行：

source .venv/bin/activate

Windows 则执行：

.venv/Scripts/activate

在虚拟环境激活后，安装 “Overview” 页面列出的必要 PyPI 包：

pip install composio composio-openai-agents openai-agents

该应用依赖包括：

composio：用于与 Composio 平台交互的 Python SDK，支持工具执行、鉴权处理与 AI 框架集成。
composio-openai-agents：将 Composio 工具与 OpenAI Agents 框架连接的集成层，支持无缝的基于 Agent 的工作流。
openai-agents：轻量、与提供商无关的框架，用于跨 OpenAI API 与 100+ LLM 提供商构建多 Agent 工作流。

完成！你已经搭好了一个 Composio + OpenAI Agents 项目。

步骤 #2：使用环境变量配置 API Key 加载

你的 AI Agent 将连接到包括 Composio 与 OpenAI 在内的第三方服务。为避免将凭据直接硬编码在脚本里，你将配置 Agent 从 .env 文件读取 API key。

首先在已激活的虚拟环境中安装 python-dotenv：

pip install python-dotenv

在 agent.py 文件顶部添加如下导入：

from dotenv import load_dotenv

接着在项目根目录创建 .env 文件：

composio-bright-data-ai-agent/
├─── .venv/
├─── agent.py
└─── .env    # <-----

在 .env 中写入你的 Composio 与 OpenAI API key：

COMPOSIO_API_KEY="<YOUR_COMPOSIO_API_KEY>"
OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

将占位符替换为你的真实 API key。如果你不确定在哪里找到 Composio API key，可以在账号的 “Settings（设置）”中查看：

最后，在 agent.py 中通过调用以下方法加载环境变量：

load_dotenv()

完成！你的脚本现在可以安全地从 .env 读取所需密钥，而不会在代码中暴露它们。

步骤 #3：在 Composio 中配置 Bright Data 工具包

要在 Composio 中配置 Bright Data 工具包，你需要在 Composio 控制台完成几个步骤。

首先在 “Overview” 选项卡中点击 “Browser Toolkits” 区块：
选择 “Browser Toolkits” 区块

你将跳转到 Composio 工具包页面：
Composio 的 “All Toolkits” 页面

在这里，你可以浏览 Composio 支持的所有集成。在搜索框中输入 “bright data”，然后点击对应卡片：
选择 “Bright Data” 工具包卡片

你将进入 Composio 的 Bright Data 工具包页面：
点击 “Add to Project” 页面
在此页面中，你可以探索可用工具、查看文档并了解使用细节。要继续，请点击 “Add to Project”。

当系统提示配置鉴权信息时：

设置一个 Auth Config Name（可保留默认自动生成名称）。
选择鉴权方式：API KEY（这是 Bright Data 的唯一主要鉴权选项）。

准备好后，点击 “Create Bright Data Auth Config” 继续：

注意：Composio Auth Config 是一种可复用配置，用于安全存储外部服务的凭据、鉴权方式与权限。你的 AI Agent 将通过 Composio SDK 使用该 Auth Config，以编程方式连接 Bright Data 工具。

很好！接下来需要在 Composio 中对 Bright Data 集成进行认证。

步骤 #4：认证 Bright Data 集成

在 Composio 中添加 Bright Data 工具包后，你需要连接你的 Bright Data 账号，确保集成可正常工作。这允许 Composio 访问 Bright Data 的网页抓取与数据服务，并通过 Composio SDK 将其暴露给你的 AI Agent。

要连接 Bright Data 账号，请在相应的 “Auth Configs” 页面点击 “Connect Account”：
点击 “Connect Account” 按钮

你会看到一个 External User ID：
Composio External User ID

复制该值，并在你的 agent.py 中将其粘贴为 Python 变量：

COMPOSIO_EXTERNAL_USER_ID = "<YOUR_COMPOSIO_EXTERNAL_USER_ID>"

在 Composio 中，User ID 用于决定访问哪些已连接账号与数据。每次工具执行、授权请求与账号操作都需要一个 userId 来定位正确上下文。本质上，User ID 像是容器，用于按工具包对已连接账号进行分组。它们可以代表个人用户、团队，甚至整个组织。

接下来，点击 “Connect Account” 继续。系统会提示你输入 Bright Data API key：
认证连接你的 Bright Data 账号

粘贴你的 Bright Data API key，并点击 “Connect Account” 完成连接。完成后，你应在 “Connected Accounts” 选项卡看到状态为 “ACTIVE” 的已连接账号：
Bright Data 账号连接

这表明 Composio 已通过你的 Bright Data API key 成功完成认证。现在 Bright Data 工具包已经可以在 AI Agent 中使用了！

你甚至可以通过 Composio Web 应用的 “Playground” 功能直接测试集成：

很好！Bright Data 现已在 Composio 中完成认证与集成。

步骤 #5：初始化 Composio 会话

现在，你已经具备了通过 Composio SDK 将基于 OpenAI Agents 的 AI Agent 连接到 Bright Data 所需的一切。

先使用 OpenAI Agents provider 初始化 Composio：

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider

# Initialize Composio with the OpenAI Agents provider
composio = Composio(provider=OpenAIAgentsProvider())

注意：Composio 构造函数会自动查找你已设置的 COMPOSIO_API_KEY 环境变量并用于认证。你也可以通过 api_key 参数显式传入 API key。

接着创建一个仅限 Bright Data 集成的 Tool Router 会话：

# Create a Tool Router session
session = composio.create(
    user_id=COMPOSIO_EXTERNAL_USER_ID,
    toolkits=["brightdata"],
    auth_configs={"brightdata": "ac_XXXXXXXXX"}, # Replace with your Auth Config ID for the Bright Data toolkit
)

Tool Router 是 Composio 最新、且已成为默认的方式，用于在 AI Agent 内驱动工具。它是一个统一接口，使 Agent 能发现可用工具、规划使用哪些工具、处理鉴权，并在数千个 Composio 集成上执行操作。它提供一组元工具在幕后管理这些任务，而不至于让 Agent 的上下文被工具细节淹没。

composio.create() 会初始化一个 Tool Router 会话，定义 Agent 的运行上下文。默认情况下，Agent 可访问所有 Composio 工具包，并在运行时被提示对它想使用的工具进行认证。

但在本例中，你已在 Composio 控制台配置了 Bright Data，因此你希望在代码中显式连接它。你需要：

在 toolkits 参数中指定 "brightdata"（这是 Composio 中 Bright Data 工具包的官方 slug）。
在 auth_configs 中将 "brightdata" 映射到其 Auth Config ID。

如果你想知道在哪里找到这些信息（slug + Auth Config ID），可在 Composio 控制台 Bright Data 工具包的 “Auth Configs” 页面查看：
Auth Config ID 与工具包 slug

注意：在 Composio 中，Auth Config ID 以 “ac” 前缀开头。同时，工具包 slug 不区分大小写，所以 "BRIGHTDATA" 等同于 "brightdata"。

现在，你可以这样检查 Bright Data 是否正确连接：

toolkits = session.toolkits()
for toolkit in toolkits.items:
    print(toolkit.name)
    print(toolkit.connection)

输出应为：

Bright Data
ToolkitConnection(is_active=True, auth_config=ToolkitConnectionAuthConfig(id='ac_XXXXXXXXX', mode='API_KEY', is_composio_managed=False), connected_account=ToolkitConnectedAccount(id='ca_YYYYYYYY', status='ACTIVE'))

这确认了：

工具包连接处于激活状态。
已连接账号状态为 ACTIVE。

这意味着 Composio SDK 已成功连接到你的 Bright Data 集成，工具包已可供 AI Agent 使用。太棒了！

步骤 #6：定义 AI Agent

基于 Composio Tool Router 会话，获取可用工具：

tools = session.tools()

将这些工具传给一个 OpenAI Agents AI Agent，如下所示：

from agents import Agent

agent = Agent(
    name="Web Data Assistant",
    instructions=(
        "You are a helpful assistant with access to Bright Data’s toolkit "
        "for web scraping, data access, and web unlocking."
    ),
    model="gpt-5-mini",
    tools=tools,
)

这会创建一个由 GPT-5 mini 模型驱动的 Web 数据助手，并且它完全知晓自己已接入 Bright Data 工具。

注意：对 OpenAI 账号的认证会自动完成，因为 OpenAI Agents SDK 会查找你之前设置的 OPENAI_API_KEY 环境变量。

完成！你现在拥有一个 OpenAI 驱动的 AI Agent，并通过 Composio 以更简化的方式集成了 Bright Data。接下来只需用真实场景测试它。

步骤 #7：运行 Agent

为了验证 AI Agent 是否正常工作，你需要给它一个必须访问 Web 数据的任务。例如，你可以让它处理一个常见营销场景：基于评论对某产品做情感分析。

这里我们聚焦于 Composio 产品在 G2 上的评论。按如下方式指定任务：

task = """"
1. Retrieve the reviews from the following G2 URL using the most appropriate scraper/dataset:
'https://www.g2.com/products/composio/reviews'
2. Wait and poll until the snapshot becomes ready.
3. Retrieve the snapshot containing all collected data.
4. Analyze the reviews and the retrieved information.
5. Provide a structured Markdown report that includes:
   - A sentiment analysis section with direct quotes from the reviews
   - Actionable insights and recommendations for improvement
"""

普通 LLM 无法完成这项任务，因为它无法访问实时的 G2 评论。而且由于 G2 的反爬措施非常激进，它也以“难抓取”而闻名。

相应地，期望 AI Agent 的行为是：

调用 Bright Data 工具为该场景选择最合适的 Scraper（例如 Bright Data G2 Scraper）。
在目标 G2 URL 上执行该 Scraper。
使用专用工具等待并轮询，直到包含抓取评论的快照（snapshot）可用。
分析快照并生成最终的结构化报告。

执行 Agent：

import asyncio
from agents import Runner

# Run the AI agent
async def main():
    result = Runner.run_streamed(
        starting_agent=agent,
        input=task,
        max_turns=50 # To avoid blocks, as the snapshot checks more than 10 (default max_turns) tool calls
    )

    # Stream the agent result in the terminal
    async for event in result.stream_events():
        # Print model output text as it streams
        if event.type == "raw_response_event":
            # Check if the event has output text data (response.output_text.delta)
            if event.data.type == "response.output_text.delta":
                print(event.data.delta, end="", flush=True)

asyncio.run(main())

很好！你的 Composio + Bright Data AI Agent 现已完成。

步骤 #8：整合全部代码

你的 agent.py 现在应包含：

import asyncio
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner
from dotenv import load_dotenv

# Load environment variables from the .env file
load_dotenv()

# The Composio external user ID
COMPOSIO_EXTERNAL_USER_ID = "pg-YYYYYYYYYYYYYYYYYYYYYYYYYYYYY" # Replace with your Composio User ID

# Initialize Composio with the OpenAI Agents provider
composio = Composio(provider=OpenAIAgentsProvider())

# Create a Tool Router session
session = composio.create(
    user_id=COMPOSIO_EXTERNAL_USER_ID,
    toolkits=["brightdata"],
    auth_configs={"brightdata": "ac_XXXXXXXXX"}, # Replace with your Auth Config ID for the Bright Data toolkit
)

# Access the Composio tools
tools = session.tools()

# Create an AI agent with tools using the OpenAI Agents SDK
agent = Agent(
    name="Web Data Assistant",
    instructions=(
        "You are a helpful assistant with access to Bright Data’s toolkit "
        "for web scraping, data access, and web unlocking."
    ),
    model="gpt-5-mini",
    tools=tools,
)

# Describe the sentiment analysis task involving fresh web data from G2
task = """"
1. Retrieve the reviews from the following G2 URL using the most appropriate scraper/dataset:
'https://www.g2.com/products/composio/reviews'
2. Wait and poll until the snapshot becomes ready.
3. Retrieve the snapshot containing all collected data.
4. Analyze the reviews and the retrieved information.
5. Provide a structured Markdown report that includes:
   - A sentiment analysis section with direct quotes from the reviews
   - Actionable insights and recommendations for improvement
"""

# Run the AI agent
async def main():
    result = Runner.run_streamed(
        starting_agent=agent,
        input=task,
        max_turns=50 # To avoid blocks, as the snapshot checks more than 10 (default max_turns) tool calls
    )

    # Stream the agent result in the terminal
    async for event in result.stream_events():
        # Print model output text as it streams
        if event.type == "raw_response_event":
            # Check if the event has output text data (response.output_text.delta)
            if event.data.type == "response.output_text.delta":
                print(event.data.delta, end="", flush=True)

asyncio.run(main())

在已激活的虚拟环境中运行：

python agent.py

Agent 将花一些时间通过 Bright Data 服务自动获取所需数据。完成后，它会在终端中流式输出一份 Markdown 报告：
Agent 生成的 Markdown 报告结果片段

将输出复制到 Markdown 查看器中，你应该会看到类似如下的内容：
查看 Markdown 报告

注意，该报告篇幅较长、准确，并且引用了来自真实 G2 评论的原文：
目标页面中的 G2 评论

要更好理解幕后发生了什么，请查看你 Composio 账号中的 “Logs” 选项卡：

你会看到 Agent 调用了：

Composio Bright Data 的 “Browse Available Scrapers” 工具（BRIGHTDATA_DATASET_LIST）以获取所有可用抓取 API 与数据集列表。
Composio Bright Data 的 “Trigger Site Crawl”（BRIGHTDATA_CRAWL_API）在指定 URL 上触发 G2 Scraper，从而在 Bright Data 云端启动一个异步抓取任务。
Composio Bright Data 的 “Download Scraped Data” 工具（BRIGHTDATA_GET_SNAPSHOT_RESULTS），并持续轮询直到包含采集数据的快照就绪。

这完全符合预期行为，证明 AI Agent 已成功集成 Bright Data。

就是这样！你仅用约 65 行代码，就构建了一个 AI Agent，并与 Composio 中可用的所有 Bright Data 解决方案完成了完整集成。

对 G2 评论做情感分析只是 Bright Data Web 数据工具支持的众多用例之一。你可以调整提示词来测试其他场景，并探索 Composio 文档以发现更多高级功能，让你的 Agent 具备生产可用能力！