必须满足下面两种接口之一: 1.继承BaseTool 2.使用@tool装饰器

参数要求:

• 拥有一个 name —— 一个简短的描述性标识符。
• 拥有一个 description —— 告诉代理何时以及如何使用该工具。这直接影响代理使用工具的效果，因此请务必清晰具体。
• 实现 _run (BaseTool) 或提供 函数体 (@tool) —— 这是同步执行逻辑。
• 对所有参数和返回值使用 类型注解。
• 返回一个 字符串 结果（或可以有意义地转换为字符串的内容）。

crew:团队,更适合复杂和创造性更强的用例,强调自主性和协作智能优化 flow:流程,通过事件进行触发,有严格的执行决策路径,适合路径确定,有更高的安全需求的用例,强调细粒度,事件驱动的控制

一些核心概念

对于团队 crew,agent,process,task

对于流程

flow,事件,state(context),crew support

如何决策框架(Crew or Flow or Both)

在于理解应用的精确性和复杂性

复杂性-精确度矩阵详解

什么是复杂性？

在CrewAI应用的上下文中，复杂性指的是：

• 所需的不同步骤或操作数量
• 需要执行任务的多样性
• 不同组件之间的相互依赖关系
• 对条件逻辑和分支的需求
• 整体工作流程的复杂程度

什么是精确率？

精确度在此上下文中指的是：

• 最终输出所需的准确度
• 对结构化、可预测结果的需求
• 可重现性的重要性
• 每个步骤所需的控制级别
• 输出结果的容差范围

四个象限

1. 低复杂度，低精度

特性：

• 简单、直接的任务
• 对输出结果存在一定变化的容忍度
• 步骤数量有限
• 创意或探索性应用

推荐方法：使用最少智能体的简单Crews示例用例：

• 基础内容生成
• 创意头脑风暴
• 简单的摘要任务
• 创意写作辅助

2. 低复杂度，高精度

特性：

• 需要精确、结构化输出的简单工作流
• 需要可重现的结果
• 步骤有限但精度要求高
• 通常涉及数据处理或转换

推荐方法： 使用直接LLM调用的流程或具有结构化输出的简单Crews示例用例：

• 数据提取与转换
• 表单填写与验证
• 结构化内容生成（JSON、XML）
• 简单的分类任务

3. 高复杂度，低精度

特性：

• 包含多个步骤的多阶段流程
• 创意或探索性输出
• 组件间的复杂交互
• 对最终结果的差异容忍度

推荐方法：使用包含多个专业智能体的复杂Crew示例用例：

• 研究与分析
• 内容创作流水线
• 探索性数据分析
• 创造性问题解决

4. 高复杂度，高精度

特性：

• 需要结构化输出的复杂工作流
• 具有严格准确性要求的多重相互依赖步骤
• 需要复杂的处理和精确的结果
• 通常是关键任务应用

推荐方法： 通过验证步骤编排多个Crew的流程示例用例：

• 企业决策支持系统
• 复杂数据处理流水线
• 多阶段文档处理
• 受监管行业应用

决策

when crew: 协作智能;问题需要思考;任务为创意性或者分析性;重视适应性而非严格结构;输出格式具有灵活性

when flow: 执行过程需要精确控制;应用具有复杂的状态需求;需要结构化可预测的输出;工作流程设计逻辑条件;需要将人工智能和过程化代码相结合

when both: 复杂地多阶段流程;需要兼顾创意和结构的应用场景;企业级人工智能应用

2.打造高效的智能体

80/20法则:专注于任务而非智能体

80%的精力放在设计任务上,20%放在定义智能体上

设计的核心原则

1.角色-目标-背景故事框架

角色:智能体的专业职能: 具体专业;符合现实;包含领域专长

目标:智能体的目标和动机: 明确且以结果为导向;强调质量标准;纳入成功标准

背景故事:智能体的经验和视角 尽力专长和经验;定义工作风格和价值观;创造连贯的人格

2.专家优于通才

高度专注的智能体提供更加精确和更强相关性的输出

3.平衡专业化与多功能性

