CrewAICrewAI

模型与开放条件Model & openness

它的模型接入路径最具体。默认走 OpenAI API，本地模型官方点名了 Ollama 工具。

README 按这个顺序写。默认 OpenAI，另有多种连接方式，例如本地模型走 Ollama 工具。

"CrewAI supports using various LLMs through a variety of connection options. By default your agents will use the OpenAI API when querying the model. However, there are several other ways to allow your agents to connect to models. For example, you can configure your agents to use a local model via the Ollama tool."

FAQ 还补了一句：LM Studio 也能接。

官方原文："Tools like Ollama and LM Studio allow seamless integration"

这条对本站读者特别有价值：本地量化模型在这三个编排框架里， 只有 CrewAI 在 README 首屏级别点名了具体工具。

完整 provider 清单已核到（官方 learn/llm-connections 页），分两类：

• 原生 SDK 接入 5 家 —— OpenAI、Anthropic、Google Gemini、Azure、AWS Bedrock
• 其余走 LiteLLM 兜底，装法 uv add 'crewai[litellm]'。官方另点名单列： Ollama、Mistral、Groq、Cohere、Hugging Face、Replicate、Together AI、 Cloudflare Workers AI、DeepInfra、SambaNova、Nebius、NVIDIA NIMs。

这条清单以 "And many more!" 结尾，指向 LiteLLM Providers 文档取全量列表

另外，官方页原文也给了默认模型：

官方原文："By default, CrewAI uses the gpt-4o-mini model."

它由 OPENAI_MODEL_NAME 决定，未设即 gpt-4o-mini。换法两种： 传字符串标识符（llm='claude-2'），或用 LLM 类配 model / base_url / api_key。 本地片段官方写全：

官方示例：LLM(model="ollama/llama3.2", base_url="http://localhost:11434")

未知：换 provider 后 tool calling / structured output 的可靠性，官方未说明。 （已查 learn/llm-connections 与 concepts/llms 两页，无 provider 间可靠性对比。）

Its model-access path is the most concrete. Defaults to the OpenAI API, and local models are officially named via the Ollama tool.

The README writes in this order. Default OpenAI, plus several connection options, e.g. local models via the Ollama tool.

"CrewAI supports using various LLMs through a variety of connection options. By default your agents will use the OpenAI API when querying the model. However, there are several other ways to allow your agents to connect to models. For example, you can configure your agents to use a local model via the Ollama tool."

The FAQ adds one more: LM Studio can also be connected.

Official wording: "Tools like Ollama and LM Studio allow seamless integration"

This is especially valuable for this site's readers: among the three orchestration frameworks, for running local quantized models, only CrewAI names concrete tools at README-first-screen level.

The full provider list is verified (official learn/llm-connections page), in two classes:

• native SDK integration, 5 vendors — OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock
• the rest fall back to LiteLLM, installed via uv add 'crewai[litellm]'. The official page additionally names individually: Ollama, Mistral, Groq, Cohere, Hugging Face, Replicate, Together AI, Cloudflare Workers AI, DeepInfra, SambaNova, Nebius, NVIDIA NIMs.

This list ends with "And many more!", pointing to the LiteLLM Providers docs for the full list

Also, the official page states the default model verbatim:

Official wording: "By default, CrewAI uses the gpt-4o-mini model."

It is decided by OPENAI_MODEL_NAME; unset means gpt-4o-mini. Two ways to switch: pass a string identifier (llm='claude-2'), or use the LLM class with model / base_url / api_key. The local snippet is given in full officially:

Official example: LLM(model="ollama/llama3.2", base_url="http://localhost:11434")

Unknown: tool calling / structured output reliability after switching providers, not stated officially. (learn/llm-connections and concepts/llms pages checked; no cross-provider reliability comparison.)

运行位置Where it runs

它是纯库，官方口径是「从原型到生产不用换框架」。

安装是 pip 包（README Getting Started 走 pip install + crewai CLI），没有托管服务。

"Move from experiment to production without changing frameworks."

状态持久化官方定位成「随系统成长再加」，README 两处原文都带这个限定语：

