第 7 章 · 内置工具体系

本章目标：掌握 crewai-tools 的安装与常用内置工具的实战用法，理解工具的环境变量约定、与 Agent 的绑定方式，并能对 RAG 类工具建立正确认知。

7.1 安装 `crewai[tools]`

CrewAI 主包只包含框架核心，所有官方维护的工具都在独立的 crewai-tools 包中。官方推荐一条命令把两者一起装好：

bash

# 同时安装 crewai 核心 + crewai-tools 工具集
pip install 'crewai[tools]'

版本对应关系

crewai-tools 与 crewai 主包是配套发布的。混用不同时代的版本（例如新主包配一年前的 tools 包）是社区里"工具调用报错"的第一大来源。升级时请两个包一起升：pip install -U 'crewai[tools]'。

7.2 常用工具速览与实战

下面这些是最常用的非 RAG 类工具：

工具	用途	需要的外部条件
`SerperDevTool`	Google 搜索（返回摘要+链接）	`SERPER_API_KEY`
`ScrapeWebsiteTool`	抓取指定 URL 的正文全文	无
`FileReadTool`	读文件（支持多种格式）	无
`DirectoryReadTool`	列出目录结构	无
`CodeInterpreterTool`	执行 Python 代码做计算/数据处理	无（本地执行）
`WebsiteSearchTool`	对网站内容做 RAG 搜索	默认需要 embedding 提供商

一个完整的"搜索 → 抓取 → 落盘"研究小队示例：

python

import os

from crewai import Agent, Crew, Process, Task, LLM
from crewai_tools import SerperDevTool, ScrapeWebsiteTool, FileReadTool

# 全部示例统一使用 OpenAI 兼容的三方模型
llm = LLM(
    model="openai/deepseek-chat",                 # LiteLLM 规则：provider/model
    base_url="https://api.deepseek.com/v1",       # 三方 OpenAI 兼容端点
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    temperature=0.7,
)

# 实例化工具：同一个工具实例可以被多个 agent 复用
search_tool = SerperDevTool()            # 联网搜索（需要 SERPER_API_KEY）
scrape_tool = ScrapeWebsiteTool()        # 抓网页全文
file_tool = FileReadTool()               # 读本地文件

researcher = Agent(
    role="资深行业研究员",
    goal="用最少的搜索次数找到关于『边缘 AI 芯片』的高质量信息",
    backstory="十年科技行业分析经验，擅长快速甄别信息源可靠性。",
    llm=llm,
    tools=[search_tool, scrape_tool],   # 绑定该 agent 可用的工具
    verbose=True,
)

writer = Agent(
    role="技术编辑",
    goal="把研究员的发现整理成一篇结构清晰的中文简报",
    backstory="严谨的技术写作者，重视事实准确。",
    llm=llm,
    tools=[file_tool],
    verbose=True,
)

t1 = Task(
    description="搜索并抓取 2-3 篇关于边缘 AI 芯片市场趋势的资料，提炼要点。",
    expected_output="不超过 500 字的趋势要点列表，每条注明来源 URL。",
    agent=researcher,
)
t2 = Task(
    description="根据研究员的要点写成简报，保存到 brief.md。",
    expected_output="Markdown 格式简报。",
    agent=writer,
    output_file="brief.md",             # Task 级落盘，比让 agent 自己调文件工具更可靠
)

crew = Crew(agents=[researcher, writer], tasks=[t1, t2], process=Process.sequential)
crew.kickoff()

output_file vs 文件工具

需要"把结果写到磁盘"时，优先用 Task(output_file=...)，而不是指望模型自己调文件工具写文件——前者由框架保证执行，后者依赖模型自觉。

7.3 工具如何与 Agent 绑定

工具绑定有三条规则值得记住：

Agent 级绑定：Agent(tools=[...]) —— 只有这个 agent 能用这些工具；
Task 级追加：Task(tools=[...]) —— 只在该任务执行期间可用；
最小权限原则：只给 agent 完成其任务所必需的工具。工具越多，模型选错的概率越高，且提示词更长、成本更高。

python

# Task 级工具：只有"数据汇总"这一步允许执行代码
from crewai_tools import CodeInterpreterTool

analyst = Agent(
    role="数据分析师",
    goal="对销售数据做准确统计",
    backstory="精通 Python 数据处理的资深分析师。",
    llm=llm,
)