角色专业化,应用多功能化;避免过于狭隘的定义;考虑协作环境

4.设置适当的专家水平:

新手;中级;专家;世界级;

为你的智能体打造高效任务

高效任务的解剖结构

任务描述:过程

详细的执行说明;上下文和背景信息;范围和限制;需要遵循的流程步骤

预期输出:交付物

格式规范(js,md);结构要求;质量标准;优质输出的示例

1.单一目的,单一输出 2.明确输入和输出 3.包含目的和上下文 4.使用结构化输出工具

应该避免的常见错误:

1.任务说明不明确 2.试图做太多全能任务 3.描述与预期输出不匹配 4.你自己都不了解流程 5.过早使用层级结构 6.模糊胡总和通用的智能体定义

设计策略:

协作设计:

在一个crew中的agent: 互补技能;交接点;建设性的张力

创建专业的工具使用者

使agent适应LLM能力

测试和迭代智能体设计

1.从原型开始 2.使用样本任务测试 3.分析输出 4.优化定义 5.在协作中测试

提供了一种在整个生命周期内唯一表示和追踪组件的方法,每个agent,crew,task在创建时都会获得一个唯一的,无法手动覆盖的指纹

工作原理

指纹时crewai.security模块中的Fingerprint类的实例,包含: UUID字符串:唯一标识符,自动生成且无法手动覆盖 创建时间戳:自动设置无法手动覆盖 元数据:可自定义的附加信息字典

基本用法

访问指纹:

处理指纹元数据:

向指纹添加元数据以获得更多的上下文信息:

指纹持久性

在整个生命周期内保持不变

确定性指纹

虽然不能设置UUID和创建时间戳,但是可以使用带有种子的generate方法来创建确定性指纹

高级用法

指纹结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from crewai.security import Fingerprint

fingerprint = agent.fingerprint

# UUID string - the unique identifier (auto-generated)
uuid_str = fingerprint.uuid_str  # e.g., "123e4567-e89b-12d3-a456-426614174000"

# Creation timestamp (auto-generated)
created_at = fingerprint.created_at  # A datetime object

# Metadata - for additional information (can be customized)
metadata = fingerprint.metadata  # A dictionary, defaults to {}

理解流程中状态的作用:

状态系统允许你维护上下文,在步骤之间共享数据,并构建复杂的应用逻辑

为什么状态管理很重要:

1.维持上下文 2.构建复杂的条件逻辑 3.创建持久化应用 4.优雅地处理错误 5.拓展你的应用 6.实现对话式的应用

状态管理基础

流程状态生命周期:

1.初始化 2.修改 3.传输 4.持久化(可选):保存到存储中 5.完成

状态管理的两种方法:

1.非结构化状态:灵活性 2.结构化状态:使用Pydantic模型:类型安全性和验证

非结构化状态管理:

工作原理:

使用self.state访问状态,行为类似于字典;可以随时增删改查键;所有状态自动对所有流程方法可用

when

快速原型开发和简单流程;动态演变的状态需求;预先无法确定的结构情况;状态要求简单的流程

结构化状态管理

工作原理:

定义一个表述状态结构的Pydantic模型 模型类型作为类型参数传给flow类 通过self.state访问状态,行为类似于Pydantic模型实例 所有字段根据定义的类型进行验证

优势:

1. 类型安全
2. 自我文档化
3. 验证
4. IDE支持
5. 默认值

when

• 明确数据模式的复杂流程
• 多名开发者共同参与的团队项目
• 需要验证数据验证的应用城西
• 需要强制执行特定数据类型和约束的流程

自动状态ID

唯一标识符,对于非结构化,通过self.state[“id”]访问,对于结构化,则通过self.state.id访问 在流程中自动生成,整个生命周期不变,用于记录,跟踪和检索已经持久化的状态

动态状态更新

在步骤之间传递数据

流程方法可以返回值,这些值随后作为参数传递给监听方法

持久化流程状态

@persist()装饰器:可以自动执行状态持久化,在执行的关键点保存你的流程状态

类级别持久化:在每次方法执行后保存状态

