CrewAI Crew 项目模板深度解析从 crewai create 生成到 crewai run 的完整实战指南【免费下载链接】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在 CrewAI 生态中绝大多数多智能体项目的起点都来自 CLI 提供的 crew 项目模板——你执行一次crewai create就会得到一套开箱即用的工程骨架而本文解析的正是这个模板内置的项目说明文档 templates/crew/README.md。读懂这份 README就能掌握一个新 Crew 项目的完整生命周期如何安装依赖、如何配置.env、如何修改agents.yaml/tasks.yaml/crew.py/main.py四个核心定制点以及如何用一条crewai run命令跑出第一份report.md。本文在此基础上进一步深入到模板渲染机制与 CLI 命令的实现源码帮助你把模板从能用用到知其所以然。模板从哪里来crewai create背后的模板渲染机制templates/crew/目录下的所有文件都是带占位符的 Jinja 风格模板其中 README 里出现的{{crew_name}}、{{folder_name}}、{{name}}会在创建项目时被替换为你实际选择的名称。真正的替换逻辑位于 create_crew.pycreate_folder_structure()负责对项目名做合法性校验自动把空格、连字符转为下划线并转小写作为文件夹名拒绝纯数字开头、Python 保留关键字如class、True并且通过get_reserved_script_names()读取模板 pyproject.toml 中的[project.scripts]段禁止与run_crew、train、replay、test、run_with_trigger等已注册脚本名冲突见 create_crew.py#L25-L44create_crew()中的copy_template_files()把模板逐个复制到目标目录模板文件清单为根级的.gitignore、pyproject.toml、README.md、knowledge/user_preference.txt源码级的__init__.py、main.py、crew.py以及tools/custom_tool.py、tools/__init__.py和config/agents.yaml、config/tasks.yaml见 create_crew.py#L163-L203若目标文件夹已存在非 DMN 模式下会交互询问是否覆盖创建成功后还会调用initialize_if_git_available()尝试初始化 Git 仓库见 create_crew.py#L324-L332。因此你生成的项目里看到的 README就是本文讨论的这份模板渲染后的成品。下面以模板原始形态为准逐节展开。项目骨架模板目录对应的运行时结构模板目录与生成后的项目结构一一对应生成后的典型布局如下your_project/ ├── pyproject.toml ├── README.md # 由本模板渲染 ├── .gitignore ├── AGENTS.md ├── knowledge/ │ └── user_preference.txt # 用户偏好知识可被 Crew 知识系统引用 ├── src/ │ └── your_project/ │ ├── __init__.py │ ├── crew.py # Crew 装配逻辑 │ ├── main.py # 入口函数run/train/replay/test 等 │ ├── config/ │ │ ├── agents.yaml # Agent 定义 │ │ └── tasks.yaml # Task 定义 │ └── tools/ │ ├── __init__.py │ └── custom_tool.py # 自定义工具示例 └── tests/各模板文件在仓库中的位置crew.py、main.py、config/agents.yaml、config/tasks.yaml、tools/custom_tool.py、knowledge/user_preference.txt。knowledge/user_preference.txt内置了一段示例用户画像User name is John Doe. User is an AI Engineer...用于演示 CrewAI 的知识Knowledge能力可按需替换为你的真实业务偏好文本。环境要求与依赖安装模板 README 给出的安装约束非常明确且与模板 pyproject.toml 中的声明完全一致Python 版本3.10,3.14模板 pyproject 的requires-python 3.10,3.14依赖声明为{{crewai_tools_dependency}}渲染后即 crewAI 及其工具包包管理器项目采用 UV 风格的项目文件做依赖管理与执行README 推荐的安装步骤是# 若尚未安装 uv pip install uv进入项目目录后README 提供了一个可选的 CLI 方式用于锁定依赖并安装crewai install这条命令由 CLI 主入口 cli.py 中的install命令处理其内部委托给install_crew()并透传额外命令行参数。此外模板 pyproject 的[tool.crewai]段声明了type crew这是 CLI 识别当前目录是一个 crew 类型项目、从而让crewai run/crewai install等命令按 crew 语义解析的关键标记。定制点一在.env中配置 API Key模板 README 的第一定制要求是把你的OPENAI_API_KEY写入.env文件。这不是手工操作的硬性要求——create_crew()在创建阶段就会交互式地引导你选择模型供应商并收集 API Key然后通过write_env_file()直接生成.env见 create_crew.py#L266-L288。如果你选择跳过或之后更换供应商再手动编辑项目根目录的.env即可。定制点二agents.yaml定义 Agent模板自带的 agents.yaml 定义了协作链路中的两个角色researcher: role: {topic} Senior Data Researcher goal: Uncover cutting-edge developments in {topic} backstory: Youre a seasoned researcher with a knack for uncovering the latest developments in {topic}. Known for your ability to find the most relevant information and present it in a clear and concise manner. reporting_analyst: role: {topic} Reporting Analyst goal: Create detailed reports based on {topic} data analysis and research findings backstory: Youre a meticulous analyst with a keen eye for detail. Youre known for your ability to turn complex data into clear and concise reports, making it easy for others to understand and act on the information you provide.三个要点值得注意YAML 顶层 keyresearcher、reporting_analyst就是身份标识crew.py中通过self.agents_config[researcher]以字符串引用它两处必须保持一致role/goal/backstory字段中的{topic}是运行时插值占位符来自kickoff(inputs...)传入的字典而非 YAML 语法每个 Agent 至少需要这三个字段也可按需追加tools、llm、allow_delegation等参数。定制点三tasks.yaml定义任务模板自带的 tasks.yaml 定义了与两个 Agent 一一对应的任务research_task: description: Conduct a thorough research about {topic} Make sure you find any interesting and relevant information given the current year is {current_year}. expected_output: A list with 10 bullet points of the most relevant information about {topic} agent: researcher reporting_task: description: Review the context you got and expand each topic into a full section for a report. Make sure the report is detailed and contains any and all relevant information. expected_output: A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without agent: reporting_analyst这里description描述任务内容可含{topic}、{current_year}插值expected_output约束产出形态agent字段把任务指派给agents.yaml中的同名 Agent。注意expected_output中 without 的写法——这是模板刻意要求产出纯 Markdown 正文因为结果要直接落盘为可读文件。定制点四crew.py装配 Agent 与 Task模板 crew.py 采用CrewBase装饰器模式是整个模板中源码含量最高的文件CrewBase class {{crew_name}}(): {{crew_name}} crew agents: list[BaseAgent] tasks: list[Task] agent def researcher(self) - Agent: return Agent( configself.agents_config[researcher], verboseTrue ) task def research_task(self) - Task: return Task( configself.tasks_config[research_task], ) task def reporting_task(self) - Task: return Task( configself.tasks_config[reporting_task], output_filereport.md ) crew def crew(self) - Crew: Creates the {{crew_name}} crew return Crew( agentsself.agents, tasksself.tasks, processProcess.sequential, verboseTrue, )从源码结构看CrewBase定义在 crew_base.py它是一个把CrewBaseMeta元类套到被装饰类上的类装饰器lib/crewai/src/crewai/project/crew_base.py中的CrewBase(metaclass_CrewBaseType)与CrewBaseMeta.__new__。元类会在类创建时注入agents_config/tasks_config两个属性自动解析类所在目录下的config/agents.yaml与config/tasks.yaml——这就是为什么模板代码里可以直接写self.agents_config[researcher]而无需手动yaml.safe_load。agent、task、crew三个装饰器把方法注册进收集列表被装饰的方法返回值会分别汇入self.agents、self.tasks最终由crew方法组装为Crew实例。模板默认使用Process.sequential即任务按tasks.yaml声明顺序串行执行如改为Process.hierarchical则需为 Crew 指定manager_llm。output_filereport.md是 README 承诺的运行后生成 report.md的直接来源。README 同时提示你可以在此文件添加自有逻辑、工具与特定参数例如把verboseTrue关掉、给 Agent 传入tools[MyCustomTool()]。定制点五main.py提供多种运行入口模板 main.py 提供了五个入口函数每个都通过inputs字典向 YAML 中的占位符注入运行时变量def run(): Run the crew. inputs { topic: AI LLMs, current_year: str(datetime.now().year) } try: {{crew_name}}().crew().kickoff(inputsinputs) except Exception as e: raise Exception(fAn error occurred while running the crew: {e})入口函数行为参数来源run()直接kickoff(inputsinputs)执行整队topic、current_yeartrain()crew().train(n_iterations..., filename..., inputs...)训练 Agentsys.argv[1]迭代次数、sys.argv[2]训练文件replay()crew().replay(task_id...)从指定任务重放sys.argv[1]任务 IDtest()crew().test(n_iterations..., eval_llm..., inputs...)评估 Crewsys.argv[1]迭代次数、sys.argv[2]评估 LLMrun_with_trigger()把 JSON 触发包载入crewai_trigger_payload后kickoff供外部系统如 Webhook/DMN 触发器调用sys.argv[1]JSON 字符串这些函数通过模板 pyproject.toml 的[project.scripts]注册为可执行入口点[project.scripts] {{folder_name}} {{folder_name}}.main:run run_crew {{folder_name}}.main:run train {{folder_name}}.main:train replay {{folder_name}}.main:replay test {{folder_name}}.main:test run_with_trigger {{folder_name}}.main:run_with_trigger也就是说crewai install把项目装进环境后run_crew、train、replay、test等命令都能直接在终端调用。需要强调的一致性约束[project.scripts]中的脚本名是全局保留的这正是create_crew.py中get_reserved_script_names()校验项目名不能与其重名的原因。自定义工具tools/custom_tool.py模板附带了一个最小可运行的自定义工具示例 custom_tool.pyfrom crewai.tools import BaseTool from typing import Type from pydantic import BaseModel, Field class MyCustomToolInput(BaseModel): Input schema for MyCustomTool. argument: str Field(..., descriptionDescription of the argument.) class MyCustomTool(BaseTool): name: str Name of my tool description: str ( Clear description for what this tool is useful for, your agent will need this information to use it. ) args_schema: Type[BaseModel] MyCustomToolInput def _run(self, argument: str) - str: return this is an example of a tool output, ignore it and move along.它演示了 CrewAI 工具三要素namedescriptionAgent 依靠描述决定何时调用工具、Pydanticargs_schema约束入参结构、_run()实现。把该类导入crew.py并在Agent(...)中传tools[MyCustomTool()]即可挂接到任意 Agent。运行项目crewai run与report.md产出README 给出的标准运行方式是在项目根目录执行$ crewai run该命令由 cli.py 中的run命令实现支持--trained-agents、--definition、--inputs等选项在不传参数时它会依据[tool.crewai]配置定位 crew 项目并触发执行。从源码结构看模板未修改时的执行链路为crewai run→ 加载 crew.py 中的{{crew_name}}类 → 元类注入的agents_config/tasks_config解析两份 YAML →kickoff(inputs{topic: AI LLMs, current_year: 当前年份})→ 按Process.sequential先由researcher完成 10 条要点研究再由reporting_analyst扩写成完整报告 →output_file把最终结果写入项目根目录的report.md。README 对此的原文承诺是未修改的模板跑一次就会在根目录产出一份针对 LLM 调研的report.md。这也是验证整个配置链路YAML 插值、Agent 指派、任务串行、输出落盘是否打通的最快冒烟测试。模板 README 的结构定位这份模板 README 本身是templates/crew/中随README.md一并被copy_template()渲染复制的文件见 create_crew.py#L295-L309其中{{crew_name}}/{{name}}会被替换为实际项目名。它刻意保持极简——安装、定制、运行三步——把深入的 API 说明留给crewai官方文档站与仓库内的docs/目录。如果你在本仓库中查找更系统的概念解释可参考docs/下的 crew 相关文档如 concepts 目录下的 agents、tasks、processes 等章节它们与本文模板中的四个定制点一一对应。小结templates/crew/README.md看似只是一份简短的项目说明实则是 CrewAI crew 项目模板的操作手册覆盖了一个多智能体项目从环境准备到首次产出的全部关键步骤环境Python3.10,3.14pip install uv后用crewai install锁依赖并安装配置.env写入 API Keyconfig/agents.yaml与config/tasks.yaml定义角色与任务{topic}等占位符在kickoff(inputs...)时注入装配crew.py用CrewBaseagent/task/crew把 YAML 配置装配为CrewProcess.sequential决定执行拓扑运行crewai run一条命令完成执行并产出report.mdmain.py额外提供train/replay/test/run_with_trigger四类扩展入口扩展tools/custom_tool.py展示了基于 Pydanticargs_schema的自定义工具写法。掌握这份模板后你就可以把任何研究—分析—产出型需求快速实例化为一个可运行、可训练、可重放的 Crew 项目。【免费下载链接】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），仅供参考