第 1 篇把三角色 Crew 跑通之后,一个尴尬很快浮出水面:研究员的全部"调研",其实只发生在模型的参数里。它没搜过网、没读过文件,写进要点清单的年份与数字全是训练记忆的复述——模型越自信,这种"一本正经的旧闻"越难被审核员识破。解法不在提示词里,在工具上:给 Agent 一个搜索工具,它才第一次拥有"看外面"的能力。
工具是 Agent 从"会说"到"会做"的分水岭,也是本系列第 2 篇的主题。全文按"体系鸟瞰 → 内置盘点 → 自定义两条路 → 挂载与选择 → 设计艺术 → MCP → 实战"展开,实战部分给第 1 篇的研究员真正装上搜索工具。版本口径同第 1 篇:CrewAI v1.15.41,2026 年 11 月。
1、工具体系三层鸟瞰
CrewAI 的工具体系是个三层结构,塔基是一个抽象基类。所有工具——不管来自哪个渠道——最终都是 BaseTool 的实例或等价物,都要回答同样三个问题:叫什么(name)、干什么(description)、怎么干(_run 方法)。先立住一句总纲:工具的 name 与 description 是写给 LLM 看的提示词,_run 才是写给人看的实现。三层结构画出来:
解读:第一层是 from crewai.tools import BaseTool 拿到的抽象基类,定义工具的契约(注意导入路径是 crewai.tools,与网上旧教程的写法可能对不上号);第二层是官方维护的内置工具包,搜索、抓取、文件读写开箱即用;第三层是你自己的业务工具,继承子类或装饰器函数皆可。另有一条捷径:官方工具文档明确 Agent 可以直接接收 LangChain 生态的工具,存量代码不必重写。
运行时的选择机制值得单说。Agent 启动时,框架把每个工具的 name 与 description 组装成函数调用(function calling)的 schema 注入上下文;模型每一轮推理,都是拿着这些描述判断"该调谁"——描述写得糊,模型就选不准,这一点第 5 节展开。
2、内置工具盘点
内置工具统一住在独立的 crewai-tools 包里,crewai 主包并不附带,安装用官方 extras 写法一步到位:
pip install 'crewai[tools]'
装完即可从 crewai_tools 导入。常用的几件整理如下:
| 工具 | 用途 | 使用要点 |
|---|---|---|
SerperDevTool |
谷歌搜索 | 需配 SERPER_API_KEY |
ScrapeWebsiteTool |
抓取指定网址正文 | 常与搜索工具前后搭配 |
WebsiteSearchTool |
抓取并语义检索网站 | RAG 型,依赖嵌入模型 |
FileReadTool |
读取本地文件 | 实例化时传文件路径 |
DirectoryReadTool |
列出目录内容 | 传目录路径即可 |
PDFSearchTool |
PDF 内容语义检索 | 同为 RAG 型工具 |
DirectorySearchTool |
目录内文件语义检索 | 同上 |
这张表只挑了最常用的七件,完整清单见官方工具文档。更该留意的是维护状态:内置清单一直在收敛,旧教程里的常客未必还在。两个确凿的例子——CodeInterpreterTool 已从 crewai-tools 包移除,Agent 的 allow_code_execution 与 code_execution_mode 参数随之标记弃用;SeleniumScrapingTool 也不再出现在当前官方工具页的清单里。
注意:
allow_code_execution默认 False 且已弃用。官方建议改用 E2B、Modal 这类专用沙箱服务承载代码执行,不要在 Agent 参数上恋战。
所以内置工具的定位是"标准件":搭原型时拿来即用,进生产前先到官方文档核对一遍存在性,再考虑要不要换成自己的实现。
3、自定义 Tool 两条路
内置包没有的能力,就得自己写。CrewAI 给了两条路:面向对象的继承 BaseTool,与函数式的 @tool 装饰器。两条路产出同一种东西——一个 BaseTool 实例——差别只在表达方式。
3.1、继承 BaseTool
先看子类写法。以一个真实场景为例:投稿前核对中文文章字数。代码如下:
from typing import Type
from pydantic import BaseModel, Field
from crewai.tools import BaseTool
class WordCountInput(BaseModel):
"""中文字数统计的输入定义"""
text: str = Field(..., description="待统计的正文文本")
class CjkWordCountTool(BaseTool):
name: str = "中文字数统计"
description: str = (
"统计一段中文文本的汉字数与总字符数,"
"用于投稿前核对篇幅要求"
)
args_schema: Type[BaseModel] = WordCountInput
def _run(self, text: str) -> str:
cjk = sum(1 for c in text if "一" <= c <= "鿿")
return f"汉字 {cjk} 个,总字符 {len(text)} 个"
走读四个要点。name 与 description 会被组装进工具 schema,description 要写"何时该用我"而不只是"我是什么";args_schema 用 Pydantic 模型声明输入,Field 的 description 同样暴露给模型,是防参数幻觉的第一道闸;_run 是执行体,参数名与模型字段对齐,返回值是字符串。第四点是进阶能力:_run 也可以返回 Pydantic 模型,框架会转成 JSON 再交给 Agent,而你的下游代码通过 tool.run() 能直接拿到原生对象。
3.2、@tool 装饰器
同一个工具用装饰器改写,体积立刻缩水。写法如下:
from crewai.tools import tool
@tool("页面标题抓取")
def fetch_page_title(url: str) -> str:
"""抓取指定 URL 的页面并返回 title 标签内容。
url 必须是完整的 http 或 https 地址。"""
import requests
resp = requests.get(url, timeout=10)
text = resp.text
start, end = text.find("<title>"), text.find("</title>")
return text[start + 7 : end].strip()
解读:装饰器的第一个参数是工具名;函数签名的类型注解自动变成参数 schema;docstring 整段成为 description——第一行分量最重,尽量一句话讲清用途与适用时机。异步函数同样支持,直接装饰 async def 即可。工程上要提醒的是:docstring 是描述的唯一来源,函数写完顺手补 docstring 应该成为肌肉记忆。
3.3、两条路如何选择
两条路的差异集中在表达力与仪式感上,对比如下:
| 维度 | 继承 BaseTool | @tool 装饰器 |
|---|---|---|
| 代码量 | 类骨架较多 | 一个函数搞定 |
| 输入声明 | args_schema 显式建模 | 类型注解自动生成 |
| 状态承载 | 可持有实例属性 | 只能依赖闭包变量 |
| 适用场景 | 复用组件、复杂逻辑 | 一次性小工具 |
选型经验一句话:验证想法用装饰器,沉淀资产用子类。装饰器适合把三行函数立刻变成 Agent 能力;当工具需要初始化客户端连接、维护缓存、被多个项目复用时,类写法的结构感更值钱。"状态承载"一行值得展开:子类可以在 __init__ 里建好数据库连接、HTTP 会话,_run 直接复用——装饰器只能靠闭包达到类似效果,逻辑一复杂可读性掉得很快。
4、把工具挂到 Agent 上
挂载本身只需一行:Agent 的 tools 参数接收 BaseTool 实例列表,默认空列表(详见Agent 官方文档)。给研究员挂两件工具的写法如下:
researcher = Agent(
role="资深技术调研员",
goal="围绕主题收集准确、最新的关键事实",
backstory="十年调研经验,先搜索再下结论",
tools=[search_tool, fetch_page_title],
verbose=True,
)
挂上之后,模型怎么在工具间做选择?机制回到第 1 节那句总纲:每轮推理时,工具的 name、description 与参数 schema 都摊在模型面前,它按"哪个描述最匹配当前意图"来挑。由此推出两条实操纪律。其一,工具数量克制:列表越长误选率越高,一个 Agent 配两三件聚焦的工具,好过十件大杂烩。其二,职责重叠要划界:两件工具若有交集,在 description 里写清分工,比如"仅用于查证数字,不用于找观点"。
还有一个容易被忽略的参数:function_calling_llm。它允许单独指定负责工具调用的模型——主推理用强模型、工具分发用快模型的组合,在 token 开销上有立竿见影的优化空间。
5、工具的设计艺术
写工具的 API 十分钟就能学会,写好工具是另一回事。三个维度最容易拉开差距:粒度、命名、错误返回。好做法与常见坑对照如下:
| 设计点 | 好做法 | 常见坑 |
|---|---|---|
| 粒度 | 一件工具一个职责 | 万能工具什么都干,模型选不准 |
| 命名 | 动词开头,名字自解释 | 名字抽象,描述留空或照抄类名 |
| 错误返回 | 返回带原因的失败信息 | 裸抛异常,整次执行中断 |
| 返回内容 | 精炼文本,只给结论 | 整页 HTML 原样塞回上下文 |
粒度的判断标准:两个职责的输入输出天然不同,就该拆成两件。搜索与抓取要分开,不是因为技术实现不同,而是模型在"我要找信息"与"我要读这个页面"两个时刻,需要能精确表达不同意图。返回内容常被轻视——把 50 KB 原始 HTML 直接返回,等于往上下文里倒垃圾,_run 里先提取再返回,是工具作者的分内事。
错误处理如今有正式机制:工具遇到可预期的失败时,返回 ToolFailure 而不是抛异常。示例如下:
from pathlib import Path
from crewai.tools.tool_failure import ToolFailure
# BaseTool 子类中的 _run 方法(节选)
def _run(self, file_path: str) -> str:
try:
return Path(file_path).read_text(encoding="utf-8")
except FileNotFoundError:
return ToolFailure(
message=f"文件不存在:{file_path},请核对路径",
retryable=False,
)
retryable 标记这次失败值不值得模型重试。框架侧还有配套的 ToolFailurePolicy,取值 ignore、warn(默认)、raise,可配在 Task、Agent、Crew 等层级,优先级按工具、Task、Agent、Crew 逐级回落,兜底为 warn。另一个内置兜底是重复调用熔断:模型在同一次任务里连续第 5 次发起一模一样的调用会被自动叫停——这通常是描述太含糊、模型原地打转的信号,与其调参不如回去重写 description。
6、与 MCP 的关系
MCP(Model Context Protocol)把"工具"从框架私产变成了跨框架的开放生态:一个 MCP server 写一次,任何支持协议的客户端都能用。CrewAI 在这方面已是全面接入——Agent 新增了 mcps 参数,可以直接挂 MCP server,不必再手工包成 BaseTool。写法如下:
from crewai import Agent
from crewai.mcp import MCPServerStdio
researcher = Agent(
role="资料调研员",
goal="读取本地资料目录并归纳要点",
backstory="十年调研经验,擅长从文档中提取事实",
mcps=[
MCPServerStdio(
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem"],
)
],
)
这段配置把 filesystem server 以子进程方式拉起,它的全部工具自动进入 Agent 的可选清单。HTTP 形态的 server 用 MCPServerHTTP(streamable=True 走流式传输),SSE 旧协议对应 MCPServerSSE,工具太多时还能用 tool_filter 白名单过滤。需要更细的控制(连接超时、生命周期管理)时,换 crewai_tools 里的 MCPServerAdapter——安装需 pip install 'crewai-tools[mcp]',它以 context manager 的形式产出普通 tools 列表,挂回 tools 参数即可。对本系列的启示很直接:自定义 BaseTool 承载独有的业务能力,MCP 通道复用业界共享的通用能力,两条通道并存,按来源选边。细节见MCP 官方文档。
7、给研究员装上搜索
回到第 1 篇的三角色流水线,把研究员从"凭记忆调研"升级成"真搜真查"。第一步装包配钥匙:
pip install 'crewai[tools]'
export SERPER_API_KEY=你的密钥
密钥在 serper.dev 注册可得,免费档有每日配额。第二步只改研究员的定义,写手、审核员与三个 Task 的组装全部不动:
from crewai import Agent, Crew, Task, Process
from crewai_tools import SerperDevTool
researcher = Agent(
role="资深技术调研员",
goal="用搜索核实关键事实,宁可少写不可写错",
backstory="十年科技行业调研经验,先搜索再下结论",
tools=[SerperDevTool()], # 谷歌搜索,读环境变量密钥
verbose=True,
)
research_task = Task(
description="针对主题 {topic} 搜索并收集 3~5 条关键事实,"
"每条注明来源链接与时间。",
expected_output="带来源链接的要点清单",
agent=researcher,
)
三处变化值得点出。工具让 goal 与 backstory 的措辞更硬气——"宁可少写不可写错"这类承诺,没有搜索工具时只是修辞,挂上工具才真正落地。Task 描述同步升级为"注明来源链接",验收标准跟着能力走。最后开着 verbose=True 跑一遍,日志里能看到模型何时发起搜索、拿回了什么、如何消化进要点清单——这是观察"模型怎么用工具"的最佳窗口。
跑完对比第 1 篇的输出,差异通常在两处:数字与版本类事实不再过时,要点清单多了可点击的来源。审核员的存在感反而下降——上游供给质量上来了,下游把关的负担自然轻了。
8、总结
本文把 CrewAI 的工具系统拆到了底层:一切工具都履行 BaseTool 的契约——name 与 description 是给 LLM 的提示词,_run 是给人的实现;内置工具住在 crewai-tools 包里当标准件,但清单在收敛,CodeInterpreterTool 已移除、allow_code_execution 已弃用,用前先查官方文档;自定义有继承子类与 @tool 装饰器两条路,验证想法用装饰器、沉淀资产用子类;挂载靠 tools 参数,选择靠描述,粒度、命名、错误返回是设计上的三块试金石;MCP 通道(mcps 参数与 MCPServerAdapter)让你直接复用开放生态的工具服务。研究员装上 SerperDevTool 之后,三角色流水线才真正配得上"调研"二字。
三个练习留给读者:
- 给写手挂上第 3 节的中文字数统计工具,让初稿自查是否满足 800 字要求
- 用
FileReadTool让研究员先读一份本地背景资料再搜索,对比前后效果 - 把
tools=[SerperDevTool()]换成mcps参数挂一个搜索类 MCP server,体会两条通道的差异
对于正在搭多角色系统的工程师,建议把工具描述当成提示词工程的一部分认真打磨——模型的每一次工具选择,都是照着你写的那两行文字在做决定。入门篇的拼图还差一块,第 3 篇见。