方法级别持久化:更加细粒度的控制,将其用于特定方法

派生(Forking)持久化状态

@persist 在 kickoff / kickoff_async 上支持两种不同的水合模式。使用 resume (inputs["id"]) 继续同一血缘；使用 fork (restore_from_state_id) 从快照启动一个新的血缘

高级状态模式

条件启动和可恢复执行

flow支持条件@start()和用于HILT/循环场景的可恢复执行

基于状态的条件逻辑

使用状态在流程中实现复杂的条件逻辑

处理复杂的状态转换

对于复杂的状态转换,可以创建专用方法

与Crew一起的状态管理

将状态传给crew

将参数传给agent的创建方法中

在状态中处理crew输出

状态管理最佳实践

1. 保持状态聚焦:设计时仅包含必要内容
2. 复杂流程使用结构化状态
3. 记录状态转化
4. 优雅地处理状态错误
5. 使用状态进行进度跟踪
6. 尽可能使用不可变操作

1

crewai create crew research_crew

第二步:探索项目结构

遵循py项目的最佳实践,通过分离配置文件和实现代码,在不修改源代码的情况下修改团队的行为

第三步:配置你的智能体

通过修改agent.yaml来定义智能体 role;goal;backstory;llm

第四步:定义你的任务

任务代表可智能体将要执行的具体工作,包括详细的说明和预期输出 通过修改task.yaml文件 包含description和expected_output,context

第五步:配置你的团队

通过crew.py文件来配置

第六步:设置你的主脚本

第七步:设置你的环境变量

.env文件

第八步:安装依赖项

1

crewai install

第九步:运行你的团队

1

crewai run

第十步:查看你的输出

why

1.针对LLM进行优化 2.更改语言 3.针对复杂领域进行专业化 4.调整语气和风格 5.支持超个性化用例

了解CrewAI的提示词系统

• 智能体模板 (Agent templates) – 控制每个智能体对其指定角色的处理方式。
• 提示词片段 (Prompt slices) – 控制任务、工具使用和输出结构等专门行为。
• 错误处理 (Error handling) – 指导智能体如何应对失败、异常或超时。
• 工具专用提示词 (Tool-specific prompts) – 定义如何调用或使用工具的详细说明。

了解默认系统指令

当通过role,goal,backstory定义agent时,自动注入的一些指令

CrewAI自动注入的内容

针对无工具的智能体

1

"I MUST use these formats, my job depends on it!"

针对有工具的智能体

1
2
3
4
5

"IMPORTANT: Use the following format in your response:

Thought: you should always think about what to do
Action: the action to take, only one name of [tool_names]
Action Input: the input to the action, just a simple JSON object...

针对结构化输出（JSON/Pydantic）

1
2

"Ensure your final answer contains only the content in the following format: {output_format}
Ensure the final output does not include any code block markers like ```json or ```python."

查看完整提示词

覆盖默认指令

选项一(推荐):自定义模板 选项二:自定义提示词文件 创建一个custom_prompt.json文件 选项三:为o1模型禁用系统提示词

使用观测性工具进行调试

生产环境最佳实践

1. 始终检查生成的提示词，然后再部署到生产环境。
2. 使用自定义模板，当您需要全面控制提示词内容时。
3. 集成可观测性工具以进行持续的提示词监控（参阅 可观测性文档）。
4. 使用不同的 LLM 进行测试，因为默认指令在不同模型间的表现可能不同。
5. 记录您的提示词自定义内容，以保持团队透明度。

管理提示词文件的最佳实践

1. 保持文件独立 – 将自定义提示词存储在主代码库之外的专用 JSON 文件中。
2. 版本控制 – 在代码仓库中跟踪更改，确保提示词的调整有清晰的文档记录。
3. 按模型或语言组织 – 使用如 prompts_llama.json 或 prompts_es.json 的命名方案，以便快速识别专用配置。
4. 记录更改 – 提供注释或维护一个 README 文件，详细说明自定义的目的和范围。
5. 最小化改动 – 仅覆盖确实需要调整的特定片段，保持其他部分的默认功能完好无损。