CrewAI 工具集成与自定义工具概念速查CrewAI 工具是 Agent 可调用的函数式能力单元。每个工具封装一个原子操作——搜索、计算、读写文件——Agent 在执的 Task 中自主决定何时调用。框架内置两类创建接口tool装饰器快捷方式crewai0.30.0fromcrewai.toolsimporttooltool(网页抓取器)deffetch_page(url:str)-str:抓取指定 URL 的文本内容# 工具逻辑return页面内容BaseTool子类化完整控制crewai0.30.0fromtypingimportTypefromcrewai.toolsimportBaseToolfrompydanticimportBaseModel,FieldclassSearchInput(BaseModel):query:strField(...,description搜索关键词)classSearchTool(BaseTool):name:str搜索工具description:str执行搜索引擎查询返回结构化结果args_schema:Type[BaseModel]SearchInputdef_run(self,query:str)-str:# 调用搜索 API 并返回return搜索结果装饰器适用于无状态、单函数工具BaseTool适用于需输入校验Pydantic schema、状态管理或混合同步/异步逻辑的场景。工具分类CrewAI 预置工具按职能大致分四类类别代表工具用途搜索检索SerperDevTool,WebsiteSearchTool,FirecrawlSearchTool网页搜索与内容抓取代码执行CodeInterpreterTool运行 Python 代码文件操作FileReadTool,DirectoryReadTool,CSVSearchTool,PDFSearchTool读/搜本地文件RAG 检索RagTool,PGSearchTool,GithubSearchTool对文档/数据库做语义搜索是否是允许缓存不缓存否Agent 收到 Task需要外部能力?选择工具序列化参数LLM 生成 JSON 输入执行 _run / _arun缓存命中?调用真实 API返回缓存结果检查 cache_function写入缓存跳过返回结果给 AgentAgent 继续 Task底层原理工具协定与执行流程CrewAI 在底层将每个工具包装为一个CrewStructuredTool内部维护name、description、args_schema、_run与可选的_arun。当 LLM 在 Agent 的 System Prompt 中看到工具描述后自主决策调用并输出 JSON 格式参数。框架反序列化该 JSON 为 Pydantic 模型传入_run执行。关键约束description是 LLM 选工具的唯一依据。描述越精确Agent 选错工具的概率越低。字段名与 LLM 能理解的自然语言一致。缓存机制缓存发生在工具层key 由工具名 参数 JSON 组成# crewai0.30.0fromcrewai.toolsimporttooltool(乘法器)defmultiply(a:int,b:int)-int:将两个数相乘returna*bdefcache_only_even(args,result):returnresult%20multiply.cache_functioncache_only_evencache_function签名是(args: dict, result: Any) - bool返回True则写入缓存。默认所有工具开启缓存若某工具结果不宜复用如余额查询通过cache_function返回False关闭。缓存存储在Crew级别的Cache实例中跨 Task 共享——同一 Crew 内多次相同参数调用只产生一次真实执行。错误处理_run内的任何异常会被框架捕获并包装为工具调用失败消息返回给 LLM。Agent 可据此尝试修正参数后重试或放弃该工具改用其他手段。# crewai0.30.0fromcrewai.toolsimportBaseToolclassSafeSearchTool(BaseTool):name:str安全搜索description:str执行搜索出错时返回友好提示def_run(self,query:str)-str:try:# 可能抛异常的 API 调用returnself.api.search(query)exceptConnectionError:return[搜索服务不可用使用缓存摘要]# LLM 看到后继续工作exceptRateLimitError:return[请求过快等待后重试]工具应返回字符串而非抛出异常。框架虽会兜底捕获但自定义错误消息让 LLM 有上下文做补救决策而裸异常则只让 Agent 知道失败了。LangChain 工具互操作所有langchain工具均可通过包装接入 CrewAI。crewai0.30.0不直接提供from_langchain工厂而是通过BaseTool子类化封装 LangChain 原生工具实例# crewai0.30.0, langchain-community0.3.0fromcrewai.toolsimportBaseToolfrompydanticimportFieldfromlangchain_community.utilitiesimportSerpAPIWrapperclassLangChainSearchTool(BaseTool):name:strWeb Searchdescription:str通过 Google Search 获取实时信息search:SerpAPIWrapperField(default_factorySerpAPIWrapper)def_run(self,query:str)-str:returnself.search.run(query)这是推荐的集成方式——不引入多余依赖在 CrewAI 的 Pydantic 序列化体系内工作。若需批量包装已有 LangChain 工具列表可自行实现一个循环工厂方法。架构设计原则单一职责 描述即契约一个工具做一件事且用description精准告诉 LLM 这件事是什么。不要写全能工具一个工具既能搜网页又能写文件那会迫使 LLM 靠参数猜测行为增加决策成本。反例description: 通用数据处理工具正例description: 当需要根据关键词搜索最新技术新闻时使用该工具。返回标题、来源和发布日期。缓存策略与结果幂等缓存提升效率但引入因果风险。设计原则读操作搜索、查 DB—— 默认缓存cache_function细化条件写操作发邮件、写文件——cache_function返回False实时数据余额、汇率——cache_function返回False或使用短 TTL错误信息的语义价值工具返回的错误字符串要带有状态提示而非只传递原因。LLM 不理解 HTTP 状态码但它能理解 “[API 扣费余额不足]”。错误消息的原则让 Agent 知道发生了什么 下一步能做什么。工具粒度与 Task 层级匹配Task 是一篇文章时对应工具是搜索“写作”。不要提供搜索总结翻译格式化的大统一工具——那让 LLM 不得不一次性做完所有事失去中间推理步骤。粗粒度工具适合简单子 Task细粒度工具交给负责推理的 Agent。以上原则贯穿 CrewAI 工具系统全链路从tool装饰器的快速定义到BaseTool的完整控制再到缓存、错误、LangChain 互操作的工程落地。按接口选方式、按场景调缓存、按职责拆工具即可获得干净高效的 Agent 工具层。