> ## Documentation Index
> Fetch the complete documentation index at: https://help.decodo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CrewAI

> decodo-crewai 软件包：为 CrewAI 的智能体和团队提供 Decodo 抓取、搜索、SERP 和电商工具。

`decodo-crewai` 是为 [**CrewAI**](https://www.crewai.com) 智能体提供实时网络数据的 Python 软件包。它为团队（crew）添加四个工具：一个以 Markdown 格式抓取任意公开 URL，另外三个从搜索引擎、Google AI 模式和电商商店返回解析后的 JSON。四者都运行在 [**Web Data API**](https://help.decodo.com/docs/cn/web-data-api-introduction.md) 之上。

> [!NOTE]
>
> 源代码、示例和最新版本请查看 [**crewAI 仓库**](https://github.com/Decodo/crewAI)。

## 功能

* **网页抓取**：获取任意公开页面，并向智能体提供干净的 Markdown
* **搜索**：解析后的 Google 网页结果或 Amazon 商品列表
* **SERP**：支持分页的 Google、Bing 和 Google AI 模式结果
* **电商**：来自 Amazon、Walmart 和 Target 的商品详情或搜索结果
* **CrewAI 集成**：标准的 `BaseTool` 类，可直接接入任何智能体、团队或流程
* **智能体可处理的失败**：失败的请求会以 CrewAI `ToolFailure` 的形式返回，而不是抛出异常

## 要求

* Python 3.10 至 3.13
* Decodo [**Web Data API 计划**](https://dashboard.decodo.com/web-data/pricing)。[**控制面板**](https://dashboard.decodo.com/)提供免费试用。

## 安装

```bash theme={null}
pip install decodo-crewai
```

这会一并安装 `crewai` 1.15.9 或更高版本，以及 [**Python SDK**](https://help.decodo.com/docs/cn/python-sdk.md)（`decodo-sdk`）2.5.0 或更高版本。

## 身份验证

在 [**Web Data API 演练场**](https://dashboard.decodo.com/web-data/playground)中，从您的 Web Data API 订阅复制 API 密钥，并将其存储在 `DECODO_API_KEY` 环境变量中。所有工具都从该变量读取密钥：

```bash theme={null}
export DECODO_API_KEY=your_api_key
```

您也可以直接将其传给某个工具：

```python theme={null}
DecodoWebScraperTool(api_key="your_api_key")
```

> [!WARNING]
>
> 这些工具仅接受 API 密钥。即便 Python SDK 支持较旧计划的基本身份验证令牌（base64 编码的 `username:password`），这些工具也不支持该令牌。

如果找不到密钥，工具在创建时就会抛出 `ValueError`，因此密钥缺失会在启动阶段暴露，而不是等到团队发出第一个网络请求时才失败。

## 快速开始

下面是一个单智能体团队，它会搜索网络并阅读找到的页面。CrewAI 会调用自己的 LLM，因此您还需要为其提供密钥——默认使用 OpenAI 的 `gpt-4.1-mini`：

```bash theme={null}
pip install decodo-crewai
export DECODO_API_KEY=your_api_key
export OPENAI_API_KEY=your_openai_key
```

```python theme={null}
# main.py
from crewai import Agent, Crew, Task

from decodo_crewai import DecodoSearchTool, DecodoWebScraperTool

researcher = Agent(
    role="Researcher",
    goal="Find and summarize up-to-date information from the web",
    backstory="You search the web, read the most relevant pages and report what they say.",
    tools=[DecodoSearchTool(), DecodoWebScraperTool()],
)

task = Task(
    description="Find the three most recent announcements about {topic} and summarize each one.",
    expected_output="Three bullet points, each with a one-sentence summary and the source URL.",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
print(crew.kickoff(inputs={"topic": "solid-state batteries"}))
```

若要使用其他模型，请设置 `MODEL`，例如 `MODEL=gpt-4.1`。其他提供商需要安装对应的 CrewAI 扩展并配置密钥，例如 `pip install "crewai[anthropic]"` 搭配 `ANTHROPIC_API_KEY` 和 `MODEL=anthropic/<model>`。

## 可用工具

| 类 | 向智能体显示的名称 | 用途 |
| - | - | - |
| `DecodoWebScraperTool` | `Decodo Web Scraper` | 抓取任意公开 URL 并返回 Markdown |
| `DecodoSearchTool` | `Decodo Search` | Google 或 Amazon 搜索，解析为 JSON |
| `DecodoSERPTool` | `Decodo SERP` | Google、Bing 或 Google AI 模式结果，解析为 JSON |
| `DecodoEcommerceTool` | `Decodo Ecommerce` | Amazon、Walmart 或 Target 商品，解析为 JSON |

您也可以不通过智能体，直接调用某个工具：

```python theme={null}
from decodo_crewai import DecodoSearchTool, DecodoWebScraperTool

print(DecodoWebScraperTool().run(url="https://ip.decodo.com"))
print(DecodoSearchTool().run(query="mechanical keyboard", source="amazon"))
```

每个工具在创建时都接受 `api_key`，默认取自 `DECODO_API_KEY`。下文中的参数则是智能体在每次调用时填写的参数。

### DecodoWebScraperTool

| 参数 | 类型 | 说明 |
| - | - | - |
| `url` | `str` | 要抓取的页面完整 URL，需包含 `https://` |
| `geo` | `str`，可选 | 发送请求的来源国家，使用国家名称，例如 `United States` |
| `js_render` | `bool`，可选 | 在无头浏览器中打开页面。仅当页面通过 JavaScript 加载内容时才需要 |

它会以 Markdown 字符串的形式返回页面。

| 构造参数 | 默认值 | 说明 |
| - | - | - |
| `api_key` | `DECODO_API_KEY` | Web Data API 密钥 |
| `max_chars` | `45000` | 超过该长度的 Markdown 会被截断，以便页面能放进智能体的上下文 |

页面被截断时，工具会追加最后一行，给出保留的字符数和完整字符数，让智能体知道自己并未取得整个页面。当某个智能体在一个任务中需要阅读多个页面时，请调低 `max_chars`：

```python theme={null}
DecodoWebScraperTool(max_chars=15_000)
```

### DecodoSearchTool

| 参数 | 类型 | 说明 |
| - | - | - |
| `query` | `str` | 搜索查询 |
| `source` | `"google"` 或 `"amazon"`，可选 | `google`（默认）返回网页结果，`amazon` 返回商品列表 |
| `geo` | `str`，可选 | Google：国家名称，例如 `United States`。Amazon：美国邮编，例如 `10001`；若配送到美国境外，则使用两位字母的国家代码，例如 `DE` |

### DecodoSERPTool

| 参数 | 类型 | 说明 |
| - | - | - |
| `query` | `str` | 搜索查询 |
| `engine` | `"google"`、`"bing"` 或 `"google_ai_mode"`，可选 | `google`（默认）或 `bing` 返回结果页；`google_ai_mode` 返回 Google 生成的 AI 回答及其引用的来源 |
| `page` | `int`，可选 | 要获取的结果页码，从 1 开始。`google_ai_mode` 会忽略该参数 |
| `geo` | `str`，可选 | 搜索的来源国家，例如 `United States` |

Bing 结果需在无头浏览器中渲染，可能耗时一分钟以上。

### DecodoEcommerceTool

请传入 `product_id` 或 `query` 之一，不要同时传入。

| 参数 | 类型 | 说明 |
| - | - | - |
| `store` | `"amazon"`、`"walmart"` 或 `"target"` | 要查询的商店 |
| `product_id` | `str`，可选 | 单个商品的详情。Amazon：ASIN，例如 `B09H74FXNW`。Walmart 或 Target：商品 URL 中的商品 ID |
| `query` | `str`，可选 | 改为搜索该商店的商品 |
| `zip_code` | `str`，可选 | 美国邮编，用于获取该配送地点的价格和库存情况，例如 `10001` |

Target 页面需在无头浏览器中渲染，可能耗时接近一分钟。

> [!NOTE]
>
> 三个 JSON 工具会返回完整的解析结果，不做截断。一次 Amazon 搜索的返回内容约为 117,000 个字符，足以挤占较小的上下文窗口，并体现在您的 LLM 账单上。请把这些工具交给确实需要完整结果集的智能体，而把范围较广的调研工作交给使用 `source="google"` 的 `DecodoSearchTool`。

## 错误

当请求失败时——无效的 API 密钥、触发速率限制、页面返回 `404`，或请求根本没有到达 Decodo 的网络错误——这些工具会返回 CrewAI `ToolFailure`，而不是抛出异常。智能体能够看到出了什么问题，并据此重试或改变策略，同时 CrewAI 会按照该智能体的 `tool_failure_policy` 记录这次失败。

每次失败都带有一个 `code`，其中值得重试的会标记为 `retryable`：

| `code` | 出现时机 | 是否可重试 |
| - | - | - |
| `authentication_failed` | Decodo 拒绝了该 API 密钥 | 否 |
| `invalid_params` | Decodo 拒绝了请求参数 | 否 |
| `rate_limited` | 您已达到订阅的速率限制 | 是 |
| `timeout` | 发往 Decodo 的请求超时 | 是 |
| `network_error` | 请求未能到达 Decodo | 是 |
| `empty_response`、`empty_content` | Decodo 未返回结果，或返回了没有内容的结果 | 否 |
| HTTP 状态码，例如 `404` 或 `503` | 目标站点返回了该状态码 | 仅 `429` 和 `5xx` |

## 示例团队

该仓库提供了一个[**调研团队**](https://github.com/Decodo/crewAI/tree/main/examples/research_crew)示例：研究员搜索 Google 并挑选五个来源，分析师用抓取工具逐一阅读，撰稿人再把笔记整理成带引用的 Markdown 报告。把它指向任意主题，它就会打印报告并保存到 `report.md`。

这些工具背后的完整 API 参数列表，请参阅[**参数**](https://help.decodo.com/docs/web-scraping-api-parameters-overview.md)。

***

## 相关内容

* [**LangChain（Python）**](https://help.decodo.com/docs/cn/langchain-python.md)：面向 LangChain 的 Decodo 工具和文档加载器。
* [**LlamaIndex**](https://help.decodo.com/docs/cn/llamaindex.md)：面向 LlamaIndex 的 Decodo 读取器和智能体工具。
* [**Python SDK**](https://help.decodo.com/docs/cn/python-sdk.md)：在 Python 中以类型化方式访问所有 Decodo 目标。
* [**MCP 服务器**](https://help.decodo.com/docs/cn/mcp.md)：将 AI 智能体和兼容 MCP 的工具连接到 Decodo。
* [GitHub 仓库](https://github.com/Decodo/crewAI)：查看源代码、示例和最新版本。

***

> [card] [支持](https://direct.lc.chat/12092754)
>
> 需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
> 您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。

> [card] [反馈](mailto:feedback@decodo.com)
>
> 找不到您要找的内容？请求一篇文章！ \
> 有反馈意见？分享您对我们如何改进的想法。


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