"Add tools, memory, checkpointing, and async execution as your system grows"

"Add deterministic steps, human input, structured outputs, and checkpointing as your system grows"

那是 README 的定位话术。

机制本身官方文档给得很细。见官方 concepts/checkpointing 页：

• 粒度：事件驱动，默认 on_events=["task_completed"]， 即每完成一个 task 落一次盘；CheckpointConfig 可改频率与上限

• 落盘后端两个：JsonProvider（每次一个文件，默认，写在 ./.checkpoints/）、 SqliteProvider（单个 SQLite 库，开 WAL，适合高频）

• 开关：Crew / Flow / Agent 都可传 checkpoint；子级默认继承父级， 也可传 False 退出

粒度是「每个完成的 task / method」，这正是本站要找的落盘粒度。

It is a pure library; the official line is "from prototype to production without changing frameworks."

Install is a pip package (README Getting Started uses pip install + the crewai CLI); there is no hosted service.

"Move from experiment to production without changing frameworks."

State persistence is positioned officially as "add as your system grows"; both README quotes carry that qualifier:

"Add tools, memory, checkpointing, and async execution as your system grows"

"Add deterministic steps, human input, structured outputs, and checkpointing as your system grows"

That is README positioning language.

The mechanism itself is documented in detail officially. See the official concepts/checkpointing page:

• granularity: event-driven, default on_events=["task_completed"], i.e. one checkpoint per completed task; CheckpointConfig can change frequency and caps

• two storage backends: JsonProvider (one file per checkpoint, default, under ./.checkpoints/), SqliteProvider (a single SQLite database, WAL enabled, suited to high frequency)

• switches: Crew / Flow / Agent all accept checkpoint; children inherit parents by default, and can pass False to opt out

The granularity is "each completed task / method" — exactly the checkpoint granularity this site looks for.

本地文件Local files

框架本身不内置文件系统能力，文件读写靠工具提供 —— 但工具的默认边界清楚。

默认边界已核到（官方 FileReadTool 页）。运行时传入的路径必须落在 base_dir 内。 base_dir 默认是当前工作目录。.. 与符号链接都会先解析再校验，

so they cannot be used to escape

两个例外：

• 构造函数里写死的 file_path 属开发者声明，可越过该限制，但只放行这一个文件
• 放开更大范围须显式 base_dir='/data'

两个环境变量管逃生与锁死：

• 逃生阀 CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true —— 进程级。

官方称它会同时关掉所有 crewai-tools 的 SSRF 防护，不建议

• 托管 worker 应用用 CREWAI_TOOLS_FORCE_SAFE_PATHS=true 锁死

另有一组多模态文件输入（crewai[file-processing] extra，Files 页，early access）。 可传图片 / PDF / 音频 / 视频 / 文本。

未知：容器部署时的默认权限，官方未说明。（已查 Files 页与 FileReadTool 页。）

The framework itself ships no filesystem capability; file read/write comes from tools — but the tools' default boundary is clear.

The default boundary is verified (official FileReadTool page). Paths passed in at runtime must fall inside base_dir. base_dir defaults to the current working directory. .. and symlinks are resolved before validation,

so they cannot be used to escape

Two exceptions:

• a file_path hardcoded in the constructor is a developer declaration and may bypass that limit, but only that one file is allowed
• opening a wider range requires an explicit base_dir='/data'

Two environment variables manage the escape hatch and the lockdown:

• escape hatch CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true — process-level.

The official docs say it also turns off SSRF protection for all crewai-tools; not recommended

• managed worker apps lock it down with CREWAI_TOOLS_FORCE_SAFE_PATHS=true

There is also a set of multimodal file inputs (crewai[file-processing] extra, Files page, early access). Images / PDFs / audio / video / text can be passed.

Unknown: default permissions under container deployment, not stated officially. (Files page and FileReadTool page checked.)

关机后的任务Tasks after shutdown

它不托管后台。 库本身不提供厂商托管的执行环境 —— 要「电脑关了还能跑」， 得自己把进程跑在自有服务器 / VPC 上。AMP 商业侧另给 Cron scheduling。

