ask-docs

提问 CrewAI 文档

根据用户实际运行的 crewai 版本，从官方文档中查找答案，解答 CrewAI 相关问题。

已于 2026-10-01 根据 crewai 1.15.23 和以下文档站点进行核验。 已于 2026-10-01 使用真实 LLM 进行实测。

CrewAI 有两个文档站点：

站点	涵盖内容	索引	MCP 服务
docs.crewai.com	开源框架：智能体、团队、任务、流程、记忆、知识、LLM、工具、CLI、测试、遥测、可观测性，以及 AMP REST API 参考（/inputs、/kickoff、/status、/resume）	https://docs.crewai.com/llms.txt	https://docs.crewai.com/mcp
docs-platform.crewai.com	CrewAI AMP（托管平台）：部署、自动化、触发器、RBAC、密钥、Studio、平台 API	https://docs-platform.crewai.com/llms.txt	https://docs-platform.crewai.com/mcp

旧的 docs.crewai.com/en/enterprise/... 链接会重定向到 docs-platform.crewai.com/platform/en/...：如果匹配页面仍然存在，则跳转到该页面（即使是从 .md URL 访问，也会以 HTML 格式提供）；否则跳转到平台简介。请直接在 docs-platform.crewai.com 上查找平台相关主题；其页面也支持在 URL 后缀添加 .md 来获取 Markdown。

---

何时使用此技能

• 其他技能未涵盖的 CrewAI 功能、参数或行为
• 其他技能指出“如果用户的 crewai version 与该技能核验时使用的版本不同，请使用 ask-docs 重新核验”
• 当前 API 语法、方法签名或配置选项
• 可能在文档中的故障排除说明或注意事项里提及的错误消息
• 较少见的功能：遥测、可观测性集成、CLI 命令、工具库、AMP 平台功能
• 实验性的对话式 Flows（handle_turn()、ConversationConfig、RouterConfig、跟踪、流式传输）

如果有相关的同级技能，请优先使用。 这些技能提供了经过筛选的指导，并已根据 crewai 1.15.x 核验：

主题	技能
项目搭建、选择 LLM.call() / Agent / Crew / Flow	getting-started
Agent 的角色、目标、背景故事、LLM、记忆、知识	design-agent
任务描述、expected_output、防护栏、结构化输出	design-task
当前 1.15.x API 与记忆中的 0.x API 对比	check-crewai-api
Flow 状态、@start / @listen / @router、持久化	build-flow
自定义工具、crewai_tools、供 Agent 使用的 MCP 服务	connect-tools-and-mcp
使用 pytest、crewai test 测试团队和流程	test-crewai-project
部署到 CrewAI AMP	deploy-to-amp
通过 HTTP 调用已部署的团队（/kickoff、/status、webhooks）	call-deployed-crew

对于未涵盖的内容使用 ask-docs，并重新核查同级技能中与版本相关的表格条目。

---

如何查询文档

使用第一个可用的路径。

路径 A：文档 MCP 服务（如果已配置）

docs.crewai.com/mcp 服务无需身份验证。它提供：

工具	用途
search_crew_ai(query, version?, language?)	语义搜索。返回带标题的内容片段，每个片段都包含一个 Link
query_docs_filesystem_crew_ai(command)	只读 Shell（rg、head、ls、tree），用于浏览包含每个页面和 OpenAPI 规范的虚拟目录树
submit_feedback(path, feedback)	向文档团队报告文档问题。除非用户要求，否则不要调用

在 Claude Code 中，这些工具会显示为 mcp__<server-name>__search_crew_ai（例如 mcp__crewai-docs__search_crew_ai）。平台服务的形式相同，名称带有 _platform 后缀：search_crew_ai_platform、query_docs_filesystem_crew_ai_platform。

规则：

• 始终传入 version，并在版本号前加 v，例如 "version": "v1.15.23"。如果不传，结果会混杂 edge 和所有托管版本（从 1.10.0 开始），而且通常旧版本会排在前面。不带 v 的 "1.15.23" 会返回 "No results found"。
• 文件系统的目录结构为 /<version>/<lang>/<path>.mdx（/v1.15.23/en/concepts/knowledge.mdx、/edge/en/...），以及 /openapi/<version>/enterprise-api.en.yaml。rg -l "restore_from_state_id" /v1.15.23/en 可查找提及某个符号的所有页面。
• 搜索结果可能很大（60 KB 以上）。优先使用范围明确的查询，然后对需要的页面运行 head -120 <file>。
• 调用偶尔会失败并提示 "Search failed"。在退回路径 B 之前，重试一次。

