AI Agent Engineer

AI Agent Engineer
个人学习进度

标记这门课程

课程正文公开可读；登录后可保存个人进度。

CrewAI 学习目录

11 min read

CrewAI 学习目录

知识库简介

CrewAI 是一个 Python Agent 编排框架，提供两组互补抽象：Crews 用 Agent、Task 和 Process 组织协作任务；Flows 用事件、路由和状态控制应用流程。官方 PyPI 描述明确区分二者：Crews 偏向自主协作，Flows 偏向细粒度、事件驱动的执行控制。

本库不把“多 Agent”当成默认答案。先确定任务、状态、工具权限和完成条件，再选择普通 Python、Flow、Crew 或两者组合。八节课程从安装和核心对象讲到状态、工具、记忆、评测、恢复与生产边界，最后依次完成框架无关 Layer A 和真实 CrewAI Layer B。

版本事实分成三层

  • 经测试包基线：本库的安装命令与 Layer B 固定为 crewai 1.15.4，该版本发布于 2026-07-17，声明要求 Python >=3.10,<3.14；现有 9 项真实 runtime 测试验证的是这一版本。
  • 最新包观察：PyPI 在 2026-07-21 显示最新稳定版为 crewai 1.15.5，发布于 2026-07-20。本轮只核对了版本与发布信息，没有在 1.15.5 上重跑本库示例，因此不把“最新可安装”写成“本库已验证”。
  • 文档内容快照：2026-07-21 针对 Flow、Checkpointing、Tools、Memory、Knowledge、Testing、Telemetry 与 Tracing 做了当前页面复核；Agents/Tasks/Processes 的对象形状仍保留 2026-07-14 的逐页深读记录。页面标签不是 PyPI 包版本，也不能替代锁定 wheel 的最小集成测试。

页面标签、最新 PyPI 版本与经测试基线不是同一事实。真实项目必须锁定安装版本，再用该版本源码、API Reference、最小导入测试和集成测试复核。本文记录的是指定日期的学习基线，不是永久 API 保证。

在总路线中的位置

本库位于“框架实践”阶段。选择 CrewAI 分支时，建议先理解 Agent 核心、Tool Calling（含 Function Calling） 和 Agentic Design Patterns 的相关能力，再把框架无关的循环、工具、状态、审批和评测映射到 CrewAI。这是框架学习的推荐顺序，不表示所有 Agent 角色都必须完成这些完整课程，也不表示 CrewAI 是 Agent/RAG 的普遍硬前置。

学习目标

  • 能解释 Agent、Task、Crew、Process、Flow、State 和 Event 的职责。
  • 能在普通 Python、Flow、Crew 和 Flow + Crew 之间选择最低复杂度方案。
  • 能用 Task 契约与结构化输出隔离 Agent 之间的数据边界。
  • 能区分 Flow state、当前 context、Memory 与 Knowledge。
  • 能为工具设置最小权限、参数校验、错误分类、幂等和审批。
  • 能设计离线单元测试、轨迹评测、真实模型试验和生产门槛。
  • 能识别文档/包版本漂移，并验证而不是猜测 API。

前置知识

  • Python 函数、类、装饰器、类型提示、异常、JSON 和基础 unittest。
  • 知道 LLM 调用会产生费用且输出有波动；理解 Tool Calling 和基本 Agent 循环。
  • 会在 Windows 11 PowerShell 7 中创建虚拟环境。

安装路线：先 venv + pip

不要在 Obsidian vault 内创建 .venv。在独立练习项目目录中，以兼容范围内的 Python 3.13 为例：

py -3.13 -m venv .venv  # 用兼容的 Python 3.13 在当前练习目录创建隔离环境。
.\.venv\Scripts\Activate.ps1  # 激活该环境，让后续 python 和 pip 指向 .venv。
python -m pip install --upgrade pip  # 先升级环境内的 pip，减少旧解析器导致的安装问题。
python -m pip install "crewai==1.15.4"  # 安装本课程实际验证过的 CrewAI 基线版本。
python -c "from importlib.metadata import version; print(version('crewai'))"  # 从已安装分发包读取并核对实际版本。

只有确实需要额外工具集时再安装：

python -m pip install "crewai[tools]==1.15.4"  # 仅在课程任务确实需要额外工具集时安装可选依赖。