Flow 的 state management 是官方明文。 README 把 Flow 描述成 "event-driven workflows with state, branching, routing"， FAQ 说 Flow 适合 "detailed execution paths and secure state management"。

state 是显式、结构化的（README「Using Crews and Flows Together」段示例代码）。

class MarketState(BaseModel)，Flow[MarketState] 里直接读写 self.state.sentiment 等字段，并按 self.state.confidence 的数值阈值分支。

这就是本站要找的「状态」：显式、结构化、可分支判断。

落盘与跨进程恢复已核到（官方 concepts/checkpointing、concepts/flows 页）：

• Flow 的 @persist 装饰器：官方称 "automatically persists all flow method states"， 默认后端 SQLiteFlowPersistence

• 续跑：kickoff(inputs={"id": <uuid>}) —— 同一 flow_uuid 续写历史
• 分叉：kickoff(restore_from_state_id=<uuid>) —— 换新 state.id，原历史不动
• checkpoint 恢复：crew / flow / agent 的 checkpoint 可从 ./.checkpoints/ 恢复， CLI crewai checkpoint 提供 resume / fork

It does not host a background. The library provides no vendor-managed execution environment — for "keeps running after the computer shuts down", you must run the process on your own servers / VPC. The AMP commercial side separately offers Cron scheduling.

Flow's state management is explicit official wording. The README describes Flow as "event-driven workflows with state, branching, routing", and the FAQ says Flow suits "detailed execution paths and secure state management".