路径 B：llms.txt 和 Markdown 页面（无需设置）

1. 获取索引：

   WebFetch: https://docs.crewai.com/llms.txt
   

   索引约有 220 行，内容格式为 - [Title](https://docs.crewai.com/v1.15.23/en/<path>.md): description，位于 ## Docs 下方，后接 ## OpenAPI Specs（AMP REST API YAML）。索引没有分类标题：请按标题或路径前缀查找页面（/en/concepts/、/en/guides/、/en/learn/、/en/tools/、/en/mcp/、/en/observability/、/en/api-reference/）。
2. 使用 .md 后缀获取页面，这会返回干净的 Markdown（约 30 KB），而不是渲染后的 HTML（约 850 KB）：

   WebFetch: https://docs.crewai.com/en/<path>.md
   

   未指定版本的 /en/... URL 会重定向到最新版本（截至 2026-10-01 为 /v1.15.23/en/...）。
3. 对于 AMP 平台相关问题，使用 https://docs-platform.crewai.com/llms.txt，方法相同。该索引按标题组织（Getting Started、Build、Operate、Manage、Integration Docs、Triggers、How-To Guides、API Reference）。

https://docs.crewai.com/llms-full.txt 包含所有页面（约 2 MB）。不要将它加载到上下文中。当索引没有指向正确页面时，请下载并搜索它（curl -s ... | grep -n -A20 "restore_from_state_id"）。

对于对话式 Flows，请直接访问 https://docs.crewai.com/en/guides/flows/conversational-flows.md。将其视为对话式 API 的事实来源（从 crewai.flow 导入；crewai.experimental.conversational 是同一模块的弃用别名），该 API 仍可能发生变化。

路径 C：文档的 GitHub 源码

文档位于公开的 crewAIInc/crewAI 仓库中，路径为 docs/<version>/<lang>/<path>.mdx，例如 https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/v1.15.23/en/concepts/knowledge.mdx 或 .../docs/edge/en/...。旧的 docs/en/... 目录结构已不存在（404）。仅当文档网站无法访问时才使用此方法。

---

将文档版本与用户版本匹配

1. 运行 crewai version（或在 uv 项目中运行 uv run python -c "import crewai; print(crewai.__version__)"）。
2. 阅读对应版本的文档：URL 前缀为 https://docs.crewai.com/v<X.Y.Z>/en/<path>.md，或者在 MCP 服务上设置 version: "v<X.Y.Z>"。从 1.10.0 开始的版本均已托管，此外还有 edge（尚未发布的 main）。只有根目录下存在 llms.txt——/v<X.Y.Z>/llms.txt 会返回 404——因此请从根目录索引中获取路径，并替换版本前缀。
3. 如果用户所用版本未托管，请阅读最近的已托管版本并说明这一点。未托管的版本不会返回 404：/v1.9.0/en/concepts/knowledge.md 会以状态码 200 重定向到主页，因此请检查获取的页面是否就是所请求的页面。

---

对照已安装的软件包检查文档代码片段

文档最适合用来查找现有功能，但不能证明代码片段可以运行。例如，请根据已安装的版本检查 @persist() 之类的装饰器调用形式。

在向用户提供重要代码前：

• 根据已安装的软件包检查签名：python -c "import inspect, crewai.flow.flow as m; print(inspect.signature(m.Flow.kickoff))"。
• 如果不需要 API 密钥，请运行能验证相关说法的最小代码片段。
• 如果文档与软件包不一致，请说明这一点，给出可用的版本，并引用两者。check-crewai-api 技能列出了已知的、与记忆中 API 和当前 API 不同之处。

---

工作流摘要

1. 理解问题——涉及哪个概念、API 或行为？使用的是哪个版本的 crewai？
2. 选择站点——框架（docs.crewai.com）或 AMP 平台（docs-platform.crewai.com）。
3. 查询——使用设置了 version 的 MCP，或者先查 llms.txt，再查对应版本的 .md 页面。
4. 检查——涉及代码时，根据已安装的软件包检查签名或运行小段代码。
5. 回答并引用——提供文档 URL（包含版本前缀），方便用户进一步阅读。

---

示例（于 2026-10-01 对照 crewai 1.15.23 核验）

问题	答案所在位置	文档说明（已核验）
“如何持久化一个 flow？”	/en/guides/flows/mastering-flow-state.md、/en/guides/flows/inputs-id-deprecation.md	使用 crewai.flow.persistence 中的 @persist() 装饰 Flow 类（或某个方法）；状态需要有 id。kickoff(restore_from_state_id=...) 会从已保存的状态分叉，并生成新的 state.id；kickoff(inputs={"id": ...}) 会使用相同的 id 恢复运行，文档已将此方式标记为弃用（1.15.23 不会发出警告）。两种方式均已在本地运行
“POST /kickoff 接受什么参数？”	/en/api-reference/kickoff.md	JSON 请求体必须包含 inputs（字符串值），并可选包含 meta、taskWebhookUrl、stepWebhookUrl、crewWebhookUrl；返回 {"kickoff_id": ...}；使用 bearer token 进行身份验证。已安装的 crewai_tools 中的 InvokeCrewAIAutomationTool 会发送相同的 {"inputs": ...} 请求体。call-deployed-crew 涵盖了完整的客户端
“如何为知识设置嵌入器？”	/en/concepts/knowledge.md	在 Crew（或 Agent）上设置 embedder={"provider": ..., "config": {...}}。默认使用 OpenAI 嵌入，即使大模型不是 OpenAI 的也一样；如果没有 OPENAI_API_KEY，知识 upsert 会记录错误。一个使用 Anthropic 大模型和 {"provider": "onnx", "config": {}} 的 crew 成功根据其知识来源作答

其他适用场景：

用户问题	适用原因
“Crew() 接受哪些参数？”	参考 API 文档，并对照已安装版本的签名进行检查
“如何关闭遥测？”	/en/telemetry.md 介绍收集的内容；test-crewai-project 技能列出了确切的开关值，并已对照已安装的软件包核验
“crewai 支持哪些 CLI 命令？”	查看 /en/concepts/cli.md，然后运行已安装版本的 crewai --help
“有哪些适用于网页抓取的工具？”	查看 /en/tools/ 下的工具库页面
“如何在 AMP 上设置 RBAC？”	查看 docs-platform.crewai.com（/platform/en/features/rbac）
“如何使用 Flow.handle_turn() 构建聊天应用？”	这是实验性的对话式 Flow API；请阅读最新指南

---

设置 Docs MCP 服务（可选）

路径 B 无需任何设置。若要进行结构化搜索，请将服务添加到编码 Agent。

Claude Code（claude mcp add）：

claude mcp add --transport http crewai-docs https://docs.crewai.com/mcp
# --scope project writes .mcp.json in the repo instead; --scope user makes it global
claude mcp list   # shows "crewai-docs: https://docs.crewai.com/mcp (HTTP) - Connected"

它会写入项目作用域的 .mcp.json：

{
  "mcpServers": {
    "crewai-docs": {
      "type": "http",
      "url": "https://docs.crewai.com/mcp"
    }
  }
}

Codex CLI - codex mcp add crewai-docs --url https://docs.crewai.com/mcp，该命令会将以下内容写入 ~/.codex/config.toml（或 $CODEX_HOME/config.toml）：

[mcp_servers.crewai-docs]
url = "https://docs.crewai.com/mcp"

Cursor - 添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以用于所有项目（Cursor MCP 文档）：

{
  "mcpServers": {
    "crewai-docs": { "url": "https://docs.crewai.com/mcp" }
  }
}

其他 Agent：将 https://docs.crewai.com/mcp 添加为远程（可流式传输的 HTTP）MCP 服务。以同样方式添加 https://docs-platform.crewai.com/mcp，即可使用 AMP 平台文档。

---

相关技能

• getting-started — 项目脚手架、抽象选择、Flow 架构
• design-agent - Agent 的 Role-Goal-Backstory、参数调优、工具、记忆和知识
• design-task — 任务描述、expected_output、护栏、结构化输出、依赖项
• check-crewai-api - 当前的 1.15.x API 与助手记忆中的 0.x API 对比
• build-flow - Flow 状态、装饰器、路由、持久化
• connect-tools-and-mcp - 自定义工具、crewai_tools、供 Agent 使用的 MCP 服务
• test-crewai-project - 对 crews 和 flows 进行确定性的 pytest 测试
• deploy-to-amp - 将 crew 或 flow 部署到 CrewAI AMP
• call-deployed-crew - 通过 HTTP 调用已部署的 crew