crewAI Task 设计与上下文传递输出期待与任务链依赖本文基于 crewAI v1.11.0 官方文档系统拆解 Task 的五大要素、上下文传递机制和结构化输出校验实践。一、Task 是什么工作单元还是数据总线很多人把 crewAI 的 Task 简单理解为给 Agent 的一段指令。这个认知让你只用了 Task 20% 的能力。Task 的真正定位有两个维度第一维工作单元——定义一件事要做什么和做成什么样是驱动 Agent 行动的核心输入。第二维数据总线——Task 的输出不只是最终结果它会通过context机制自动流入下游 Task 的上下文成为整个多智能体协作系统中信息流转的数据通道。理解了这两个维度你才能设计出真正高效的多智能体工作流。二、Task 五要素详解2.1 description驱动推理的任务说明书fromcrewaiimportTask research_taskTask(description 你需要对 {topic} 这个技术方向进行深度研究。 研究维度要求 1. 技术成熟度评估TRL 1-9 标准 2. 主要开源实现GitHub 星数 5000 优先 3. 商业化落地案例至少 3 个 4. 核心技术挑战和未解决的问题 研究时间范围过去 12 个月内的信息为主基础理论部分不限时间。 避免不要引用未经验证的消息源不要做过度乐观的技术预测。 ,...)description 的编写原则具体化任务边界告诉 Agent 做什么不做什么避免领域提供评估标准如技术成熟度 TRL 标准让 Agent 用明确的框架思考注入偏好约束如避免过度乐观的预测直接影响输出质量善用 Jinja2 变量{topic}这类占位符让 Task 模板化、可复用2.2 expected_output定义完成的标准expected_output 是 crewAI Guardrails 机制的基础——Agent 会持续工作直到输出符合这里描述的预期。research_taskTask(description...,expected_output 一份结构化的技术调研报告必须包含以下部分 ## 技术概述200-300字 ## 成熟度评估TRL 等级 判断依据 ## 主要实现方案表格格式含GitHub链接 ## 商业案例3-5个含公司名、应用场景、规模估算 ## 核心挑战bullet list每条给出技术解释 ## 作者结论100字以内给出明确的值得/不值得深入判断 输出格式Markdown。不需要引言和致谢。 ,agentresearcher)关键点expected_output 越具体输出质量越稳定。含糊的写一份报告和具体的包含6个指定章节、字数范围、格式要求的报告最终质量差异显著。2.3 agent执行者的精确指派research_taskTask(description...,expected_output...,agentresearcher# 明确指派给 researcher Agent)在 Sequential 流程中agent 是必填的。在 Hierarchical 流程中Manager Agent 会根据任务内容和 Agent 能力自动分配此时可以省略 agent 参数。2.4 context任务链的数据传递context是 crewAI 中最精妙的设计之一。它建立了 Task 之间的显式依赖关系并自动完成数据传递# Task 1研究research_taskTask(description研究 {topic} 的技术现状,expected_output包含技术要点的调研报告,agentresearcher)# Task 2分析依赖 Task 1 的输出analyze_taskTask(description 基于已有的调研报告从投资价值角度进行深度分析。 重点评估技术壁垒、市场规模、竞争格局。 ,expected_output投资分析报告含明确的投资建议,agentanalyst,context[research_task]# research_task 的输出自动注入此处)# Task 3撰写同时依赖 Task 1 和 Task 2write_taskTask(description将技术调研和投资分析整合为面向高管的简报,expected_output500字以内的执行摘要,agentwriter,context[research_task,analyze_task]# 同时使用两个上游任务的输出)context 的数据流机制research_task.output │ ▼ [自动追加到 analyze_task 的 Prompt 中] 以下是已完成任务的输出请基于此继续工作 [research_task 的输出内容] │ ▼ analyze_task 执行 → analyze_task.output │ ▼ [自动追加到 write_task 的 Prompt 中] 以下是已完成任务的输出 [research_task 输出] [analyze_task 输出]这个机制让信息传递完全声明式——你只需要声明依赖关系crewAI 负责数据流转无需任何手动拼接 Prompt 的代码。2.5 toolsTask 级别的工具覆盖Task 级别的 tools 配置优先级高于Agent 级别的默认工具# Agent 有通用工具集researcherAgent(role研究员,tools[SerperDevTool(),ScrapeWebsiteTool(),FileReadTool()])# 特定 Task 只允许用搜索工具安全限制public_research_taskTask(description只从公开互联网搜索信息,expected_output...,agentresearcher,tools[SerperDevTool()]# 覆盖 Agent 的工具集只允许搜索)# 另一个 Task 需要额外工具internal_research_taskTask(description结合内部数据库和互联网信息,expected_output...,agentresearcher,tools[SerperDevTool(),internal_db_tool]# 扩展工具集)三、结构化输出Pydantic 校验与类型安全当你需要 Task 的输出具有严格的结构如要存入数据库、传给下游 API可以使用 Pydantic 模型定义输出格式fromcrewaiimportTaskfrompydanticimportBaseModel,FieldfromtypingimportListclassTechTrend(BaseModel):name:strField(description技术名称)trl_level:intField(description技术成熟度等级 1-9,ge1,le9)github_url:strField(description主要 GitHub 仓库地址)summary:strField(description100字以内的技术概述)classResearchReport(BaseModel):topic:strtrends:List[TechTrend]Field(description识别到的技术趋势列表)conclusion:strField(description作者的综合结论)confidence_level:floatField(description作者对结论的信心度 0-1,ge0,le1)research_taskTask(description研究 {topic} 的技术趋势,expected_output结构化的技术趋势分析报告,agentresearcher,output_pydanticResearchReport# 指定 Pydantic 输出模型)# 执行后result 是 ResearchReport 实例类型安全resultcrew.kickoff(inputs{topic:具身智能})report:ResearchReportresearch_task.output.pydanticprint(report.trends[0].trl_level)# 有类型提示IDE 可自动补全四、任务模板化Jinja2 变量注入crewAI 的 Task description 和 expected_output 都支持 Jinja2 模板语法这让同一套 Task 定义可以服务于不同的运行时参数# 可复用的研究 Task 模板research_taskTask(description 对 {{topic}} 进行深度技术研究时间范围过去 {{months}} 个月。 重点关注 {{focus_area}} 方向输出语言{{language}}。 ,expected_output结构化调研报告,agentresearcher)# 不同参数运行同一个 Taskcrew.kickoff(inputs{topic:大语言模型量化压缩,months:6,focus_area:边缘设备部署,language:中文})crew.kickoff(inputs{topic:具身智能,months:12,focus_area:工业机器人应用,language:英文})五、回调机制任务完成后的处理链Task 支持 callback 函数在任务完成后异步触发importjsonfromdatetimeimportdatetimedefsave_research_result(task_output):任务完成后自动保存结果到文件timestampdatetime.now().strftime(%Y%m%d_%H%M%S)filenamefresearch_{timestamp}.jsonwithopen(filename,w,encodingutf-8)asf:json.dump({task:research,output:task_output.raw,timestamp:timestamp},f,ensure_asciiFalse,indent2)print(f研究结果已保存到{filename})defnotify_slack(task_output):任务完成后发送 Slack 通知slack_client.post_message(channel#ai-research,textf研究任务完成\n摘要{task_output.raw[:200]}...)research_taskTask(description...,expected_output...,agentresearcher,callbacksave_research_result# 任务完成后自动调用)六、YAML 配置方式与 Agent 类似Task 的生产环境推荐使用 YAML 声明# config/tasks.yamlresearch_task:description:对 {topic} 进行深度技术研究时间范围过去 {months} 个月。 重点关注技术成熟度、主要实现和商业案例。expected_output:包含以下章节的 Markdown 报告 技术概述、成熟度评估、主要实现方案表格、 商业案例3-5个、核心挑战、作者结论agent:researcheranalyze_task:description:基于已有的调研报告从投资价值角度进行深度分析。 重点评估技术壁垒、市场规模、竞争格局。expected_output:投资分析报告含明确的值得/不值得投资建议agent:analystcontext:[research_task]CrewBaseclassTechResearchCrew:tasks_configconfig/tasks.yamltaskdefresearch_task(self)-Task:returnTask(configself.tasks_config[research_task]# callback 等代码逻辑仍在 Python 中配置)taskdefanalyze_task(self)-Task:returnTask(configself.tasks_config[analyze_task],callbacknotify_slack)七、任务链设计的常见模式7.1 线性管道最常见Task A → Task B → Task C顺序依赖适合研究→分析→写作、采集→处理→报告7.2 扇出-汇聚并行后合并→ Task B分支1─┐ Task A ─── → Task C分支2─┼→ Task E汇聚 → Task D分支3─┘实现方式Task E 的 context 中同时引用 B、C、DTask(context[task_b,task_c,task_d])7.3 条件分支结合 Flows对于需要条件判断的复杂流程推荐结合 Flows 的router装饰器在 Flow 层面做分支控制Crew 负责每个分支内的具体执行。八、常见设计错误错误一expected_output 过于模糊# ❌ LLM 不知道完成的标准是什么expected_output关于这个话题的分析# ✅ 具体到格式、字数、必含要素expected_output 包含5个以上论点的分析报告800-1200字。 每个论点必须有数据支撑。格式Markdown使用 H2 标题分隔论点。 错误二不必要的 context 依赖# ❌ Task C 其实不需要 Task A 的输出但却添加了依赖task_cTask(context[task_a,task_b])# task_a 是无关的# ✅ 只声明真正需要的依赖task_cTask(context[task_b])不必要的 context 会使 LLM 的上下文窗口被无关信息占据增加 Token 消耗且可能干扰输出质量。错误三单个 Task 承担太多职责# ❌ 一个 Task 同时做研究分析写作质量难以保证mega_taskTask(description研究、分析并写出一篇完整的技术报告)# ✅ 拆分为多个专注的 Taskresearch_taskTask(description研究阶段收集原始信息)analyze_taskTask(description分析阶段提炼洞见)write_taskTask(description写作阶段组织为可读文章)九、小结Task 是 crewAI 中连接Agent 能力和业务需求的桥梁。设计好 Task 意味着description 精准给 Agent 明确的任务边界和评估框架expected_output 具体把完成的标准描述清楚而非留给 Agent 自己判断context 按需声明显式建立依赖关系让信息流转零代码适当使用 Pydantic需要结构化输出时类型安全比自由文本可靠得多Task 设计能力是区分 crewAI 初级用户和高级用户的核心差异。一个精心设计的 Task 链可以让能力普通的模型产出超出预期的质量而设计糟糕的 Task就算用最强的模型也会返回混乱的输出。系列导航上一篇crewAI Agent 深度定义角色、目标、背景故事与工具绑定下一篇crewAI 顺序与层级流程Sequential vs Hierarchical 决策矩阵基于 crewAI v1.11.0 官方文档撰写于 2026 年 3 月
crewAI Task 设计与上下文传递：输出期待与任务链依赖
发布时间：2026/7/9 1:43:53
crewAI Task 设计与上下文传递输出期待与任务链依赖本文基于 crewAI v1.11.0 官方文档系统拆解 Task 的五大要素、上下文传递机制和结构化输出校验实践。一、Task 是什么工作单元还是数据总线很多人把 crewAI 的 Task 简单理解为给 Agent 的一段指令。这个认知让你只用了 Task 20% 的能力。Task 的真正定位有两个维度第一维工作单元——定义一件事要做什么和做成什么样是驱动 Agent 行动的核心输入。第二维数据总线——Task 的输出不只是最终结果它会通过context机制自动流入下游 Task 的上下文成为整个多智能体协作系统中信息流转的数据通道。理解了这两个维度你才能设计出真正高效的多智能体工作流。二、Task 五要素详解2.1 description驱动推理的任务说明书fromcrewaiimportTask research_taskTask(description 你需要对 {topic} 这个技术方向进行深度研究。 研究维度要求 1. 技术成熟度评估TRL 1-9 标准 2. 主要开源实现GitHub 星数 5000 优先 3. 商业化落地案例至少 3 个 4. 核心技术挑战和未解决的问题 研究时间范围过去 12 个月内的信息为主基础理论部分不限时间。 避免不要引用未经验证的消息源不要做过度乐观的技术预测。 ,...)description 的编写原则具体化任务边界告诉 Agent 做什么不做什么避免领域提供评估标准如技术成熟度 TRL 标准让 Agent 用明确的框架思考注入偏好约束如避免过度乐观的预测直接影响输出质量善用 Jinja2 变量{topic}这类占位符让 Task 模板化、可复用2.2 expected_output定义完成的标准expected_output 是 crewAI Guardrails 机制的基础——Agent 会持续工作直到输出符合这里描述的预期。research_taskTask(description...,expected_output 一份结构化的技术调研报告必须包含以下部分 ## 技术概述200-300字 ## 成熟度评估TRL 等级 判断依据 ## 主要实现方案表格格式含GitHub链接 ## 商业案例3-5个含公司名、应用场景、规模估算 ## 核心挑战bullet list每条给出技术解释 ## 作者结论100字以内给出明确的值得/不值得深入判断 输出格式Markdown。不需要引言和致谢。 ,agentresearcher)关键点expected_output 越具体输出质量越稳定。含糊的写一份报告和具体的包含6个指定章节、字数范围、格式要求的报告最终质量差异显著。2.3 agent执行者的精确指派research_taskTask(description...,expected_output...,agentresearcher# 明确指派给 researcher Agent)在 Sequential 流程中agent 是必填的。在 Hierarchical 流程中Manager Agent 会根据任务内容和 Agent 能力自动分配此时可以省略 agent 参数。2.4 context任务链的数据传递context是 crewAI 中最精妙的设计之一。它建立了 Task 之间的显式依赖关系并自动完成数据传递# Task 1研究research_taskTask(description研究 {topic} 的技术现状,expected_output包含技术要点的调研报告,agentresearcher)# Task 2分析依赖 Task 1 的输出analyze_taskTask(description 基于已有的调研报告从投资价值角度进行深度分析。 重点评估技术壁垒、市场规模、竞争格局。 ,expected_output投资分析报告含明确的投资建议,agentanalyst,context[research_task]# research_task 的输出自动注入此处)# Task 3撰写同时依赖 Task 1 和 Task 2write_taskTask(description将技术调研和投资分析整合为面向高管的简报,expected_output500字以内的执行摘要,agentwriter,context[research_task,analyze_task]# 同时使用两个上游任务的输出)context 的数据流机制research_task.output │ ▼ [自动追加到 analyze_task 的 Prompt 中] 以下是已完成任务的输出请基于此继续工作 [research_task 的输出内容] │ ▼ analyze_task 执行 → analyze_task.output │ ▼ [自动追加到 write_task 的 Prompt 中] 以下是已完成任务的输出 [research_task 输出] [analyze_task 输出]这个机制让信息传递完全声明式——你只需要声明依赖关系crewAI 负责数据流转无需任何手动拼接 Prompt 的代码。2.5 toolsTask 级别的工具覆盖Task 级别的 tools 配置优先级高于Agent 级别的默认工具# Agent 有通用工具集researcherAgent(role研究员,tools[SerperDevTool(),ScrapeWebsiteTool(),FileReadTool()])# 特定 Task 只允许用搜索工具安全限制public_research_taskTask(description只从公开互联网搜索信息,expected_output...,agentresearcher,tools[SerperDevTool()]# 覆盖 Agent 的工具集只允许搜索)# 另一个 Task 需要额外工具internal_research_taskTask(description结合内部数据库和互联网信息,expected_output...,agentresearcher,tools[SerperDevTool(),internal_db_tool]# 扩展工具集)三、结构化输出Pydantic 校验与类型安全当你需要 Task 的输出具有严格的结构如要存入数据库、传给下游 API可以使用 Pydantic 模型定义输出格式fromcrewaiimportTaskfrompydanticimportBaseModel,FieldfromtypingimportListclassTechTrend(BaseModel):name:strField(description技术名称)trl_level:intField(description技术成熟度等级 1-9,ge1,le9)github_url:strField(description主要 GitHub 仓库地址)summary:strField(description100字以内的技术概述)classResearchReport(BaseModel):topic:strtrends:List[TechTrend]Field(description识别到的技术趋势列表)conclusion:strField(description作者的综合结论)confidence_level:floatField(description作者对结论的信心度 0-1,ge0,le1)research_taskTask(description研究 {topic} 的技术趋势,expected_output结构化的技术趋势分析报告,agentresearcher,output_pydanticResearchReport# 指定 Pydantic 输出模型)# 执行后result 是 ResearchReport 实例类型安全resultcrew.kickoff(inputs{topic:具身智能})report:ResearchReportresearch_task.output.pydanticprint(report.trends[0].trl_level)# 有类型提示IDE 可自动补全四、任务模板化Jinja2 变量注入crewAI 的 Task description 和 expected_output 都支持 Jinja2 模板语法这让同一套 Task 定义可以服务于不同的运行时参数# 可复用的研究 Task 模板research_taskTask(description 对 {{topic}} 进行深度技术研究时间范围过去 {{months}} 个月。 重点关注 {{focus_area}} 方向输出语言{{language}}。 ,expected_output结构化调研报告,agentresearcher)# 不同参数运行同一个 Taskcrew.kickoff(inputs{topic:大语言模型量化压缩,months:6,focus_area:边缘设备部署,language:中文})crew.kickoff(inputs{topic:具身智能,months:12,focus_area:工业机器人应用,language:英文})五、回调机制任务完成后的处理链Task 支持 callback 函数在任务完成后异步触发importjsonfromdatetimeimportdatetimedefsave_research_result(task_output):任务完成后自动保存结果到文件timestampdatetime.now().strftime(%Y%m%d_%H%M%S)filenamefresearch_{timestamp}.jsonwithopen(filename,w,encodingutf-8)asf:json.dump({task:research,output:task_output.raw,timestamp:timestamp},f,ensure_asciiFalse,indent2)print(f研究结果已保存到{filename})defnotify_slack(task_output):任务完成后发送 Slack 通知slack_client.post_message(channel#ai-research,textf研究任务完成\n摘要{task_output.raw[:200]}...)research_taskTask(description...,expected_output...,agentresearcher,callbacksave_research_result# 任务完成后自动调用)六、YAML 配置方式与 Agent 类似Task 的生产环境推荐使用 YAML 声明# config/tasks.yamlresearch_task:description:对 {topic} 进行深度技术研究时间范围过去 {months} 个月。 重点关注技术成熟度、主要实现和商业案例。expected_output:包含以下章节的 Markdown 报告 技术概述、成熟度评估、主要实现方案表格、 商业案例3-5个、核心挑战、作者结论agent:researcheranalyze_task:description:基于已有的调研报告从投资价值角度进行深度分析。 重点评估技术壁垒、市场规模、竞争格局。expected_output:投资分析报告含明确的值得/不值得投资建议agent:analystcontext:[research_task]CrewBaseclassTechResearchCrew:tasks_configconfig/tasks.yamltaskdefresearch_task(self)-Task:returnTask(configself.tasks_config[research_task]# callback 等代码逻辑仍在 Python 中配置)taskdefanalyze_task(self)-Task:returnTask(configself.tasks_config[analyze_task],callbacknotify_slack)七、任务链设计的常见模式7.1 线性管道最常见Task A → Task B → Task C顺序依赖适合研究→分析→写作、采集→处理→报告7.2 扇出-汇聚并行后合并→ Task B分支1─┐ Task A ─── → Task C分支2─┼→ Task E汇聚 → Task D分支3─┘实现方式Task E 的 context 中同时引用 B、C、DTask(context[task_b,task_c,task_d])7.3 条件分支结合 Flows对于需要条件判断的复杂流程推荐结合 Flows 的router装饰器在 Flow 层面做分支控制Crew 负责每个分支内的具体执行。八、常见设计错误错误一expected_output 过于模糊# ❌ LLM 不知道完成的标准是什么expected_output关于这个话题的分析# ✅ 具体到格式、字数、必含要素expected_output 包含5个以上论点的分析报告800-1200字。 每个论点必须有数据支撑。格式Markdown使用 H2 标题分隔论点。 错误二不必要的 context 依赖# ❌ Task C 其实不需要 Task A 的输出但却添加了依赖task_cTask(context[task_a,task_b])# task_a 是无关的# ✅ 只声明真正需要的依赖task_cTask(context[task_b])不必要的 context 会使 LLM 的上下文窗口被无关信息占据增加 Token 消耗且可能干扰输出质量。错误三单个 Task 承担太多职责# ❌ 一个 Task 同时做研究分析写作质量难以保证mega_taskTask(description研究、分析并写出一篇完整的技术报告)# ✅ 拆分为多个专注的 Taskresearch_taskTask(description研究阶段收集原始信息)analyze_taskTask(description分析阶段提炼洞见)write_taskTask(description写作阶段组织为可读文章)九、小结Task 是 crewAI 中连接Agent 能力和业务需求的桥梁。设计好 Task 意味着description 精准给 Agent 明确的任务边界和评估框架expected_output 具体把完成的标准描述清楚而非留给 Agent 自己判断context 按需声明显式建立依赖关系让信息流转零代码适当使用 Pydantic需要结构化输出时类型安全比自由文本可靠得多Task 设计能力是区分 crewAI 初级用户和高级用户的核心差异。一个精心设计的 Task 链可以让能力普通的模型产出超出预期的质量而设计糟糕的 Task就算用最强的模型也会返回混乱的输出。系列导航上一篇crewAI Agent 深度定义角色、目标、背景故事与工具绑定下一篇crewAI 顺序与层级流程Sequential vs Hierarchical 决策矩阵基于 crewAI v1.11.0 官方文档撰写于 2026 年 3 月
