CrewAI DirectoryReadTool 详解让 Agent 递归盘点目录内容的实战指南【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAIDirectoryReadTool 是 CrewAI 工具库crewai_tools内置的目录枚举工具用于递归遍历并完整列出指定目录及其所有子目录中的文件清单。在需要 Agent 先了解某个目录里“有什么”再决定下一步该读哪些文件、如何组织输出的多步骤任务中它是理想的前置探测组件。读完本文你将掌握 DirectoryReadTool 的安装、两种使用模式、参数语义、底层递归实现与输出格式并理解其路径安全校验机制与在 Agent/Crew 中的正确接法。工具定位与适用场景DirectoryReadTool 的官方定义非常朴素高效地全面枚举目录内容。它会递归深入目标目录把包括子目录在内的所有文件逐一列出常被用于两类任务目录结构清点Agent 在开始处理前先摸清某个资料目录下有多少文件、分布在哪一层组织结构校验验证一个目录的文件摆放是否符合预期例如检查某个导出目录是否完整。从实现角度看directory_read_tool.py 中工具对外暴露的名称是List files in directory描述为“A tool that can be used to recursively list a directorys content.”一个可递归列出目录内容的工具。它只负责“列出清单”不读取文件正文——若要读取单个文件内容可使用同一工具包内的 FileReadTool若需要在目录内容之上做语义检索则可组合使用 DirectorySearchTool。三者构成“先盘点 → 再精读 / 再检索”的递进工具链。安装与导入DirectoryReadTool 随crewai_tools包一起分发直接通过 crewAI 的 tools 扩展安装即可pip install crewai[tools]安装完成后即可从包顶层导入from crewai_tools import DirectoryReadTool该符号在 crewai_tools 包的顶层init.py约第 72 行导入、第 262 行导出中与其余全部官方工具一同被公开因此无需记忆深层导入路径。基础用法官方 README 给出的最小示例展示了它最常用的“固定目录”模式from crewai_tools import DirectoryReadTool # 用目标目录初始化工具 tool DirectoryReadTool(directory/path/to/your/directory) # 列出该目录内容 directory_contents tool.run() print(directory_contents)当在构造时传入directory参数后工具后续调用不再需要任何参数直接执行run()即可拿到整个目录树的文件清单。作为 Agent 工具的典型接法在实际 Crew 中DirectoryReadTool 通常被挂载到 Agent 的tools列表中让 LLM 按需调用from crewai import Agent, Crew, Task from crewai_tools import DirectoryReadTool directory_tool DirectoryReadTool(directory./research_notes) researcher Agent( role资料盘点专员, goal先摸清 research_notes 目录下有哪些素材文件, backstory擅长在动手前先盘点工作目录中的可用资源。, tools[directory_tool], ) task Task(description列出 research_notes 中的全部文件并按子目录归纳, agentresearcher) Crew(agents[researcher], tasks[task]).kickoff()挂载后工具的名称、参数 schema 与描述会通过formatted_description合成一段面向 LLM 的工具说明参见 base_tool.pyAgent 据此知道何时该调用它来获取目录文件清单。两种运行模式与参数语义DirectoryReadTool 的灵活性体现在它支持“固定目录”与“动态目录”两种用法这两种模式由构造函数与 Pydantic schema 的组合切换实现理解 directory_read_tool.py 就能看清全貌模式触发方式运行时参数说明固定目录模式DirectoryReadTool(directory/some/path)无需参数工具描述会被改写为A tool that can be used to list /some/paths content.args schema 切换为空的FixedDirectoryReadToolSchemaLLM 无法再传路径调用更安全动态目录模式DirectoryReadTool()不传 directory必填directory字符串使用完整DirectoryReadToolSchema由 Agent 在每次调用时自行决定盘点哪个目录参数 schema工具类上默认绑定的输入 schema 为DirectoryReadToolSchemaclass DirectoryReadToolSchema(FixedDirectoryReadToolSchema): directory: str Field(..., descriptionMandatory directory to list content)directory唯一的核心参数必填语义为“要列出内容的目录”接受绝对路径与相对路径两种写法注意 Pydantic 的Field(..., ...)表示该字段无默认值、必须提供这与 tool.specs.json约第 8414-8427 行中自动生成的工具规格一致run_params_schema中directory被标记为required类型为string。如果构造时不传directory就直接调用运行期会抛出ValueError(Directory must be provided.)源码第 40-42 行。底层实现递归遍历与输出格式化DirectoryReadTool 并不借助任何外部服务它完全基于 Python 标准库os.walk实现递归枚举。_run 方法的核心逻辑 可拆解为四步def _run(self, **kwargs: Any) - Any: directory: str | None kwargs.get(directory, self.directory) if directory is None: raise ValueError(Directory must be provided.) directory validate_directory_path(directory) if directory[-1] /: directory directory[:-1] files_list [ f{directory}/{(os.path.join(root, filename).replace(directory, ).lstrip(os.path.sep))} for root, dirs, files in os.walk(directory) for filename in files ] files \n- .join(files_list) return fFile paths: \n-{files}参数解析从调用方的 kwargs 中取directory取不到则回退到构造时保存的self.directory动态模式的入口就在此路径校验调用validate_directory_path做安全性检查详见下一节尾部规整若目录字符串以/结尾则先去掉保证后续拼接格式统一递归枚举用os.walk(directory)自顶向下遍历对每个(root, dirs, files)元组中的每个filename把它的完整路径修剪成“相对 root 起点、去掉directory前缀”的形式再拼回{directory}/...。例如对目录/data/docs若存在文件/data/docs/a.md与/data/docs/sub/b.md最终返回值类似File paths: -/data/docs/a.md - /data/docs/sub/b.md返回内容以File paths:为标题每个文件占一行并以-起头是便于 LLM 直接阅读的纯文本清单该字符串会作为工具结果回传给 Agent作为其后续推理的上下文。需要留意的是os.walk默认不跟随符号链接指向的目录且枚举顺序遵循文件系统返回顺序并不保证字母序若下游对排序敏感建议先运行工具再自行对结果排序。路径安全校验与沙箱逃逸开关与 FileReadTool 等文件类工具一样DirectoryReadTool 在访问任何路径前都会调用安全模块做目录级路径校验。校验实现位于 safe_path.pyvalidate_directory_path(path, base_dirNone)第 139-158 行先复用validate_file_path的解析逻辑——用os.path.realpath解析软链与..等相对段再检查解析后的绝对路径是否位于允许的根目录base_dir默认取进程当前工作目录之内越界即抛ValueError最后额外用os.path.isdir确认目标确实是一个目录而不是文件。沙箱逃逸开关设置环境变量CREWAI_TOOLS_ALLOW_UNSAFE_PATHStrue可跳过该校验官方不建议在生产使用而CREWAI_TOOLS_FORCE_SAFE_PATHStrue会强制忽略前者防止托管租户自行关闭校验第 75-89 行。这两类行为同样被 test_safe_path.py如对相对路径、非目录路径、../../越界路径的用例所覆盖验证。因此在默认配置下相对路径会被解析并锚定到当前工作目录内相对路径引用base_dir 之外的文件如../../会直接报错指向符号链接外部目录的路径同样会被拒绝。这一设计对“Agent 输入由 LLM 产生”的场景意义重大当使用动态模式把路径决定权交给模型时安全层能有效避免模型触达沙箱之外的敏感目录。与目录搜索、文件读写工具的配合crewai_tools提供了一组围绕本地文件系统的工作工具DirectoryReadTool 是其中的“清单”一环。以 tools 目录 下的实现为例它们的职责边界如下DirectoryReadTool递归枚举目录下的所有文件路径只出清单不读内容FileReadTool读取并返回单个文件的文本内容DirectorySearchTool基于 RAG 对目录内文档做语义检索返回与查询最相关的内容片段FileWriterTool向指定路径写入文件。一个典型的文件分析任务流因此可以是先用DirectoryReadTool得知素材文件全貌 → 用FileReadTool逐个读取候选文件 → 必要时用DirectorySearchTool做跨文件语义检索。三者组合即可覆盖“盘点 → 精读 → 检索”的完整闭环而不必为每个场景单独编写自定义工具。CLI 脚手架与配置化使用DirectoryReadTool 也被 CrewAI 的工程化工具链所识别。在 create_json_crew.py约第 163 行中它以(DirectoryReadTool, List directory contents)的键值对形式被注册进可用工具清单说明在基于 JSON 配置生成 Crew 的流程里开发者可以直接选择它作为 Agent 的官方内置工具之一CLI 侧相关的创建测试可参考 test_create_crew.py。这意味着除了纯 Python 写法你还可以在 JSON 化 Crew 定义中按字符串引用该工具从而把 Agent 的工具装配与业务代码解耦。使用注意事项与建议结合源码与文档给出以下几点实践建议优先固定目录只要业务上目录是确定的就用DirectoryReadTool(directory...)的固定模式——工具描述会带上具体路径运行时不再暴露可变参数既减少 LLM 误传路径的概率也让输出更聚焦。路径尽量用绝对路径或在工作目录内默认安全策略以进程工作目录为锚跨目录访问需要显式构造在允许范围内的路径。不要对超大目录无脑调用os.walk会一次性遍历整棵目录树并把全部文件路径拼成一个字符串返回目录层级极深或文件数量极大时返回体可能很长、占用 Agent 上下文窗口建议先评估目录规模或结合过滤策略使用。输出解析按行处理返回值以File paths:开头、逐行一条文件作为工具结果回传后下游若需程序化处理可对字符串按换行切分后逐条解析。小结DirectoryReadTool 是 CrewAI 本地文件工具链中最轻量也最常用的一环一个参数、两种模式、标准库递归实现配合内建的安全路径校验足以支撑 Agent 在各类任务中的“目录侦察”需求。你可以配合 FileReadTool 与 DirectorySearchTool 延伸出完整的本地文件工作流也可以从 工具源码 与 路径安全模块 出发理解其递归枚举与沙箱约束的每一处细节。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考