crewAI CLI 与项目结构：从原型到生产的工程化规范

crewAI CLI 与项目结构从原型到生产的工程化规范本文基于 crewAI v1.11.0系统介绍 crewAI 项目的标准工程结构、CLI 工具链和生产环境配置规范。一、原型与生产的鸿沟很多 crewAI 项目都死在从原型到生产的过渡阶段。原型阶段的代码通常是这样的# prototype.py别笑你写过fromcrewaiimportAgent,Task,Crew agentAgent(role研究员,goal...,backstory...)taskTask(description研究crewAI,expected_output...,agentagent)crewCrew(agents[agent],tasks[task])resultcrew.kickoff()print(result.raw)这段代码能跑但它有一堆生产问题Agent/Task 配置硬编码无法多环境切换没有依赖管理换个机器就可能跑不起来没有错误处理一报错整个程序崩溃没有日志出问题不知道哪里出了问题API Key 散落在代码各处虽然我们假设你不会这么做crewAI 提供了一套完整的工程化工具链来解决这些问题。二、使用 UV 安装 crewAIcrewAI 官方推荐使用uv作为包管理工具相比 pip/Poetry速度快 10-100 倍# 安装 uv如果还没有curl-LsSfhttps://astral.sh/uv/install.sh|sh# macOS/Linux# Windows:# powershell -c irm https://astral.sh/uv/install.ps1 | iex# 安装 crewAI带工具集uv pipinstallcrewai[tools]# 验证安装crewai--version# crewAI, version 1.11.0三、crewAI CLI快速创建标准项目3.1 创建新项目crewai create crew my_research_crew执行后crewAI 会在当前目录创建标准项目结构my_research_crew/ ├── pyproject.toml ─ 项目元数据和依赖配置 ├── .env ─ 环境变量不要提交到 Git ├── .gitignore ─ Git 忽略文件 ├── README.md ─ 项目说明 └── src/ └── my_research_crew/ ├── __init__.py ├── main.py ─ 程序入口 ├── crew.py ─ Crew 定义核心文件 ├── tools/ │ ├── __init__.py │ └── custom_tool.py ─ 自定义工具 └── config/ ├── agents.yaml ─ Agent 配置推荐在此定义 Agent └── tasks.yaml ─ Task 配置推荐在此定义 Task3.2 标准文件解析pyproject.toml项目配置文件[tool.poetry] name my-research-crew version 0.1.0 description 基于 crewAI 的技术研究自动化系统 authors [Your Name youexample.com] [tool.poetry.dependencies] python 3.10,3.13 crewai {extras [tools], version 1.11.0,2.0.0} [tool.poetry.scripts] my_research_crew my_research_crew.main:run # crewai run 的入口 [build-system] requires [poetry-core] build-backend poetry.core.masonry.apimain.py程序入口#!/usr/bin/env python# src/my_research_crew/main.pyimportsysfrommy_research_crew.crewimportMyResearchCrewdefrun():标准入口函数供 crewai run 调用inputs{topic:AI在企业知识管理中的应用,current_year:2026}try:resultMyResearchCrew().crew().kickoff(inputsinputs)print(\n*60)print(执行结果)print(*60)print(result.raw)exceptExceptionase:print(f执行失败{e},filesys.stderr)sys.exit(1)deftrain():用于训练/微调场景高级用法inputs{topic:AI研究,n_iterations:5,filename:training_data.pkl}MyResearchCrew().crew().train(**inputs)defreplay():重放指定任务调试用task_idsys.argv[1]iflen(sys.argv)1elseNoneifnottask_id:print(使用方式crewai replay task_id)sys.exit(1)MyResearchCrew().crew().replay(task_idtask_id)if__name____main__:run()crew.pyCrew 核心定义# src/my_research_crew/crew.pyfromcrewaiimportAgent,Crew,Process,Taskfromcrewai.projectimportCrewBase,agent,crew,taskfromcrewai_toolsimportSerperDevTool,ScrapeWebsiteToolCrewBaseclassMyResearchCrew:技术研究 Crew 定义agents_configconfig/agents.yamltasks_configconfig/tasks.yaml# ── 工具初始化 ──────────────────────────────────────def__init__(self):self.search_toolSerperDevTool()self.scrape_toolScrapeWebsiteTool()# ── Agent 定义 ──────────────────────────────────────agentdefresearcher(self)-Agent:returnAgent(configself.agents_config[researcher],tools[self.search_tool,self.scrape_tool],verboseTrue)agentdefanalyst(self)-Agent:returnAgent(configself.agents_config[analyst],verboseTrue)agentdefwriter(self)-Agent:returnAgent(configself.agents_config[writer],verboseTrue)# ── Task 定义 ───────────────────────────────────────taskdefresearch_task(self)-Task:returnTask(configself.tasks_config[research_task])taskdefanalysis_task(self)-Task:returnTask(configself.tasks_config[analysis_task])taskdefwriting_task(self)-Task:returnTask(configself.tasks_config[writing_task],output_filereport.md# 自动将输出保存到文件)# ── Crew 组装 ───────────────────────────────────────crewdefcrew(self)-Crew:returnCrew(agentsself.agents,# 自动收集所有 agent 装饰的方法tasksself.tasks,# 自动收集所有 task 装饰的方法processProcess.sequential,verboseTrue)四、YAML 配置生产环境的标准范式4.1 agents.yaml# src/my_research_crew/config/agents.yamlresearcher:role:高级技术研究员goal:对 {topic} 进行深度技术研究 识别 {current_year} 年最具价值的技术趋势和实践案例backstory:你是一位资深技术研究员有着10年的技术调研经验。 你擅长从海量信息中提炼关键洞见 你的调研报告以严谨、深度和实用性著称。 你永远不会引用未经验证的信息。memory:trueverbose:truemax_iter:15analyst:role:技术战略分析师goal:基于研究成果从商业价值和实施可行性角度进行深度分析backstory:你在麦肯锡数字化转型团队工作了8年 帮助超过50家企业制定AI战略。 你的分析总是聚焦商业价值而不是技术本身。memory:truewriter:role:技术写作专家goal:将复杂的技术分析转化为高管和技术团队都能看懂的报告backstory:你是前《哈佛商业评论》技术专栏作家 擅长用简洁的语言解释复杂的技术概念。 你的文章总是有清晰的结构和令人信服的论点。4.2 tasks.yaml# src/my_research_crew/config/tasks.yamlresearch_task:description:对 {topic} 进行全面的技术研究。研究维度 1.{current_year}年的主要技术突破 2. 领先企业的实践案例至少5个 3. 主要的开源项目和工具 4. 技术成熟度评估 5. 主要挑战和限制expected_output:结构化的研究报告Markdown格式包含 - 技术概述200-300字 - 关键技术突破列表每项含简短评述 - 企业案例表格公司名、行业、应用场景、规模 - 主要开源项目含GitHub链接 - 技术挑战总结agent:researcheranalysis_task:description:基于研究报告从商业价值角度进行深度分析 1. 市场规模和增长潜力附数据来源 2. 技术壁垒评估0-10分并说明理由 3. 主要应用场景的ROI分析 4. 实施路径建议expected_output:投资价值分析报告Markdown格式包含 - 市场机会评估 - 技术壁垒分析表格形式 - 典型场景ROI估算 - 推荐的实施优先级agent:analystcontext:-research_taskwriting_task:description:将研究报告和分析报告整合为面向技术决策者的综合报告。 报告应该既有深度技术人员看完能落地又有高度高管看完能决策。 字数2000-3000字。expected_output:完整的综合报告Markdown格式结构 # 执行摘要300字以内 ## 技术背景 ## 关键发现 ## 商业价值分析 ## 实施建议 ## 结论agent:writercontext:-research_task-analysis_task五、环境管理与多环境配置5.1 .env 文件配置# .env本地开发OPENAI_API_KEYsk-...SERPER_API_KEY...ANTHROPIC_API_KEYsk-ant-...# 多环境配置ENVIRONMENTdevelopment# 可选指定模型DEFAULT_LLM_MODELgpt-4oMANAGER_LLM_MODELgpt-4o# 可选日志级别LOG_LEVELINFO5.2 多环境切换# src/my_research_crew/config.pyimportosfromdotenvimportload_dotenv# 根据 ENVIRONMENT 加载不同的配置文件envos.getenv(ENVIRONMENT,development)load_dotenv(f.env.{env},overrideTrue)load_dotenv(.env)# 通用配置# 类型安全的配置类frompydanticimportBaseSettingsclassSettings(BaseSettings):openai_api_key:strserper_api_key:strdefault_llm_model:strgpt-4olog_level:strINFOenvironment:strdevelopmentclassConfig:env_file.envsettingsSettings()六、CLI 命令速查# 创建新项目crewai create crew my_crew# 运行 Crewcrewai run# 在特定目录运行cdmy_crewcrewai run# 查看帮助crewai--help# 安装依赖等同于 poetry installcrewaiinstall# 测试/重放特定任务调试用crewai replaytask_id# 查看版本crewai--version七、类型安全Pydantic v2 在 crewAI 中的应用crewAI 内部大量使用 Pydantic v2 进行数据校验开发者也应该在自定义部分保持类型安全frompydanticimportBaseModel,Field,validatorfromtypingimportList,OptionalfromenumimportEnumclassResearchDepth(str,Enum):QUICKquick# 快速调研1-2小时STANDARDstandard# 标准调研半天DEEPdeep# 深度调研1-2天classResearchRequest(BaseModel):topic:strField(min_length5,max_length200)depth:ResearchDepthResearchDepth.STANDARD focus_areas:List[str]Field(default_factorylist,max_items5)exclude_sources:List[str]Field(default_factorylist)output_language:strField(defaultzh,pattern^(zh|en)$)validator(topic)deftopic_must_be_specific(cls,v):ifany(wordinv.lower()forwordin[all,everything,general]):raiseValueError(主题过于宽泛请指定具体方向)returnv# 在 main.py 中使用类型校验defrun():try:# 验证输入参数requestResearchRequest(topiccrewAI多智能体框架在企业知识管理中的应用,depthResearchDepth.STANDARD,focus_areas[技术实现,成本效益],output_languagezh)inputsrequest.model_dump()resultMyResearchCrew().crew().kickoff(inputsinputs)exceptValidationErrorase:print(f输入参数无效{e},filesys.stderr)sys.exit(1)八、小结工程化是 crewAI 项目从能跑到能用的关键跨越项目结构标准化crewai create crew一键生成标准目录避免每个人一套结构的混乱YAML 配置优先Agent/Task 的定义从代码里分离出来便于维护和非技术人员参与环境变量管理密钥永远不进代码库多环境配置一套体系类型安全Pydantic v2 保护关键数据的合法性这些工程实践不是过度设计而是让项目在生产环境中活得更久的基本保障。系列导航上一篇crewAI 外部触发器与 API 集成Gmail/Slack/Salesforce 事件驱动下一篇crewAI 可观测性体系Langfuse/Phoenix 集成与执行链路追踪基于 crewAI v1.11.0 官方文档撰写于 2026 年 3 月