CrewAI Crew 项目模板深度解析：从 crewai create 生成到 crewai run 的完整实战指南-育师

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.py：

create_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-L44）；
create_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: > You're 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: > You're a meticulous analyst with a keen eye for detail. You're 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 顶层 key（researcher、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( config=self.agents_config['researcher'], verbose=True ) @task def research_task(self) -> Task: return Task( config=self.tasks_config['research_task'], ) @task def reporting_task(self) -> Task: return Task( config=self.tasks_config['reporting_task'], output_file='report.md' ) @crew def crew(self) -> Crew: """Creates the {{crew_name}} crew""" return Crew( agents=self.agents, tasks=self.tasks, process=Process.sequential, verbose=True, )

从源码结构看，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_file='report.md'是 README 承诺的"运行后生成 report.md"的直接来源。README 同时提示你可以在此文件添加自有逻辑、工具与特定参数，例如把verbose=True关掉、给 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(inputs=inputs) except Exception as e: raise Exception(f"An error occurred while running the crew: {e}")

入口函数	行为	参数来源
`run()`	直接`kickoff(inputs=inputs)`执行整队	`topic`、`current_year`
`train()`	`crew().train(n_iterations=..., filename=..., inputs=...)`训练 Agent	`sys.argv[1]`迭代次数、`sys.argv[2]`训练文件
`replay()`	`crew().replay(task_id=...)`从指定任务重放	`sys.argv[1]`任务 ID
`test()`	`crew().test(n_iterations=..., eval_llm=..., inputs=...)`评估 Crew	`sys.argv[1]`迭代次数、`sys.argv[2]`评估 LLM
`run_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.py：

from crewai.tools import BaseTool from typing import Type from pydantic import BaseModel, Field class MyCustomToolInput(BaseModel): """Input schema for MyCustomTool.""" argument: str = Field(..., description="Description 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 工具三要素：name+description（Agent 依靠描述决定何时调用工具）、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 项目模板的"操作手册"，覆盖了一个多智能体项目从环境准备到首次产出的全部关键步骤：

环境：Python>=3.10,<3.14，pip install uv后用crewai install锁依赖并安装；
配置：.env写入 API Key，config/agents.yaml与config/tasks.yaml定义角色与任务，{topic}等占位符在kickoff(inputs=...)时注入；
装配：crew.py用@CrewBase+@agent/@task/@crew把 YAML 配置装配为Crew，Process.sequential决定执行拓扑；
运行：crewai run一条命令完成执行并产出report.md，main.py额外提供train/replay/test/run_with_trigger四类扩展入口；
扩展：tools/custom_tool.py展示了基于 Pydanticargs_schema的自定义工具写法。

掌握这份模板后，你就可以把任何"研究—分析—产出"型需求快速实例化为一个可运行、可训练、可重放的 Crew 项目。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CrewAI Crew 项目模板深度解析：从 crewai create 生成到 crewai run 的完整实战指南