State is explicit and structured (example code in the README's "Using Crews and Flows Together" section).

class MarketState(BaseModel), with Flow[MarketState] reading and writing self.state.sentiment and similar fields directly, branching on numeric thresholds of self.state.confidence.

This is the "state" this site looks for: explicit, structured, branchable.

Persistence and cross-process recovery verified (official concepts/checkpointing, concepts/flows pages):

• Flow's @persist decorator: officially "automatically persists all flow method states", default backend SQLiteFlowPersistence

• resume: kickoff(inputs={"id": <uuid>}) — same flow_uuid continues the history
• fork: kickoff(restore_from_state_id=<uuid>) — new state.id, original history untouched
• checkpoint restore: crew / flow / agent checkpoints can be restored from ./.checkpoints/; the crewai checkpoint CLI provides resume / fork

工具与扩展Tools & extensions

官方明确列了 MCP 与 A2A 两项，这是它的一个强项。

"Use tools, memory, knowledge, checkpointing, async execution, and MCP/A2A support for more capable production agents."

MCP 是核心依赖，不是可选 extra。 官方 lib/crewai/pyproject.toml 的 [project] dependencies 里直接写死 mcp~=1.28.1。

A2A 才是可选 extra：a2a = ["a2a-sdk~=0.3.10", ...]。 这与 OpenAI Agents SDK 把 mcp>=1.19.0 放进 dependencies 一致，属核心能力。

MCP 的接入面：

• 传输三种：stdio / SSE / Streamable HTTP（各一页）
• DSL 字段 mcps=；多 server 聚合用 MCPServerAdapter
• 另有 MCP security 专页
• 内置工具是 crewai-tools（官方称 75+ OSS catalog，装 crewai[tools]）

另外，CrewAI 自己托管了一个文档 MCP server（docs.crewai.com/mcp）， 可供 AI 编程助手查询它的 API 细节（README「Build with AI」段提到的 ask-docs）。

A2A（Agent-to-Agent）的规范与生态仍属外部协议：本站只记 「官方有 a2a extra 与一批 A2A 事件」，协议规范不在本站研究范围。

The official docs explicitly list MCP and A2A — one of its strengths.

"Use tools, memory, knowledge, checkpointing, async execution, and MCP/A2A support for more capable production agents."

MCP is a core dependency, not an optional extra. The official lib/crewai/pyproject.toml [project] dependencies pins mcp~=1.28.1 directly.

A2A is the optional extra: a2a = ["a2a-sdk~=0.3.10", ...]. This matches the OpenAI Agents SDK putting mcp>=1.19.0 in dependencies — a core capability.

The MCP integration surface:

• three transports: stdio / SSE / Streamable HTTP (one page each)
• DSL field mcps=; multi-server aggregation via MCPServerAdapter
• there is also an MCP security dedicated page
• built-in tools are crewai-tools (officially a 75+ OSS catalog, install crewai[tools])

Additionally, CrewAI hosts its own documentation MCP server (docs.crewai.com/mcp), queryable by AI coding assistants for its API details (the ask-docs mentioned in the README's "Build with AI" section).

The A2A (Agent-to-Agent) specification and ecosystem remain an external protocol: this site only records "the official docs have an a2a extra and a batch of A2A events"; the protocol spec is outside this site's research scope.

上下文与记忆Context & memory

它给了一套统一 memory 系统，外加独立的 knowledge。机制已核到。

README 里与记忆相关的表述有两处：

• Key Features 的 "memory, knowledge, checkpointing"
• 「Build with AI」段的 agent 配置项清单 "Configuring agents — role, goal, backstory, tools, LLMs, memory, guardrails"

机制已核到，且推翻旧判断（官方 concepts/memory 页）。官方现有统一 Memory 类。

官方原文："a single Memory class that replaces separate short-term, long-term, entity, and external memory types with one intelligent API"

即旧档案「官方不区分工作记忆 / 长期记忆」的说法已过时。

具体机制：

• 作用域：分层 scope 树（类文件系统，如 /agent/researcher）。Crew 级默认共享。 agent 可用 memory.scope("/agent/x") 取私有子树。另有 slice() 做跨分支只读 / 读写视图

• 存储后端：默认平台目录下的向量库，默认 ChromaDB，路径可由 CREWAI_STORAGE_DIR 改。

知识存储官方称 "uses the same storage system as memory"

• 裁剪不是简单截断：检索用 semantic + recency + importance 复合打分。 写入走 LLM 抽取原子事实 + consolidation/dedup （相似度过阈值时由 LLM 决定 keep / update / delete）

• knowledge 与 memory 的关系：knowledge 是 RAG 事实库（独立 collection，agent/crew 两级）。 memory 是跨任务的统一记录库。两者共用向量存储，用途不同。

It provides a unified memory system plus separate knowledge. The mechanism is verified.

Two memory-related statements in the README:

• Key Features' "memory, knowledge, checkpointing"
• the agent-config checklist in the "Build with AI" section: "Configuring agents — role, goal, backstory, tools, LLMs, memory, guardrails"

The mechanism is verified, and it overturns the old judgment (official concepts/memory page). The official docs now have a unified Memory class.

Official wording: "a single Memory class that replaces separate short-term, long-term, entity, and external memory types with one intelligent API"

That is, the old entry's "official docs do not distinguish working / long-term memory" is outdated.

The concrete mechanism:

• scopes: a hierarchical scope tree (filesystem-like, e.g. /agent/researcher). Crew-level is shared by default. Agents can take a private subtree via memory.scope("/agent/x"). slice() provides cross-branch read-only / read-write views.

• storage backend: a vector store under the platform directory, ChromaDB by default, path changeable via CREWAI_STORAGE_DIR.

The knowledge store officially "uses the same storage system as memory"

• pruning is not simple truncation: retrieval uses a composite semantic + recency + importance score. Writes go through LLM extraction of atomic facts + consolidation/dedup (when similarity crosses the threshold, the LLM decides keep / update / delete)

• knowledge vs memory: knowledge is a RAG fact base (separate collection, agent/crew two levels). Memory is the unified cross-task record store. The two share vector storage but serve different purposes.

权限与限制Permissions & limits

guardrails 是「任务输出校验」，不是权限边界 —— 这一点与旧判断不同。

官方 concepts/tasks 页「Task Guardrails」原文：

官方原文："validate and transform task outputs before they are passed to the next task"

两类实现：

• 函数式 —— 传 guardrail= 回调，返回 (bool, result)，确定性校验
• LLM 式 —— 传字符串描述，自动建 LLMGuardrail，用该 task 的 agent 的 LLM 判
• 相关字段 —— guardrail / guardrails / guardrail_max_retries（默认 3 次）

关键判定：它只拦输出（task 产出），不是双向校验，也不改状态：

• 不是 OpenAI Agents SDK 那种 input + output 双向校验
• 不是 ADK 的 Tool Confirmation 执行前确认
• 不是 LangGraph 的 interrupts 改状态

所以对照表里 CrewAI 应写作「校验 task 输出、失败重试」。

沙箱：OSS 无进程 / 容器级沙箱。 边界来自工具本身 —— 文件工具默认把路径限制在 base_dir。默认是 cwd，见 local_files 轴。 MCP 安全官方明说是「信任」问题、不提供内置防护。

未知：网络访问控制官方无机制（已查 tasks 页与 mcp/security 页）。 RBAC / SSO / PII redaction 属 AMP 商业侧，开源版没有。

Guardrails are "task output validation", not a permission boundary — this differs from the old judgment.

Official concepts/tasks page "Task Guardrails" wording:

Official wording: "validate and transform task outputs before they are passed to the next task"

Two implementation styles:

• functional — pass a guardrail= callback returning (bool, result), deterministic validation
• LLM-style — pass a string description; an LLMGuardrail is auto-built, judged by the task's agent's LLM
• related fields — guardrail / guardrails / guardrail_max_retries (default 3)

Key judgment: it only gates outputs (task products), not two-way validation, and it does not change state:

• not the OpenAI Agents SDK style of input + output two-way validation
• not ADK's Tool Confirmation pre-execution check
• not LangGraph's interrupts changing state

So in the comparison table CrewAI should read "validates task outputs, retries on failure".

Sandbox: OSS has no process / container-level sandbox. The boundary comes from the tools themselves — file tools restrict paths to base_dir by default. Default is cwd, see the local_files axis. MCP security is officially stated as a matter of "trust", with no built-in protection.

Unknown: network access control has no official mechanism (tasks page and mcp/security page checked). RBAC / SSO / PII redaction belong to the AMP commercial side; the open-source version does not have them.

适合什么任务Best for

适合三类场景。

• 任务能被表述成「一支有角色分工的团队」（Crews）
• 需要业务逻辑留在普通 Python 里、并显式控制执行路径（Flows）
• 想在本地模型上跑（官方点名 Ollama / LM Studio）；需要 MCP 与 A2A 接入；Python 栈

不适合三类场景。 都写在同一张否定的清单里：

• 需要进程 / 容器级沙箱或网络访问控制 —— 官方无此机制； guardrails 只校验 task 输出，文件工具只限 base_dir

• 需要把「工作记忆」与「跨会话长期记忆」分开管理 —— CrewAI 已统一成一个 Memory 类， 不再分型，与 LangGraph 的分型路线相反

• 需要厂商托管的真后台 —— 纯库，得自己部署到自有服务器 / VPC

Fits three scenarios.

• tasks expressible as "a team with role division" (Crews)
• needing business logic to stay in plain Python with explicit control of execution paths (Flows)
• wanting to run on local models (officially naming Ollama / LM Studio); needing MCP and A2A integration; Python stacks

Does not fit three scenarios. All on the same negative list:

• needing process / container-level sandboxing or network access control — no official mechanism; guardrails only validate task outputs, file tools only limit base_dir

• needing "working memory" and "cross-session long-term memory" managed separately — CrewAI has unified them into one Memory class, no longer typed, the opposite of LangGraph's typed route

• needing a vendor-hosted true background — pure library; deploy it yourself to your own servers / VPC

class MarketState(BaseModel):
    ...

class AdvancedAnalysisFlow(Flow[MarketState]):
    def run(self):
        self.state.sentiment = "analyzing"
        if self.state.confidence > 0.8:
            ...
        elif self.state.confidence > 0.5:
            ...

class MarketState(BaseModel):
    ...

class AdvancedAnalysisFlow(Flow[MarketState]):
    def run(self):
        self.state.sentiment = "analyzing"
        if self.state.confidence > 0.8:
            ...
        elif self.state.confidence > 0.5:
            ...

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.