export_task = Task(
    description="读取 sales.csv 并计算各区域季度销售额汇总表。",
    expected_output="Markdown 表格。",
    agent=analyst,
    tools=[CodeInterpreterTool()],   # 仅此任务可用
)

7.4 环境变量管理

几乎所有联网工具都遵循"环境变量注入密钥"的约定（如 SERPER_API_KEY）。生产项目的推荐做法：

用 .env 文件 + python-dotenv 在程序入口加载，.env 加入 .gitignore；
密钥缺失时尽早失败：在创建工具前显式检查，而不是等运行到一半才报错。

python

import os
from dotenv import load_dotenv

load_dotenv()  # 从 .env 加载环境变量

def require_env(key: str) -> str:
    """缺少必需环境变量时立即抛错，避免跑到一半才失败。"""
    value = os.getenv(key)
    if not value:
        raise RuntimeError(f"缺少环境变量 {key}，请在 .env 中配置")
    return value

require_env("SERPER_API_KEY")      # 启动即校验
search_tool = SerperDevTool()

7.5 正确认识 RAG 类工具

名字里带 Search 的工具有两类，初学者最容易混淆：

联网搜索类（SerperDevTool、ExaSearchTool）：每次调用都请求外部搜索引擎，结果新鲜但不可控；
RAG 检索类（PDFSearchTool、CSVSearchTool、DirectorySearchTool、WebsiteSearchTool）：先把本地/指定来源的内容切块、嵌入、存入向量库，之后 agent 通过语义检索来"查资料"。它们都继承自通用的 RagTool。

python

import os
from crewai_tools import PDFSearchTool

# 把一份本地产品手册变成可检索的知识源（文件建议放在项目 knowledge/ 目录）
pdf_rag = PDFSearchTool(pdf="knowledge/product-manual.pdf")

support_agent = Agent(
    role="售后支持专家",
    goal="只依据产品手册回答用户问题",
    backstory="熟悉手册每一页的客服老手。",
    llm=llm,
    tools=[pdf_rag],
)

RAG 工具默认使用 OpenAI embedding；如果使用三方 OpenAI 兼容端点，可通过 embedder 配置指定（与记忆/知识库的 embedder 配置格式一致，详见第 10 章）。

RAG 工具 vs Knowledge

RAG 工具是被动的：只有当模型判断需要时才会调用。如果你希望某些事实"稳定可靠地"进入上下文，应该用第 11 章的 Knowledge Sources（框架在任务开始时检索注入），而不是依赖模型主动调工具。

本章小结

pip install 'crewai[tools]' 安装工具集，注意与主包版本配套升级；
常用组合：SerperDevTool 搜索 + ScrapeWebsiteTool 抓取 + FileReadTool 读文件；
工具在 Agent 级绑定，也可在 Task 级临时追加；遵循最小权限原则；
密钥一律走环境变量，入口处尽早校验；
区分"联网搜索类"与"RAG 检索类"工具，后者继承自 RagTool。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 安装 CrewAI 官方工具集的正确命令是？

2. 关于工具与 Agent 的绑定，下列说法错误的是？

3. PDFSearchTool 这类 RAG 工具的工作方式是？

4. 需要把某个任务的最终产出可靠地写入本地文件，最佳做法是？

🛠️ 动手实践

申请一个免费的 serper.dev key，复现 7.2 的"研究员+编辑"双人小队，把主题换成你所在行业的趋势。
用 PDFSearchTool 或 CSVSearchTool 把自己的一份资料变成可检索工具，设计 5 个问题测试召回质量。
为你的项目写一个 require_env 启动校验模块，把所有工具密钥检查集中到入口处，并故意删掉一个 key 验证快速失败。

下一章我们不再当"工具的使用者"，而是动手造工具：第 8 章 · 自定义工具开发。

第 7 章 · 内置工具体系 ​

7.1 安装 crewai[tools] ​

7.2 常用工具速览与实战 ​

7.3 工具如何与 Agent 绑定 ​

7.4 环境变量管理 ​

7.5 正确认识 RAG 类工具 ​

本章小结 ​

🧪 随堂测验

🛠️ 动手实践 ​

第 7 章 · 内置工具体系

7.1 安装 `crewai[tools]`

7.2 常用工具速览与实战

7.3 工具如何与 Agent 绑定

7.4 环境变量管理

7.5 正确认识 RAG 类工具

本章小结

🛠️ 动手实践