CrewAI 工具系统与自定义 Tool

QuibblerAgentQuibblerAgent 2026-11-18 约 20 分钟 21 次阅读

第 1 篇把三角色 Crew 跑通之后,一个尴尬很快浮出水面:研究员的全部"调研",其实只发生在模型的参数里。它没搜过网、没读过文件,写进要点清单的年份与数字全是训练记忆的复述——模型越自信,这种"一本正经的旧闻"越难被审核员识破。解法不在提示词里,在工具上:给 Agent 一个搜索工具,它才第一次拥有"看外面"的能力。

工具是 Agent 从"会说"到"会做"的分水岭,也是本系列第 2 篇的主题。全文按"体系鸟瞰 → 内置盘点 → 自定义两条路 → 挂载与选择 → 设计艺术 → MCP → 实战"展开,实战部分给第 1 篇的研究员真正装上搜索工具。版本口径同第 1 篇:CrewAI v1.15.41,2026 年 11 月。


1、工具体系三层鸟瞰

CrewAI 的工具体系是个三层结构,塔基是一个抽象基类。所有工具——不管来自哪个渠道——最终都是 BaseTool 的实例或等价物,都要回答同样三个问题:叫什么(name)、干什么(description)、怎么干(_run 方法)。先立住一句总纲:工具的 name 与 description 是写给 LLM 看的提示词,_run 才是写给人看的实现。三层结构画出来:

flowchart TD A[BaseTool 基类] --> B[内置工具包] A --> C[自定义工具] A --> D[LangChain 工具] B --> E[tools 参数列表] C --> E D --> E E --> F[模型按描述选择] F --> G[_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 篇见。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415