上述 1.15.4 是本库经测试的运行基线，不是 2026-07-21 观察到的最新包；若新项目选择 1.15.5 或后续版本，应重新查 PyPI、发行说明和 Python 约束，并在该版本上重跑最小导入与集成测试。官方 Installation 页面当前主推 uv 和 CrewAI CLI；先理解 venv + pip 后，可按官方文档改用 uv 管理项目，但不要在同一环境里无计划地混用两个锁定来源。

运行前先决定遥测策略

CrewAI 当前 PyPI 的 Telemetry 说明称，框架默认发送匿名使用遥测，范围包括 CrewAI/Python/OS 版本、Agent/Task 数量、process、memory/delegation、并行方式、模型、角色和工具名称等；供应商说明默认不采集 Prompt、Task 正文、backstory/goal、API 调用与响应等内容。显式设置 share_crew=True 会进一步共享 goal、backstory、context 和 Task output 等详细执行数据。

在私有代码、客户数据或受监管环境中，先完成隐私审查并默认关闭不需要的外发遥测。优先用 CrewAI 专用的 CREWAI_DISABLE_TELEMETRY=true；OTEL_SDK_DISABLED=true 会同时关闭同一进程的其他 OpenTelemetry instrumentation。AMP tracing 还由独立配置控制，不能把关闭匿名 telemetry 当成全部 trace 已关闭；在锁定的 1.15.4 中，实例级 tracing=False 才是明确覆盖，环境变量值 false 仍可能回落到本机保存的 consent。生产环境应把“关闭、允许或改接自有 exporter”的决定写进部署配置并测试实际效果。不要把 share_crew=True 当调试捷径。

真实模型提供商通常需要凭据。本库不提供、不读取也不验证真实密钥；只在独立项目中使用环境变量或密钥管理服务，绝不把值写进 YAML、Markdown、测试夹具或 Git。

推荐学习顺序

  1. 核心对象：Crew、Agent、Task、Process：安装快照、对象职责、Task 契约和 Process 选择。
  2. Flow、State 与事件：用 start、listen、router、结构化状态和持久化控制流程。
  3. Tools 边界与结构化输出：工具权限、Pydantic 输出和 guardrail。
  4. Memory、Knowledge 与上下文：分清数据生命周期、存储和权限。
  5. 测试、评测与可观测性：从确定性测试到多 trial 在线评测。
  6. 安全、失败恢复与生产边界：检查点、幂等、沙箱和部署门槛。
  7. 项目：离线研究简报 Flow：运行、测试并迁移一个标准库项目。
  8. 项目：真实 CrewAI 持久化 Flow：验证锁定 runtime、SQLite state 水合、fork 与 receipt 后崩溃恢复。

动手实践或项目入口

Layer A 使用三个确定性 Task 桩模拟研究、写作与审核，再由外层 Flow 控制修订预算、终态和发布：

  • examples/offline_research_flow.py
  • examples/sources.json
  • examples/test_offline_research_flow.py

Layer A 不导入 CrewAI、不联网、不调用模型；它验证的是架构契约。Layer B 位于 examples/crewai_layer_b/，直接运行 crewai==1.15.4，用 9 项测试验证 Flow decorators、SQLite persistence、同 UUID 水合、flow_id 规范化、未知 ID 的 resume/fork 失败关闭、operation/payload 冲突、fork 与独立 receipt；它仍不调用模型，因此只声称 runtime 控制面已验证，不声称真实模型质量或生产并发已验证。

掌握标准

  • 能在一句话内区分 Crew 与 Flow，并给出各自不适合的任务。
  • 能为 Agent 设置能力和工具边界，为 Task 写可验证产物。
  • 能解释 sequential 与 hierarchical Process 的额外成本和要求。
  • 能用结构化 state 和有限路由控制循环与终态。
  • 能区分 Memory、Knowledge、state 与当轮 context。
  • 能让写工具经过执行层校验、审批和幂等保护。
  • 能在普通、-O、warnings-as-errors 三种模式运行离线测试。
  • 能在锁定依赖环境中运行真实 Flow 恢复测试，并区分 state UUID 与业务 operation ID。
  • 能记录包版本、页面标签、模型、工具 schema、数据与评测集版本。

与其他知识库的关系

  • Agentic Design Patterns 提供框架无关的路由、并行、审批、恢复和评测模式。
  • LangChain 与 LangGraph 是另一组组件和状态编排抽象；比较时应使用同一任务集、模型和成本口径。
  • MCP 可为 Agent 暴露远程工具，但协议连接不等于工具已获授权或可信。
  • CrewAI 只负责部分运行时能力；LLMOps、监控、安全和治理仍需独立工程设计。

主要参考资料

Backlinks