{
"canonical_name": "crewAIInc/crewAI",
"compilation_id": "pack_89baa2176f104fceab08b699a1a2f6dc",
"created_at": "2026-05-12T16:09:57.431780+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx skills` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx skills",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_0f4dd0fc53a64266ad9f5a5d141b9653"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_01f785c8a4e9e730b2ac2c45de2fa4ec",
"canonical_name": "crewAIInc/crewAI",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/crewAIInc/crewAI",
"slug": "crewai",
"source_packet_id": "phit_170489dc06d140ea9d2e9ebd0d2a0cf8",
"source_validation_id": "dval_a860c3e6178142e3b92fd4a77029872b"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 7097,
"github_stars": 51296,
"one_liner_en": "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.",
"one_liner_zh": "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "crewAI",
"title_zh": "crewAI 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_170489dc06d140ea9d2e9ebd0d2a0cf8",
"page_model": {
"artifacts": {
"artifact_slug": "crewai",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx skills",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/crewAIInc/crewAI#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"结构化数据提取"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_a7c38215ebb04a4fbc6e7c6d2fdb2469 | https://github.com/crewAIInc/crewAI/issues/5708 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] Wrong code in document",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_390380af45524e959d558b160597b38b | https://github.com/crewAIInc/crewAI/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] Wrong code in document",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Enhance the document about @persisit",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_effef000d4cf47a892f17850aa033610 | https://github.com/crewAIInc/crewAI/issues/5372 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] Enhance the document about @persisit",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] GuardrailProvider interface for pre-tool-call authorization",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_858a1a8bead2456289d686ec0d2d802c | https://github.com/crewAIInc/crewAI/issues/4877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "仓库名 `crewai` 与安装入口 `skills` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:710601088 | https://github.com/crewAIInc/crewAI | repo=crewai; install=skills"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dcfa2a852812414a82683392c2888795 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4a1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_0de86b993ffa4d9298726daa189abf49 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.4a1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.5a4",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_6db6cd94b6ef4bffa23da215458565b4 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.5a4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Scans the client database to extract existing policy details.",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_8201c73155314e67801bd0b81ea9820d | https://github.com/crewAIInc/crewAI/issues/5760 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Scans the client database to extract existing policy details.",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:710601088 | https://github.com/crewAIInc/crewAI | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：1.14.5a1",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_c4094bb55c234f1581b9879efd4994c6 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.5a1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.3",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ff4d292bd8984a039527502ef51aed98 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.3",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0e5616e4bf1f47f59e10e83c1849c86a | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：1.14.5a2",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 23 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 298,
"forks": 7097,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 51296,
"open_issues": 289,
"pushed_at": "2026-05-13T00:22:50.000Z"
},
"source_url": "https://github.com/crewAIInc/crewAI",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.",
"title": "crewAI 能力包",
"trial_prompt": "# crewAI - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 crewAI 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：crewAI 简介与快速入门。围绕“crewAI 简介与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构与模块设计。围绕“系统架构与模块设计”模拟一次用户任务，不展示安装或运行结果。\n3. agents：Agent 智能体系统。围绕“Agent 智能体系统”模拟一次用户任务，不展示安装或运行结果。\n4. crews：Crew 智能体团队。围绕“Crew 智能体团队”模拟一次用户任务，不展示安装或运行结果。\n5. flows：Flow 事件驱动工作流。围绕“Flow 事件驱动工作流”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“crewAI 简介与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构与模块设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. agents\n输入：用户提供的“Agent 智能体系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. crews\n输入：用户提供的“Crew 智能体团队”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. flows\n输入：用户提供的“Flow 事件驱动工作流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“crewAI 简介与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构与模块设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / agents：Step 3 必须围绕“Agent 智能体系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / crews：Step 4 必须围绕“Crew 智能体团队”形成一个小中间产物，并等待用户确认。\n- Step 5 / flows：Step 5 必须围绕“Flow 事件驱动工作流”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/crewAIInc/crewAI\n- https://github.com/crewAIInc/crewAI#readme\n- lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md\n- lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md\n- lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md\n- README.md\n- lib/crewai/README.md\n- lib/cli/src/crewai_cli/create_crew.py\n- lib/cli/src/crewai_cli/create_flow.py\n- lib/crewai/pyproject.toml\n- lib/crewai/src/crewai/__init__.py\n- lib/crewai/src/crewai/crew.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 crewAI 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Question: integration path for Agent Threat Rules detection in crewai/se（https://github.com/crewAIInc/crewAI/issues/5763）；github/github_issue: [FEATURE] Implement Process.consensual with a pluggable ConsensusEngine（https://github.com/crewAIInc/crewAI/issues/5708）；github/github_issue: [FEATURE] GuardrailProvider interface for pre-tool-call authorization（https://github.com/crewAIInc/crewAI/issues/4877）；github/github_issue: Security: OWASP Agent Memory Guard – protect CrewAI agents from memory p（https://github.com/crewAIInc/crewAI/issues/5762）；github/github_issue: Scans the client database to extract existing policy details.（https://github.com/crewAIInc/crewAI/issues/5760）；github/github_issue: Security: Request to enable Private Vulnerability Reporting / coordinate（https://github.com/crewAIInc/crewAI/issues/5728）；github/github_issue: Question: integration path for Agent Threat Rules detection in crewai/se（https://github.com/crewAIInc/crewAI/issues/5763）；github/github_issue: Security: OWASP Agent Memory Guard – protect CrewAI agents from memory p（https://github.com/crewAIInc/crewAI/issues/5762）；github/github_issue: Scans the client database to extract existing policy details.（https://github.com/crewAIInc/crewAI/issues/5760）；github/github_issue: [FEATURE] Enhance the document about @persisit（https://github.com/crewAIInc/crewAI/issues/5372）；github/github_issue: [BUG] Wrong code in document（https://github.com/crewAIInc/crewAI/issues/5378）；github/github_issue: [FEATURE] Tool to add input_files（https://github.com/crewAIInc/crewAI/issues/5758）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Question: integration path for Agent Threat Rules detection in crewai/se",
"url": "https://github.com/crewAIInc/crewAI/issues/5763"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine",
"url": "https://github.com/crewAIInc/crewAI/issues/5708"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] GuardrailProvider interface for pre-tool-call authorization",
"url": "https://github.com/crewAIInc/crewAI/issues/4877"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security: OWASP Agent Memory Guard – protect CrewAI agents from memory p",
"url": "https://github.com/crewAIInc/crewAI/issues/5762"
},
{
"kind": "github_issue",
"source": "github",
"title": "Scans the client database to extract existing policy details.",
"url": "https://github.com/crewAIInc/crewAI/issues/5760"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security: Request to enable Private Vulnerability Reporting / coordinate",
"url": "https://github.com/crewAIInc/crewAI/issues/5728"
},
{
"kind": "github_issue",
"source": "github",
"title": "Question: integration path for Agent Threat Rules detection in crewai/se",
"url": "https://github.com/crewAIInc/crewAI/issues/5763"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security: OWASP Agent Memory Guard – protect CrewAI agents from memory p",
"url": "https://github.com/crewAIInc/crewAI/issues/5762"
},
{
"kind": "github_issue",
"source": "github",
"title": "Scans the client database to extract existing policy details.",
"url": "https://github.com/crewAIInc/crewAI/issues/5760"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] Enhance the document about @persisit",
"url": "https://github.com/crewAIInc/crewAI/issues/5372"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Wrong code in document",
"url": "https://github.com/crewAIInc/crewAI/issues/5378"
},
{
"kind": "github_issue",
"source": "github",
"title": "[FEATURE] Tool to add input_files",
"url": "https://github.com/crewAIInc/crewAI/issues/5758"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.",
"effort": "安装已验证",
"forks": 7057,
"icon": "code",
"name": "crewAI 能力包",
"risk": "可发布",
"slug": "crewai",
"stars": 51055,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"结构化数据提取"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/crewAIInc/crewAI 项目说明书\n\n生成时间：2026-05-11 07:12:58 UTC\n\n## 目录\n\n- [crewAI 简介与快速入门](#introduction)\n- [系统架构与模块设计](#architecture)\n- [Agent 智能体系统](#agents)\n- [Crew 智能体团队](#crews)\n- [Flow 事件驱动工作流](#flows)\n- [Task 任务系统](#tasks)\n- [LLM 集成与提供者](#llm-integration)\n- [工具系统与 MCP 集成](#tools)\n- [MCP 与 A2A 协议](#mcp-a2a)\n- [记忆与知识管理系统](#memory-knowledge)\n\n\n\n## crewAI 简介与快速入门\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#architecture), [Agent 智能体系统](#agents), [Crew 智能体团队](#crews)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/crewAIInc/crewAI/blob/main/README.md)\n- [lib/crewai/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/README.md)\n- [lib/cli/src/crewai_cli/templates/AGENTS.md](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/AGENTS.md)\n- [lib/crewai-tools/src/crewai_tools/tools/rag/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/rag/README.md)\n- [lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md)\n- [lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md)\n \n\n# crewAI 简介与快速入门\n\n## 什么是 crewAI？\n\ncrewAI 是一个先进的多代理自动化框架，旨在释放多代理自动化的真正潜力，提供最佳的**速度**与**智能组合**。该框架允许开发者创建能够协同工作的 AI 代理（Agent），使这些代理像团队一样处理复杂任务。\n\n资料来源：[README.md:1-15]()\n\n### 核心概念\n\ncrewAI 的架构围绕以下几个核心概念构建：\n\n| 概念 | 描述 |\n|------|------|\n| **Agent（代理）** | 具有特定角色、目标和背景故事的 AI 实体，可以拥有自己的工具和记忆 |\n| **Task（任务）** | 需要代理完成的具体工作单元，包含描述和预期输出 |\n| **Crew（团队）** | 由多个代理组成的协作单元，按照定义的流程协同工作 |\n| **Process（流程）** | 定义代理之间协作方式的工作流程机制 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:30-50]()\n\n### crewAI 架构图\n\n```mermaid\ngraph TD\n A[用户] --> B[Crew 团队]\n B --> C[Agent 1: Researcher]\n B --> D[Agent 2: Writer]\n B --> E[Agent N: ...]\n C --> F[Task 1: 研究任务]\n D --> G[Task 2: 写作任务]\n F --> H[结果输出]\n G --> H\n```\n\n## 安装与配置\n\n### 环境要求\n\ncrewAI 项目对环境有以下要求：\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | >=3.10, <3.14 |\n| 包管理工具 | 推荐使用 [UV](https://docs.astral.sh/uv/) |\n| 可选依赖 | crewai[tools] 用于工具支持 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:8-10]()\n\n### 安装步骤\n\n1. **安装 UV 包管理器**（如果尚未安装）：\n\n```bash\npip install uv\n```\n\n2. **创建 crewAI 项目**：\n\n```bash\ncrewai create crew --skip_provider\n```\n\n3. **安装项目依赖**：\n\n```bash\ncrewai install\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:15-22]()\n\n## 创建第一个 Crew\n\n### 项目结构\n\ncrewAI 项目通常包含以下结构：\n\n| 文件/目录 | 用途 |\n|-----------|------|\n| `src//crew.py` | Crew 类定义，包含代理和任务配置 |\n| `config/agents.yaml` | 代理的配置文件 |\n| `config/tasks.yaml` | 任务的配置文件 |\n| `src//main.py` | 项目入口文件 |\n| `pyproject.toml` | 项目依赖配置 |\n\n### 定义 Agent\n\ncrewAI 使用 `@agent` 装饰器来定义代理，代理可以从 YAML 配置文件中读取配置：\n\n```python\nfrom crewai import Agent\nfrom crewai.project import CrewBase, agent\nfrom crewai_tools import SerperDevTool\n\n@CrewBase\nclass ResearchCrew():\n \"\"\"研究团队\"\"\"\n\n agents_config = \"config/agents.yaml\"\n tasks_config = \"config/tasks.yaml\"\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config[\"researcher\"],\n tools=[SerperDevTool()],\n verbose=True,\n )\n\n @agent\n def writer(self) -> Agent:\n return Agent(\n config=self.agents_config[\"writer\"],\n verbose=True,\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:35-60]()\n\n### 定义 Task\n\n任务定义使用 `@task` 装饰器：\n\n```python\nfrom crewai import Task\nfrom crewai.project import CrewBase, task\n\n@CrewBase\nclass ResearchCrew():\n # ... agent 定义 ...\n\n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config[\"research_task\"],\n )\n\n @task\n def writing_task(self) -> Task:\n return Task(\n config=self.tasks_config[\"writing_task\"],\n output_file='output/article.md'\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:65-80]()\n\n### YAML 配置示例\n\n**agents.yaml 示例**：\n\n```yaml\nresearcher:\n role: Senior Research Analyst\n goal: Uncover groundbreaking technologies in {topic}\n backstory: |\n You are a Senior Research Analyst at a leading tech think tank.\n Your expertise lies in identifying emerging trends and technologies.\n verbose: true\n\nwriter:\n role: Content Writer\n goal: Write engaging article about {topic}\n backstory: |\n You are a skilled content writer known for your ability to explain complex topics.\n verbose: true\n```\n\n**tasks.yaml 示例**：\n\n```yaml\nresearch_task:\n description: >\n Conduct a thorough research on {topic}.\n Identify key trends, notable companies, and potential impact.\n expected_output: >\n A comprehensive research report with main topics, each with full section of information.\n agent: researcher\n\nwriting_task:\n description: >\n Write an article based on the research findings about {topic}.\n expected_output: >\n A polished 4-paragraph article formatted in markdown.\n agent: writer\n output_file: output/article.md\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:5-30]()\n\n## 集成工具生态\n\ncrewAI 支持丰富的工具生态，以下是常用工具的集成方式：\n\n### RagTool - 知识库检索工具\n\nRagTool 支持从多种来源加载内容构建知识库：\n\n```python\nfrom crewai_tools.tools.rag_tool import RagTool\n\n# 从文件加载\nrag_tool = RagTool().from_file('path/to/your/file.txt')\n\n# 从目录加载\nrag_tool = RagTool().from_directory('path/to/your/directory')\n\n# 从网页加载\nrag_tool = RagTool().from_web_page('https://example.com')\n```\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/rag/README.md:25-35]()\n\n### FileWriterTool - 文件写入工具\n\nFileWriterTool 简化了向文件写入内容的过程，支持创建目录：\n\n```python\nfrom crewai_tools import FileWriterTool\n\n# 初始化工具\nfile_writer_tool = FileWriterTool()\n\n# 写入内容到指定目录\nresult = file_writer_tool._run(\n 'example.txt', \n 'This is a test content.', \n 'test_directory'\n)\n```\n\n| 参数 | 说明 |\n|------|------|\n| filename | 要创建或覆盖的文件名 |\n| content | 要写入的内容 |\n| directory | 文件所在目录路径（可选，默认为当前目录）|\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md:20-35]()\n\n### TavilyExtractorTool - 网页内容提取\n\nTavilyExtractorTool 允许从网页提取结构化内容：\n\n```python\nfrom crewai import Agent, Task, Crew\nfrom crewai_tools import TavilyExtractorTool\n\n# 初始化工具\ntavily_tool = TavilyExtractorTool()\n\n# 创建使用该工具的代理\nextractor_agent = Agent(\n role='Web Content Extractor',\n goal='Extract key information from specified web pages',\n backstory='You are an expert at extracting content from websites.',\n tools=[tavily_tool],\n verbose=True\n)\n```\n\n| 参数 | 说明 |\n|------|------|\n| 必需 | Tavily API Key（通过 TAVILY_API_KEY 环境变量设置） |\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md:15-40]()\n\n### 工具安装方式\n\n```bash\n# 使用 UV 安装 crewai 及其工具\nuv add 'crewai[tools]' tavily-python\n\n# 或使用 pip\npip install 'crewai[tools]' contextual-client\n```\n\n## 常用命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `crewai create crew ` | 创建新的 crew 项目 |\n| `crewai create flow ` | 创建新的 flow 项目 |\n| `crewai run` | 运行 crew 或 flow |\n| `crewai test` | 测试 crew（默认 2 次迭代）|\n| `crewai test -n 5 -m gpt-4o` | 自定义测试迭代次数和模型 |\n| `crewai train -n 5 -f training.json` | 训练 crew |\n| `crewai reset-memories -a` | 重置所有记忆 |\n| `crewai log-tasks-outputs` | 显示最新任务输出 |\n| `crewai replay -t ` | 从特定任务重新播放 |\n| `crewai tool publish ` | 发布自定义工具 |\n| `crewai tool install ` | 安装社区工具 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:25-40]()\n\n## Crew 工作流程\n\n```mermaid\ngraph LR\n A[定义 Agents] --> B[定义 Tasks]\n B --> C[配置 Crew]\n C --> D[kickoff]\n D --> E{Process 执行}\n E -->|顺序| F[Sequential]\n E -->|层级| G[Hierarchical]\n E -->|协作| H[Collaborative]\n F --> I[结果聚合]\n G --> I\n H --> I\n I --> J[输出]\n```\n\n## 下一步\n\n- 阅读 [Agent 设计指南](/design-agent) 学习如何配置代理\n- 阅读 [Task 设计指南](/design-task) 学习如何编写任务描述\n- 探索 [官方文档](https://docs.crewai.com) 了解更多高级功能\n\n---\n\n\n\n## 系统架构与模块设计\n\n### 相关页面\n\n相关主题：[crewAI 简介与快速入门](#introduction), [Agent 智能体系统](#agents), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/pyproject.toml)\n- [lib/crewai/src/crewai/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/__init__.py)\n- [lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n- [lib/crewai/src/crewai/flow/flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow.py)\n- [lib/cli/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/pyproject.toml)\n- [lib/crewai-tools/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/pyproject.toml)\n \n\n# 系统架构与模块设计\n\n## 概述\n\ncrewAI 是一个多智能体协作框架，旨在通过编排多个 AI Agent 来完成复杂任务。该框架采用模块化架构设计，将核心功能分离到独立模块中，实现关注点分离（Separation of Concerns）原则。\n\n核心设计理念：\n\n- **模块化**：各功能组件独立封装，便于维护和扩展\n- **可组合性**：通过 Crew（团队）概念组合多个 Agent 协同工作\n- **流程控制**：提供 Flow 机制实现任务编排和状态管理\n- **工具扩展**：支持自定义工具扩展 Agent 能力\n\n资料来源：[lib/crewai/src/crewai/__init__.py]()\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n CLI[CLI 界面]\n API[API 接口]\n end\n\n subgraph \"核心层\"\n Crew[Crew 编排器]\n Agent[Agent 智能体]\n Task[Task 任务]\n Flow[Flow 流程]\n end\n\n subgraph \"工具层\"\n Tools[Tools 工具集]\n CustomTools[自定义工具]\n end\n\n subgraph \"底层服务\"\n LLM[大语言模型]\n Memory[记忆系统]\n end\n\n CLI --> Crew\n API --> Crew\n Crew --> Agent\n Crew --> Task\n Flow --> Crew\n Agent --> Tools\n Agent --> LLM\n Agent --> Memory\n```\n\n## 项目结构\n\n### 代码库组织\n\n| 目录 | 说明 | 配置文件 |\n|------|------|----------|\n| `lib/crewai/` | 核心框架代码 | `pyproject.toml` |\n| `lib/cli/` | 命令行工具 | `pyproject.toml` |\n| `lib/crewai-tools/` | 工具扩展包 | `pyproject.toml` |\n\n### 核心模块依赖关系\n\n```mermaid\ngraph LR\n A[crewai core] --> B[Agent]\n A --> C[Crew]\n A --> D[Task]\n A --> E[Flow]\n A --> F[Tools]\n B --> D\n C --> B\n C --> D\n F --> B\n```\n\n## 核心模块详解\n\n### Crew 编排器\n\n`Crew` 是 crewAI 的核心编排组件，负责管理多个 Agent 和 Task 的协作执行。\n\n主要职责：\n\n- 初始化和管理 Agent 列表\n- 协调任务执行顺序\n- 管理任务结果汇总\n- 处理异常和重试逻辑\n\n资料来源：[lib/crewai/src/crewai/crew.py]()\n\n```python\nclass Crew:\n def __init__(\n self,\n agents: List[Agent],\n tasks: List[Task],\n process: Process = Process.hierarchical,\n verbose: bool = False,\n ):\n self.agents = agents\n self.tasks = tasks\n self.process = process\n self.verbose = verbose\n```\n\n### Agent 智能体\n\n`Agent` 代表一个具有特定角色的 AI 实体，每个 Agent 拥有：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `role` | str | 角色名称 |\n| `goal` | str | 目标描述 |\n| `backstory` | str | 背景故事 |\n| `tools` | List[BaseTool] | 可用工具列表 |\n| `llm` | Optional[LLM] | 语言模型配置 |\n\n### Task 任务\n\n`Task` 定义了具体的工作单元，与特定 Agent 关联执行。\n\n### Flow 流程控制\n\n`Flow` 模块提供了高级的流程编排能力，支持状态管理和工作流控制。\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py]()\n\n```python\nclass Flow:\n def __init__(self):\n self.state: Dict[str, Any] = {}\n \n def kickoff(self):\n \"\"\"启动流程执行\"\"\"\n pass\n \n def crew(self):\n \"\"\"注册 Crew 到 Flow\"\"\"\n pass\n```\n\n## 工具系统架构\n\n### 工具层设计\n\n```mermaid\ngraph TD\n Tools[Tools 基类] --> FileTools[文件工具]\n Tools --> SearchTools[搜索工具]\n Tools --> APITools[API 工具]\n Tools --> BrowserTools[浏览器工具]\n \n FileTools --> ReadTool[读取工具]\n FileTools --> WriteTool[写入工具]\n```\n\n### 工具注册机制\n\ncrewAI 采用基于装饰器的工具注册模式，工具继承 `BaseTool` 基类并实现 `_run` 方法。\n\n资料来源：[lib/crewai-tools/pyproject.toml]()\n\n## CLI 模块设计\n\nCLI 模块提供命令行交互入口，支持项目管理、任务创建、执行监控等功能。\n\n| 命令 | 功能 |\n|------|------|\n| `crewai create` | 创建新项目 |\n| `crewai run` | 运行 Crew |\n| `crewai task` | 任务管理 |\n| `crewai agent` | Agent 管理 |\n\n资料来源：[lib/cli/pyproject.toml]()\n\n## 包依赖配置\n\n### 核心包依赖\n\n```toml\n# lib/crewai/pyproject.toml\n[project]\nname = \"crewai\"\nversion = \"0.1.0\"\ndependencies = [\n \"pydantic>=2.0.0\",\n \"langchain-core>=0.1.0\",\n \"langchain-openai>=0.0.5\",\n]\n```\n\n### 工具包依赖\n\n```toml\n# lib/crewai-tools/pyproject.toml\n[project]\nname = \"crewai-tools\"\ndependencies = [\n \"crewai>=0.1.0\",\n \"langchain-core>=0.1.0\",\n]\n```\n\n## 执行流程\n\n### Crew 执行流程\n\n```mermaid\ngraph TD\n A[初始化 Crew] --> B[加载 Agents]\n B --> C[加载 Tasks]\n C --> D{执行模式}\n D -->|顺序| E[按序执行 Task]\n D -->|层级| F[Manager Agent 分配]\n E --> G[汇总结果]\n F --> G\n G --> H[返回最终输出]\n```\n\n### Flow 与 Crew 集成\n\n```mermaid\ngraph LR\n A[Flow.kickoff] --> B[初始化 State]\n B --> C[执行 crew]\n C --> D[Agent 执行任务]\n D --> E[更新 State]\n E --> F{是否完成}\n F -->|否| D\n F -->|是| G[返回结果]\n```\n\n## 配置选项\n\n### Crew 配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `process` | `Process.hierarchical` | 执行流程模式 |\n| `verbose` | `False` | 是否输出详细日志 |\n| `memory` | `True` | 是否启用记忆功能 |\n| `max_rpm` | `None` | 每分钟最大请求数 |\n| `share_crew` | `False` | 是否共享 Crew 实例 |\n\n### Agent 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `role` | str | Agent 角色定义 |\n| `goal` | str | Agent 目标 |\n| `backstory` | str | Agent 背景 |\n| `allow_delegation` | bool | 是否允许委托任务 |\n| `tools` | List[BaseTool] | 绑定工具 |\n\n## 模块间通信\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Crew\n participant Agent\n participant Tools\n participant LLM\n \n User->>CLI: 发起请求\n CLI->>Crew: 创建 Crew 实例\n Crew->>Agent: 分配任务\n Agent->>Tools: 调用工具\n Tools-->>Agent: 返回结果\n Agent->>LLM: 请求推理\n LLM-->>Agent: 返回响应\n Agent-->>Crew: 汇报结果\n Crew-->>CLI: 汇总输出\n CLI-->>User: 显示结果\n```\n\n## 扩展机制\n\n### 自定义工具开发\n\n开发者可通过继承 `BaseTool` 类创建自定义工具：\n\n```python\nfrom crewai.tools import BaseTool\n\nclass MyCustomTool(BaseTool):\n name: str = \"my_custom_tool\"\n description: str = \"工具描述\"\n \n def _run(self, *args, **kwargs):\n # 工具实现逻辑\n return result\n```\n\n### Flow 自定义\n\n通过继承 `Flow` 类并重写钩子方法实现自定义流程：\n\n| 方法 | 说明 |\n|------|------|\n| `before_kickoff()` | 启动前执行 |\n| `after_kickoff()` | 完成后执行 |\n| `crew()` | 注册 Crew 实例 |\n\n## 版本与依赖管理\n\ncrewAI 采用 PEP 440 版本规范，核心包与扩展包版本需保持兼容：\n\n| 包名 | 最低版本 | 用途 |\n|------|----------|------|\n| `pydantic` | ≥2.0.0 | 数据验证 |\n| `langchain-core` | ≥0.1.0 | LLM 接口抽象 |\n| `langchain-openai` | ≥0.0.5 | OpenAI 集成 |\n\n资料来源：[lib/crewai/pyproject.toml](), [lib/crewai-tools/pyproject.toml](), [lib/cli/pyproject.toml]()\n\n---\n\n\n\n## Agent 智能体系统\n\n### 相关页面\n\n相关主题：[Crew 智能体团队](#crews), [Task 任务系统](#tasks), [LLM 集成与提供者](#llm-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/agents/agent_builder/base_agent.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/agent_builder/base_agent.py)\n- [lib/crewai/src/crewai/agent/core.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agent/core.py)\n- [lib/crewai/src/crewai/agents/crew_agent_executor.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/crew_agent_executor.py)\n- [lib/crewai/src/crewai/agents/step_executor.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/step_executor.py)\n- [lib/crewai/src/crewai/tools/agent_tools/agent_tools.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/agent_tools/agent_tools.py)\n- [lib/cli/src/crewai_cli/templates/crew/config/agents.yaml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/config/agents.yaml)\n \n\n# Agent 智能体系统\n\n## 概述\n\nAgent（智能体）是 CrewAI 框架的核心构建单元，代表能够自主执行任务的人工智能角色。每个 Agent 具有明确的角色（role）、目标（goal）和背景故事（backstory），并可配备各种工具（Tools）来扩展其能力。\n\nAgent 系统的主要职责包括：\n\n- 理解并执行分配的任务\n- 与其他 Agent 协作完成复杂目标\n- 访问和利用各种工具获取信息或执行操作\n- 通过大语言模型（LLM）进行推理和决策\n\n## Agent 核心组件\n\n### 架构概览\n\n```mermaid\ngraph TD\n A[Agent] --> B[BaseAgent]\n A --> C[Agent Config]\n B --> D[CrewAgentExecutor]\n B --> E[StepExecutor]\n D --> F[LLM]\n D --> G[Tools]\n E --> H[Memory]\n E --> I[Guardrails]\n```\n\n### 核心类结构\n\n| 类名 | 文件位置 | 职责描述 |\n|------|----------|----------|\n| `BaseAgent` | `lib/crewai/src/crewai/agents/agent_builder/base_agent.py` | Agent 的基础抽象类，定义通用接口和属性 |\n| `Agent` | `lib/crewai/src/crewai/agent/core.py` | Agent 的核心实现类 |\n| `CrewAgentExecutor` | `lib/crewai/src/crewai/agents/crew_agent_executor.py` | Agent 执行器，负责运行 Agent 逻辑 |\n| `StepExecutor` | `lib/crewai/src/crewai/agents/step_executor.py` | 单步执行器，处理 Agent 的单个执行步骤 |\n\n## Agent 配置\n\n### YAML 配置格式\n\nAgent 通过 `agents.yaml` 配置文件定义，支持以下核心属性：\n\n```yaml\n# lib/cli/src/crewai_cli/templates/crew/config/agents.yaml\nresearcher:\n role: >\n {topic} Senior Data Researcher\n goal: >\n Uncover cutting-edge developments in {topic}\n backstory: >\n You're a seasoned researcher with a knack for uncovering the latest\n developments in {topic}. Known for your ability to find the most relevant\n information and present it in a clear and concise manner.\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `role` | string | 是 | Agent 的角色名称，如\"研究员\"、\"分析师\"等 |\n| `goal` | string | 是 | Agent 的核心目标，描述其需要达成的目的 |\n| `backstory` | string | 是 | Agent 的背景故事，定义其经验和专业领域 |\n| `llm` | dict | 否 | 大语言模型配置，覆盖默认设置 |\n| `tools` | list | 否 | 分配给 Agent 的工具列表 |\n| `verbose` | bool | 否 | 是否输出详细日志，默认 false |\n| `allow_delegation` | bool | 否 | 是否允许委托任务给其他 Agent |\n\n## Agent 创建与使用\n\n### 使用装饰器创建 Agent\n\nCrewAI 推荐使用 `@agent` 装饰器在 Crew 类中定义 Agent：\n\n```python\n# lib/cli/src/crewai_cli/templates/crew/crew.py\nfrom crewai import Agent\nfrom crewai.project import CrewBase, agent\n\n@CrewBase\nclass LatestAiDevelopmentCrew():\n agents: List[BaseAgent]\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config['researcher'],\n verbose=True,\n tools=[SerperDevTool()]\n )\n```\n\n### 直接实例化 Agent\n\n也可以直接实例化 Agent 类：\n\n```python\nfrom crewai import Agent\n\nresearcher = Agent(\n role=\"Information Researcher\",\n goal=\"Fetch relevant results from search engines.\",\n backstory=\"An expert in online information retrieval...\",\n tools=[search_tool],\n verbose=True\n)\n```\n\n## Agent 工具系统\n\n### 内置工具\n\nAgent 可使用多种内置工具来扩展能力：\n\n| 工具名称 | 功能描述 | 资料来源 |\n|----------|----------|----------|\n| `SerperDevTool` | 网络搜索工具 | README.md |\n| `LinkupSearchTool` | Linkup 搜索服务 | `lib/crewai-tools/src/crewai_tools/tools/linkup/README.md` |\n| `TavilyExtractorTool` | 网页内容提取 | `lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md` |\n| `ApifyActorsTool` | Apify 自动化工具 | `lib/crewai-tools/src/crewai_tools/tools/apify_actors_tool/README.md` |\n| `CodeDocsSearchTool` | 代码文档搜索 | `lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md` |\n\n### 工具配置示例\n\n```python\n# 自定义 LLM 和 embeddings 配置\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n## Agent 执行流程\n\n### 执行器工作流程\n\n```mermaid\ngraph TD\n A[Task 任务] --> B[CrewAgentExecutor]\n B --> C{是否需要工具?}\n C -->|是| D[调用 Tool]\n C -->|否| E[直接 LLM 响应]\n D --> F[处理 Tool 结果]\n E --> G[StepExecutor 单步执行]\n F --> G\n G --> H[更新 Memory]\n H --> I[返回结果]\n```\n\n### 单步执行机制\n\nStepExecutor 负责处理 Agent 的单个执行步骤，包括：\n\n1. 解析当前任务上下文\n2. 生成 LLM 调用\n3. 处理工具调用请求\n4. 解析执行结果\n5. 更新 Agent 记忆\n\n## Agent 与 Crew 协作\n\n### Crew 组合架构\n\n```mermaid\ngraph LR\n A[Crew] --> B[Agent 1]\n A --> C[Agent 2]\n A --> D[Agent N]\n B --> E[Task 1]\n C --> F[Task 2]\n D --> G[Task N]\n E --> H[Process 流程]\n F --> H\n G --> H\n```\n\n### 任务委派\n\nAgent 可以将任务委派给其他 Agent：\n\n```python\n@agent\ndef manager(self) -> Agent:\n return Agent(\n config=self.agents_config['manager'],\n verbose=True,\n allow_delegation=True # 允许委派任务\n )\n```\n\n## 高级配置\n\n### 内存系统\n\nAgent 配备内存系统以维护对话上下文：\n\n- **短期记忆**：当前会话内的上下文信息\n- **长期记忆**：跨会话积累的知识\n- **实体记忆**：关于特定实体的详细信息\n\n### Guardrails 安全机制\n\nAgent 支持配置安全护栏（Guardrails），确保输出符合预期：\n\n```python\nfrom crewai import Agent\nfrom crewai.agents import Guardrail\n\nagent = Agent(\n role=\"Data Analyst\",\n goal=\"Analyze data accurately\",\n backstory=\"Expert in data analysis\",\n guardrails=[custom_guardrail]\n)\n```\n\n## 环境配置\n\n### 必要环境变量\n\n运行 Agent 前需要配置以下环境变量：\n\n| 变量名 | 描述 | 必需 |\n|--------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 是（使用 OpenAI 时） |\n| `SERPER_API_KEY` | Serper.dev API 密钥 | 使用搜索工具时 |\n| `TAVILY_API_KEY` | Tavily API 密钥 | 使用 Tavily 工具时 |\n| `OTEL_SDK_DISABLED` | 禁用遥测 | 否 |\n\n### 依赖安装\n\n```bash\n# 使用 uv 管理依赖\nuv sync\n\n# 或使用 crewai CLI\ncrewai install\n```\n\n## 最佳实践\n\n### 1. 角色设计\n\n- 角色名称应清晰表达 Agent 的专业领域\n- 目标描述应具体、可衡量\n- 背景故事应与任务需求匹配\n\n### 2. 工具选择\n\n- 只分配与任务相关的工具\n- 避免过多工具导致决策混乱\n- 正确配置工具 API 密钥\n\n### 3. 流程编排\n\n- sequential（顺序）流程：任务有明确依赖关系\n- hierarchical（层级）流程：需要管理角色协调\n\n## 测试与调试\n\n### 运行测试\n\n```bash\n# 默认测试（2 次迭代，使用 gpt-4o-mini）\ncrewai test\n\n# 自定义测试\ncrewai test -n 5 -m gpt-4o\n```\n\n### 查看输出\n\n```bash\n# 查看最新任务输出\ncrewai log-tasks-outputs\n\n# 重放特定任务\ncrewai replay -t \n```\n\n## 总结\n\nAgent 智能体系统是 CrewAI 框架的核心，通过结合角色定义、目标设定、工具扩展和记忆机制，实现了灵活且强大的多智能体协作能力。开发者可以通过 YAML 配置或 Python 代码定义 Agent，并将其组合成 Crew 来完成复杂任务。\n\n## 相关资源\n\n- [官方文档](https://docs.crewai.com)\n- [GitHub 仓库](https://github.com/crewAIInc/crewAI)\n- [Discord 社区](https://discord.gg/X4JWnZnxPb)\n\n---\n\n\n\n## Crew 智能体团队\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents), [Task 任务系统](#tasks), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n- [lib/crewai/src/crewai/process.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/process.py)\n- [lib/crewai/src/crewai/crews/crew_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crews/crew_output.py)\n- [lib/crewai/src/crewai/agents/tools_handler.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/tools_handler.py)\n- [lib/cli/src/crewai_cli/templates/crew/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/crew.py)\n \n\n# Crew 智能体团队\n\n## 概述\n\nCrew 是 CrewAI 框架中的核心编排单元，用于组织和管理多个 AI 智能体（Agent）协同完成复杂任务。Crew 本质上是一个任务编排容器，它将多个具有特定角色的智能体组合在一起，通过预定义的流程模式协调它们之间的工作。\n\nCrew 的设计理念是将自治性（Autonomy）和精确性（Precision）相结合，使得开发者能够灵活地构建从简单任务到企业级自动化的各类应用场景。\n\n## 核心架构\n\n### Crew 与 Agent 的关系\n\n```mermaid\ngraph TD\n A[Crew 智能体团队] --> B[Agent 1: 研究员]\n A --> C[Agent 2: 分析员]\n A --> D[Agent 3: 报告员]\n A --> E[Task 任务列表]\n A --> F[Process 进程模式]\n B -.-> E\n C -.-> E\n D -.-> E\n E -.-> F\n```\n\n一个 Crew 由以下核心元素组成：\n\n| 组件 | 描述 | 类型 |\n|------|------|------|\n| agents | 智能体列表 | List[BaseAgent] |\n| tasks | 任务列表 | List[Task] |\n| process | 进程模式 | Process Enum |\n| verbose | 详细输出控制 | bool |\n| memory | 记忆系统 | bool |\n\n## Crew 的创建方式\n\n### 使用装饰器模式（CrewBase）\n\nCrewAI 推荐使用 `@CrewBase` 装饰器来定义 Crew 类，这种方式将配置与代码分离，便于维护和修改。\n\n```python\nfrom crewai import Agent, Crew, Process, Task\nfrom crewai.project import CrewBase, agent, crew, task\nfrom typing import List\n\n@CrewBase\nclass MyCrew():\n \"\"\"我的智能体团队\"\"\"\n agents: List[BaseAgent]\n tasks: List[Task]\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config['researcher'],\n verbose=True\n )\n\n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n )\n\n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/crew/crew.py:1-45]()\n\n### 直接实例化\n\n也可以不使用装饰器，直接通过代码创建 Crew：\n\n```python\nfrom crewai import Agent, Crew, Process, Task\n\nresearcher = Agent(role=\"研究员\", goal=\"研究最新AI发展\", backstory=\"...\")\ntask1 = Task(description=\"研究任务\", agent=researcher)\n\ncrew = Crew(\n agents=[researcher],\n tasks=[task1],\n process=Process.sequential,\n verbose=True\n)\n```\n\n## 进程模式（Process）\n\nCrew 支持两种主要的进程模式，用于控制智能体执行任务的顺序和方式。\n\n### 顺序执行（Sequential）\n\n顺序执行模式按照任务列表的定义顺序依次执行任务，每个任务完成后才启动下一个任务。\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n)\n```\n\n### 分层执行（Hierarchical）\n\n分层执行模式会自动分配一个管理员角色，负责协调和验证任务的规划与执行结果。\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.hierarchical,\n verbose=True,\n manager_agent=manager # 可选：自定义管理员\n)\n```\n\n### 进程模式对比\n\n| 模式 | 说明 | 适用场景 | 管理员 |\n|------|------|----------|--------|\n| Sequential | 按顺序执行任务 | 线性工作流 | 无 |\n| Hierarchical | 动态委托和验证 | 需要协调的复杂任务 | 自动或自定义 |\n\n资料来源：[lib/crewai/src/crewai/process.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/process.py)\n\n## Crew 配置参数\n\n### 主要参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| agents | List[BaseAgent] | 是 | - | 团队成员列表 |\n| tasks | List[Task] | 是 | - | 任务列表 |\n| process | Process | 否 | Process.sequential | 进程模式 |\n| verbose | bool | 否 | False | 是否输出详细日志 |\n| memory | bool | 否 | False | 启用记忆系统 |\n| max_rpm | int | 否 | None | 最大请求速率限制 |\n| language | str | 否 | en | 输出语言 |\n| config | dict | 否 | None | 自定义配置 |\n\n### 完整配置示例\n\n```python\ncrew = Crew(\n agents=[researcher, analyst, writer],\n tasks=[task1, task2, task3],\n process=Process.sequential,\n verbose=True,\n memory=True,\n max_rpm=60,\n respect_context_window=True,\n config={\n \"workflow\": \"research_report\",\n \"output_format\": \"markdown\"\n }\n)\n```\n\n资料来源：[lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n\n## Crew 的生命周期\n\n```mermaid\ngraph TD\n A[创建 Crew 实例] --> B[初始化 Agents 和 Tasks]\n B --> C[调用 kickoff 方法]\n C --> D{进程模式}\n D -->|Sequential| E[按顺序执行任务]\n D -->|Hierarchical| F[管理员协调任务]\n E --> G[收集任务输出]\n F --> G\n G --> H[生成 CrewOutput]\n H --> I[返回最终结果]\n```\n\n### 执行入口\n\nCrew 的主入口方法是 `kickoff()`，它接收输入参数并启动整个团队的工作：\n\n```python\ninputs = {\n 'topic': 'AI Agents',\n 'format': 'markdown'\n}\n\nresult = my_crew.kickoff(inputs=inputs)\n```\n\n### 输出处理\n\nCrew 执行完成后会返回 `CrewOutput` 对象，包含所有任务的结果和元数据：\n\n```python\nclass CrewOutput(BaseOutput):\n tasks_output: List[TaskOutput]\n token_usage: Dict[str, Any]\n raw: Optional[str]\n```\n\n资料来源：[lib/crewai/src/crewai/crews/crew_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crews/crew_output.py)\n\n## 记忆系统（Memory）\n\nCrew 支持可选的记忆系统，用于实现跨会话学习和上下文保持。\n\n### 记忆类型\n\n| 类型 | 参数 | 说明 |\n|------|------|------|\n| 短期记忆 | - | 当前会话的临时数据 |\n| 长期记忆 | - | 持久化的历史数据 |\n| 实体记忆 | - | 实体相关的信息 |\n| 知识库 | knowledge | 结构化的领域知识 |\n\n### 使用记忆\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n memory=True, # 启用记忆系统\n verbose=True\n)\n```\n\n## 工具集成\n\n### 工具处理器\n\n每个 Agent 可以配备多个工具，工具通过 `ToolsHandler` 进行管理和调用：\n\n```mermaid\ngraph LR\n A[Agent] --> B[ToolsHandler]\n B --> C[Tool 1]\n B --> D[Tool 2]\n B --> E[Tool N]\n```\n\n### 内置工具示例\n\nCrewAI 提供了丰富的内置工具：\n\n| 工具名称 | 功能 |\n|----------|------|\n| SerperDevTool | 网络搜索 |\n| LinkupSearchTool | 搜索增强 |\n| CodeDocsSearchTool | 代码文档搜索 |\n| TavilyExtractorTool | 网页内容提取 |\n\n### 自定义工具\n\n开发者可以创建自定义工具继承 `BaseTool` 类：\n\n```python\nfrom crewai.tools import BaseTool\n\nclass MyCustomTool(BaseTool):\n name: str = \"my_tool\"\n description: str = \"执行自定义任务\"\n\n def _run(self, **kwargs):\n # 工具逻辑\n return result\n```\n\n资料来源：[lib/crewai/src/crewai/agents/tools_handler.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/tools_handler.py)\n\n## 最佳实践\n\n### 1. YAML 配置优先\n\n推荐使用 YAML 文件定义 agents 和 tasks，保持代码简洁：\n\n```\nsrc/my_project/\n├── config/\n│ ├── agents.yaml\n│ └── tasks.yaml\n├── crew.py\n└── main.py\n```\n\n### 2. 结构化输出\n\n对于需要跨任务传递的数据，使用 `output_pydantic` 定义数据结构：\n\n```python\nTask(\n config=self.tasks_config['task_name'],\n output_pydantic=ReportModel # 定义输出结构\n)\n```\n\n### 3. 速率限制\n\n生产环境中设置合理的 `max_rpm` 避免 API 限流：\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n max_rpm=60 # 每分钟最多60次请求\n)\n```\n\n### 4. 上下文窗口管理\n\n启用 `respect_context_window=True` 自动处理 token 限制：\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n respect_context_window=True\n)\n```\n\n## 错误处理与调试\n\n### 日志输出\n\n使用 `verbose=True` 查看详细执行日志：\n\n```bash\ncrewai run # 运行并显示详细输出\ncrewai log-tasks-outputs # 查看任务输出\n```\n\n### 重放功能\n\n使用 `replay` 命令从特定任务重新执行：\n\n```bash\ncrewai replay -t \n```\n\n### 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 任务未执行 | 任务依赖未满足 | 检查 tasks_config |\n| API 超时 | 请求速率过高 | 降低 max_rpm |\n| 上下文过长 | token 超限 | 启用 respect_context_window |\n\n## 总结\n\nCrew 是 CrewAI 框架中用于组织多智能体协作的核心组件。通过合理配置 agents、tasks 和 process 模式，开发者可以构建从简单到复杂的各类自动化工作流。Crew 提供了灵活的架构，支持顺序执行、分层协调、记忆系统和丰富的工具集成，使其能够适应各种企业级应用场景。\n\n关键要点：\n- 使用 `@CrewBase` 装饰器实现声明式配置\n- 根据工作流特性选择合适的进程模式\n- 合理使用记忆系统和速率限制提升性能\n- 利用结构化输出确保任务间数据传递的准确性\n\n---\n\n\n\n## Flow 事件驱动工作流\n\n### 相关页面\n\n相关主题：[Crew 智能体团队](#crews), [Task 任务系统](#tasks), [系统架构与模块设计](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/flow/flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow.py)\n- [lib/crewai/src/crewai/flow/flow_config.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow_config.py)\n- [lib/crewai/src/crewai/flow/flow_context.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow_context.py)\n- [lib/crewai/src/crewai/flow/persistence/decorators.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/persistence/decorators.py)\n- [lib/crewai/src/crewai/flow/persistence/sqlite.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/persistence/sqlite.py)\n- [lib/cli/src/crewai_cli/templates/flow/main.py](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/flow/main.py)\n \n\n# Flow 事件驱动工作流\n\n## 概述\n\nFlow 是 CrewAI 框架中的事件驱动工作流编排模块，专为复杂的多 Crew 协调场景设计。与 Crew 的自主性（Autonomy）定位不同，Flow 提供精确的（Precise）工作流控制能力，允许开发者通过事件机制实现复杂的任务管道编排。\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\nFlow 的核心设计理念包括：\n\n- **YAML 优先配置**：通过 YAML 文件定义 agents 和 tasks，保持 Crew 类的简洁性\n- **结构化流状态**：使用 Pydantic 模型替代非结构化字典，确保类型安全\n- **事件驱动架构**：通过 `@start`、`@listen`、`@router` 装饰器实现复杂的事件路由逻辑\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 核心组件\n\nFlow 模块主要由以下组件构成，它们共同实现了事件驱动的工作流编排能力：\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| Flow | `flow.py` | 工作流主类，负责事件分发和流程协调 |\n| FlowConfig | `flow_config.py` | 工作流配置管理 |\n| FlowContext | `flow_context.py` | 上下文状态管理，用于在流程中传递数据 |\n| Persistence | `persistence/` | 持久化层，支持流程状态的保存和恢复 |\n\n### Flow 主类\n\nFlow 类是整个事件驱动工作流的核心，负责：\n\n- 管理事件监听器注册\n- 分发事件到对应的处理器\n- 协调多个 Crew 的执行顺序\n\n```python\nclass Flow:\n def __init__(self):\n self._event_bus = EventBus()\n self._listeners = []\n \n def on(self, event_type):\n \"\"\"注册事件监听器\"\"\"\n def decorator(func):\n self._listeners.append((event_type, func))\n return func\n return decorator\n \n def emit(self, event):\n \"\"\"触发事件\"\"\"\n self._event_bus.emit(event)\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py](#)\n\n### FlowContext 上下文管理\n\nFlowContext 提供了流程内的状态共享机制，允许不同的事件处理器之间传递数据：\n\n```python\nclass FlowContext:\n def __init__(self, initial_state=None):\n self._state = initial_state or {}\n \n def set(self, key, value):\n \"\"\"设置状态值\"\"\"\n self._state[key] = value\n \n def get(self, key, default=None):\n \"\"\"获取状态值\"\"\"\n return self._state.get(key, default)\n \n def to_dict(self):\n \"\"\"导出为字典\"\"\"\n return self._state.copy()\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow_context.py](#)\n\n### FlowConfig 配置管理\n\nFlowConfig 负责管理工作流的配置信息，包括事件路由规则、超时设置等：\n\n```python\nclass FlowConfig:\n def __init__(\n self,\n max_retries: int = 3,\n timeout: int = 3600,\n enable_persistence: bool = True\n ):\n self.max_retries = max_retries\n self.timeout = timeout\n self.enable_persistence = enable_persistence\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow_config.py](#)\n\n## 事件驱动架构\n\n### 事件总线模式\n\nFlow 采用事件总线（Event Bus）模式进行事件分发，所有事件通过中央总线进行路由：\n\n```mermaid\ngraph TD\n A[事件源] --> B[EventBus 事件总线]\n B --> C[监听器 A]\n B --> D[监听器 B]\n B --> E[监听器 C]\n C --> F[事件处理]\n D --> G[事件处理]\n E --> H[事件处理]\n```\n\n事件总线的核心职责包括：\n\n- 维护事件类型与监听器的映射关系\n- 按顺序触发匹配的监听器\n- 处理事件传播中的异常\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py](#)\n\n### 事件类型分类\n\nFlow 支持多种事件类型，覆盖完整的工作流生命周期：\n\n| 事件类别 | 描述 | 使用场景 |\n|----------|------|----------|\n| Crew 生命周期事件 | Crew 启动、完成、失败等 | 协调多 Crew 执行顺序 |\n| Agent 执行事件 | Agent 任务分配、执行结果 | 监控 Agent 状态 |\n| Task 管理事件 | 任务创建、执行、完成 | 任务依赖管理 |\n| Tool 使用事件 | 工具调用及结果 | 工具使用审计 |\n| Knowledge 检索事件 | 知识库查询 | RAG 相关处理 |\n| LLM 调用事件 | 模型交互记录 | 成本和性能监控 |\n| Memory 操作事件 | 记忆读写操作 | 会话状态管理 |\n| Flow 执行事件 | Flow 特有的流程控制 | 事件路由决策 |\n| Safety 事件 | 安全防护触发 | 内容过滤和验证 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n### 事件监听装饰器\n\nFlow 提供了三个核心装饰器用于定义事件处理器：\n\n| 装饰器 | 功能 | 示例 |\n|--------|------|------|\n| `@start` | 定义流程启动时的初始事件 | 触发第一个 Crew |\n| `@listen` | 监听特定事件并处理 | 响应 Crew 完成事件 |\n| `@router` | 根据条件路由到不同处理路径 | 条件分支逻辑 |\n\n```python\nfrom crewai.flow.flow import Flow, start, listen, router\n\nclass MyFlow(Flow):\n @start()\n def begin(self):\n \"\"\"流程启动事件\"\"\"\n return {\"action\": \"start_research\"}\n \n @listen(\"research_complete\")\n def process_results(self, event):\n \"\"\"监听研究完成事件\"\"\"\n return {\"action\": \"analyze\"}\n \n @router()\n def route_by_quality(self, event):\n \"\"\"条件路由\"\"\"\n if event.get(\"quality_score\", 0) > 0.8:\n return \"high_quality_path\"\n return \"standard_path\"\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 持久化层\n\n### SQLite 持久化\n\nFlow 内置了基于 SQLite 的持久化方案，用于保存工作流执行状态：\n\n```python\nclass SQLitePersistence:\n def __init__(self, db_path: str = \"crewai_flow.db\"):\n self.db_path = db_path\n \n def save_state(self, flow_id: str, state: dict):\n \"\"\"保存流程状态\"\"\"\n pass\n \n def load_state(self, flow_id: str) -> dict:\n \"\"\"加载流程状态\"\"\"\n pass\n \n def save_event(self, event: dict):\n \"\"\"保存事件历史\"\"\"\n pass\n```\n\n资料来源：[lib/crewai/src/crewai/flow/persistence/sqlite.py](#)\n\n### 持久化装饰器\n\n提供了用于标记持久化行为的装饰器：\n\n```python\n@persistence\nclass MyFlow(Flow):\n \"\"\"启用自动持久化的 Flow\"\"\"\n pass\n```\n\n资料来源：[lib/crewai/src/crewai/flow/persistence/decorators.py](#)\n\n### 持久化配置\n\n持久化支持以下配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `enable_persistence` | bool | True | 是否启用持久化 |\n| `db_path` | str | \"crewai_flow.db\" | 数据库路径 |\n| `auto_save` | bool | True | 是否自动保存状态 |\n| `save_interval` | int | 60 | 自动保存间隔（秒） |\n\n## 使用模式\n\n### 顺序执行模式\n\n适用于线性工作流，下一个任务依赖上一个任务的结果：\n\n```mermaid\ngraph LR\n A[开始] --> B[任务 1]\n B --> C[任务 2]\n C --> D[任务 3]\n D --> E[结束]\n```\n\n### 并行执行模式\n\n多个任务可以同时执行，提高效率：\n\n```mermaid\ngraph TD\n A[开始] --> B[任务 A]\n A --> C[任务 B]\n A --> D[任务 C]\n B --> E[汇合]\n C --> E\n D --> E\n E --> F[完成]\n```\n\n### 条件路由模式\n\n根据事件内容动态选择处理路径：\n\n```mermaid\ngraph TD\n A[事件] --> B{条件判断}\n B -->|条件 A| C[处理 A]\n B -->|条件 B| D[处理 B]\n B -->|条件 C| E[处理 C]\n C --> F[结束]\n D --> F\n E --> F\n```\n\n## 完整示例\n\n### 项目结构\n\n```\nmy_flow_project/\n├── src/\n│ └── my_flow/\n│ ├── __init__.py\n│ ├── crew.py # Crew 定义\n│ ├── flow.py # Flow 定义\n│ └── main.py # 入口文件\n└── config/\n ├── agents.yaml\n └── tasks.yaml\n```\n\n### Flow 定义示例\n\n```python\n# src/my_flow/flow.py\nfrom crewai.flow.flow import Flow\nfrom crewai import Crew, Agent, Task\nfrom crewai.flow.flow_context import FlowContext\nfrom pydantic import BaseModel\n\nclass FlowState(BaseModel):\n research_results: str = \"\"\n analysis_results: str = \"\"\n final_report: str = \"\"\n\nclass ResearchFlow(Flow):\n def __init__(self):\n super().__init__()\n self.state = FlowContext()\n \n def initialize_crew(self):\n \"\"\"初始化 Crew\"\"\"\n researcher = Agent(\n role=\"Researcher\",\n goal=\"Research the topic thoroughly\",\n backstory=\"Expert researcher\"\n )\n analyzer = Agent(\n role=\"Analyzer\",\n goal=\"Analyze research findings\",\n backstory=\"Expert analyst\"\n )\n \n research_task = Task(\n description=\"Research {topic}\",\n expected_output=\"Comprehensive research report\",\n agent=researcher\n )\n \n analysis_task = Task(\n description=\"Analyze research results\",\n expected_output=\"Analysis summary\",\n agent=analyzer\n )\n \n return Crew(\n agents=[researcher, analyzer],\n tasks=[research_task, analysis_task],\n process=\"sequential\"\n )\n \n def crew_callback(self, crew, output):\n \"\"\"Crew 执行回调\"\"\"\n self.state.set(\"last_output\", output.raw)\n return output\n\n# 导出 kickoff 方法供 CLI 调用\ndef kickoff():\n flow = ResearchFlow()\n result = flow.kickoff()\n return result\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/flow/main.py](#)\n\n### 入口文件\n\n```python\n# src/my_flow/main.py\nfrom crewai import Crew\nfrom crewai.flow.flow import Flow\nfrom crewai.project import CrewBase, agent, crew, task\n\n@CrewBase\nclass MyFlowCrew():\n \"\"\"Flow 内部使用的 Crew\"\"\"\n agents: list\n tasks: list\n \n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n verbose=True\n )\n\ndef run_flow(topic: str):\n \"\"\"运行 Flow\"\"\"\n flow = MyFlowCrew()\n result = flow.kickoff(inputs={\"topic\": topic})\n return result\n\nif __name__ == \"__main__\":\n result = run_flow(\"AI Agents\")\n print(result)\n```\n\n## CLI 命令\n\nFlow 项目支持以下命令行操作：\n\n| 命令 | 描述 |\n|------|------|\n| `crewai create flow ` | 创建新的 Flow 项目 |\n| `crewai run` | 运行 Flow（自动检测 pyproject.toml） |\n| `crewai flow kickoff` | 旧版 Flow 执行命令 |\n\n```bash\n# 创建 Flow 项目\ncrewai create flow my_flow --skip_provider\n\n# 安装依赖\ncrewai install\n\n# 运行 Flow\ncrewai run\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 最佳实践\n\n### 结构化状态管理\n\n始终使用 Pydantic 模型定义 Flow 状态，而非普通的字典：\n\n```python\nfrom pydantic import BaseModel\n\nclass FlowState(BaseModel):\n topic: str\n research_data: dict = {}\n analysis_result: str = \"\"\n report_path: str = \"\"\n```\n\n这样可以获得更好的类型检查和 IDE 支持。\n\n### 事件命名规范\n\n使用清晰的事件命名约定，便于追踪和调试：\n\n- `crew_kickoff_started`: Crew 开始执行\n- `crew_kickoff_completed`: Crew 执行完成\n- `task_completed`: 单个任务完成\n- `error_occurred`: 错误发生\n\n### 异常处理\n\n在事件处理器中添加适当的异常处理：\n\n```python\n@listen(\"external_event\")\ndef handle_external(self, event):\n try:\n result = process_event(event)\n return {\"status\": \"success\", \"data\": result}\n except Exception as e:\n return {\"status\": \"error\", \"message\": str(e)}\n```\n\n### 超时配置\n\n对于可能长时间运行的操作，设置合理的超时时间：\n\n```python\nflow_config = FlowConfig(\n timeout=3600, # 1 小时\n max_retries=3\n)\n```\n\n## 与 Crew 的对比\n\n| 特性 | Crew | Flow |\n|------|------|------|\n| **定位** | 自主性（Autonomy） | 精确性（Precise） |\n| **执行模式** | 并行/层次化 | 事件驱动 |\n| **任务协调** | 自动委托 | 显式路由 |\n| **适用场景** | 通用多 Agent 协作 | 复杂流程控制 |\n| **配置方式** | YAML + Python | Python 优先 |\n\n## 总结\n\nFlow 事件驱动工作流为 CrewAI 提供了强大的流程编排能力，特别适合以下场景：\n\n- 需要精确控制执行顺序的多步骤流程\n- 基于条件进行动态分支的业务逻辑\n- 需要保存和恢复执行状态的长时间运行任务\n- 需要事件日志和审计追踪的应用\n\n通过结合 Crew 的自主 Agent 能力和 Flow 的精确控制能力，开发者可以构建出既智能又可控的复杂 AI 工作流系统。\n\n---\n\n\n\n## Task 任务系统\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents), [Crew 智能体团队](#crews), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/task.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/task.py)\n- [lib/crewai/src/crewai/tasks/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/__init__.py)\n- [lib/crewai/src/crewai/tasks/conditional_task.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/conditional_task.py)\n- [lib/crewai/src/crewai/tasks/task_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/task_output.py)\n- [lib/crewai/src/crewai/tasks/llm_guardrail.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/llm_guardrail.py)\n- [lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml)\n \n\n# Task 任务系统\n\n## 概述\n\nTask 任务是 CrewAI 多智能体框架中的核心执行单元。每个 Task 代表一个具体的工作目标，由特定的 Agent 负责执行。Task 系统支持丰富的配置选项，包括输出结构化数据、任务依赖关系、条件执行、输出验证等功能。\n\nTask 系统的主要职责：\n\n- 定义具体的工作任务和预期输出\n- 管理 Agent 与 Task 之间的绑定关系\n- 处理任务之间的依赖关系和执行顺序\n- 支持结构化输出（Pydantic、JSON）\n- 提供输出验证和 Guardrails 机制\n\n## 核心组件\n\n### Task 类\n\n`Task` 是任务系统的核心类，位于 `lib/crewai/src/crewai/task.py`。\n\n```mermaid\nclassDiagram\n class Task {\n +str description\n +str expected_output\n +Agent agent\n +List~Task~ dependencies\n +str output_file\n +bool verbose\n +int max_iterations\n +float max_rpm\n +callbacks: List[Callback]\n +async_execute()\n +execute()\n +output: TaskOutput\n }\n```\n\n### TaskOutput 类\n\n`TaskOutput` 类封装任务的执行结果。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `description` | str | 任务描述 |\n| `pydantic` | BaseModel | Pydantic 模型实例（结构化输出） |\n| `json_dict` | dict | JSON 格式输出 |\n| `text` | str | 纯文本输出 |\n| `summary` | str | 任务执行摘要 |\n\n资料来源：[lib/crewai/src/crewai/tasks/task_output.py]()\n\n### ConditionalTask 类\n\n条件任务允许根据运行时条件决定是否执行任务。\n\n```python\n@task\ndef conditional_research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n condition=lambda context: len(context.get('topics', [])) > 0\n )\n```\n\n资料来源：[lib/crewai/src/crewai/tasks/conditional_task.py]()\n\n## Task 属性详解\n\n### 基础属性\n\n| 属性 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `description` | str | 是 | 任务的详细描述，描述 Agent 需要完成的工作 |\n| `expected_output` | str | 是 | 期望的输出格式和内容说明 |\n| `agent` | Agent | 否 | 负责执行此任务的 Agent，可为空让 Crew 自动分配 |\n| `dependencies` | List[Task] | 否 | 任务依赖列表，必须在依赖任务完成后才能执行 |\n| `output_file` | str | 否 | 输出文件路径，任务结果将写入此文件 |\n\n### 执行控制属性\n\n| 属性 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `verbose` | bool | False | 是否启用详细输出模式 |\n| `max_iterations` | int | 20 | 最大迭代次数，防止无限循环 |\n| `max_rpm` | int | 0 | 每分钟最大请求数（0 表示不限制） |\n| `respect_context_window` | bool | True | 是否尊重上下文窗口限制 |\n\n### 输出配置属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `output_pydantic` | BaseModel | Pydantic 模型类，用于结构化输出验证 |\n| `output_json` | Type[BaseModel] | JSON Schema 模型，用于 JSON 输出 |\n| `callback` | Any | 任务完成后的回调函数 |\n\n资料来源：[lib/crewai/src/crewai/task.py]()\n\n## Guardrails 机制\n\nGuardrails 用于验证和约束任务输出，确保输出符合预期标准。\n\n### LLM Guardrail\n\n基于 LLM 的输出验证器。\n\n```python\nfrom crewai.tasks.llm_guardrail import LLMGuardrail\n\nguardrail = LLMGuardrail(\n llm=agent.llm,\n threshold=0.7\n)\n```\n\n### Hallucination Guardrail\n\n检测输出中的幻觉内容（事实性错误）。\n\n```python\nfrom crewai.tasks.hallucination_guardrail import HallucinationGuardrail\n\nguardrail = HallucinationGuardrail(\n llm=agent.llm,\n context=\"参考文档内容...\",\n threshold=8.0\n)\n```\n\n| Guardrail 类型 | 用途 | 适用场景 |\n|---------------|------|----------|\n| `LLMGuardrail` | 通用的 LLM 输出验证 | 格式检查、风格验证 |\n| `HallucinationGuardrail` | 幻觉检测 | 事实性内容验证 |\n\n资料来源：[lib/crewai/src/crewai/tasks/llm_guardrail.py]()\n\n## 任务依赖与执行流程\n\n### 依赖关系管理\n\n```mermaid\ngraph TD\n A[Task A: 研究任务] --> B[Task B: 分析任务]\n A --> C[Task C: 报告撰写]\n B --> C\n D[Task D: 条件任务] -->|仅当条件满足| E[Task E: 后续任务]\n```\n\n### 顺序执行流程\n\n在 `Process.sequential` 模式下，任务按依赖顺序执行：\n\n1. 执行没有依赖的任务\n2. 等待所有依赖任务完成\n3. 收集依赖任务的输出作为上下文\n4. 执行当前任务\n5. 重复直到所有任务完成\n\n```python\nfrom crewai import Crew, Process, Task, Agent\n\nresearcher = Agent(role=\"研究员\", goal=\"收集信息\", backstory=\"...\")\nanalyst = Agent(role=\"分析师\", goal=\"分析数据\", backstory=\"...\")\n\nresearch_task = Task(\n description=\"研究最新 AI 发展\",\n expected_output=\"AI 发展摘要\",\n agent=researcher\n)\n\nanalysis_task = Task(\n description=\"分析研究结果\",\n expected_output=\"深度分析报告\",\n agent=analyst,\n dependencies=[research_task] # 依赖于研究任务\n)\n\ncrew = Crew(\n agents=[researcher, analyst],\n tasks=[research_task, analysis_task],\n process=Process.sequential\n)\n```\n\n资料来源：[lib/crewai/src/crewai/task.py:1-200]()\n\n## YAML 配置\n\n### tasks.yaml 配置示例\n\n```yaml\n# lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml\n\nresearch_task:\n description: >\n 深入研究 {topic} 相关信息，收集最新发展和趋势。\n 这包括新闻文章、学术论文和行业报告。\n expected_output: >\n 一份结构化的研究报告，包含关键发现、\n 数据来源和趋势分析。\n agent: researcher\n\nreporting_task:\n description: >\n 基于研究报告，创建一份全面的报告\n expected_output: >\n 一份完整的报告，包含主要主题，\n 每个主题都有详细信息。格式为 markdown，不包含代码块。\n agent: reporting_analyst\n output_file: report.md\n```\n\n### 条件任务配置\n\n```yaml\nconditional_research_task:\n description: >\n 仅当存在特定主题时执行深入研究\n expected_output: >\n 针对指定主题的详细研究报告\n agent: researcher\n condition: \"topics_exist\" # 条件标识符\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml]()\n\n## 编程式创建 Task\n\n### 基本用法\n\n```python\nfrom crewai import Agent, Task\n\nagent = Agent(\n role=\"高级数据研究员\",\n goal=\"发现 {topic} 的最新发展\",\n backstory=\"你是一名资深研究员...\"\n)\n\ntask = Task(\n description=\"深入研究 {topic}\",\n expected_output=\"一份详细的研究报告\",\n agent=agent,\n verbose=True\n)\n```\n\n### 结构化输出\n\n```python\nfrom pydantic import BaseModel, Field\nfrom crewai import Task\n\nclass ResearchOutput(BaseModel):\n summary: str = Field(description=\"研究摘要\")\n key_findings: list[str] = Field(description=\"关键发现\")\n sources: list[str] = Field(description=\"数据来源\")\n\ntask = Task(\n description=\"研究 AI Agents\",\n expected_output=\"结构化的研究结果\",\n agent=agent,\n output_pydantic=ResearchOutput\n)\n```\n\n### 带依赖的任务\n\n```python\nanalysis_task = Task(\n description=\"分析研究报告\",\n expected_output=\"分析结论\",\n agent=analyst,\n dependencies=[research_task] # 等待研究任务完成\n)\n```\n\n### 输出到文件\n\n```python\nreport_task = Task(\n description=\"撰写报告\",\n expected_output=\"完整的报告文档\",\n agent=writer,\n output_file=\"report.md\" # 结果将写入此文件\n)\n```\n\n## 任务执行上下文\n\n### 上下文传递机制\n\n```mermaid\ngraph LR\n A[Task A 输出] -->|context| B[Task B 输入]\n B -->|context| C[Task C 输入]\n C -->|最终结果| D[Result]\n```\n\n当一个任务完成后，其输出（`TaskOutput`）会自动传递给依赖它的任务作为上下文。上下文包含：\n\n- `task_output.text`: 文本输出\n- `task_output.pydantic`: Pydantic 模型实例\n- `task_output.json_dict`: JSON 字典格式\n- `task_output.summary`: 执行摘要\n\n### 访问上下文\n\n```python\ndef analysis_callback(context: dict):\n previous_results = context.get('previous_tasks', [])\n for result in previous_results:\n print(result.text)\n\ntask = Task(\n description=\"基于之前结果继续分析\",\n expected_output=\"深入分析\",\n agent=analyst,\n dependencies=[research_task],\n callback=analysis_callback\n)\n```\n\n## 最佳实践\n\n### 1. 清晰的任务描述\n\n```python\n# ✅ 推荐：清晰、具体的描述\ntask = Task(\n description=\"从 2024 年 1 月至 6 月的财经新闻中提取关于 AI 投资的信息\",\n expected_output=\"JSON 格式的投资信息列表，包含公司名、投资金额、投资轮次\"\n)\n\n# ❌ 避免：模糊的描述\ntask = Task(\n description=\"查一下新闻\"\n)\n```\n\n### 2. 明确的预期输出\n\n```python\ntask = Task(\n description=\"分析销售数据\",\n expected_output=\"\"\"\n 格式：Markdown 表格\n 列：产品名称 | 销量 | 增长率 | 市场份额\n 包含趋势分析和改进建议\n \"\"\"\n)\n```\n\n### 3. 合理的任务粒度\n\n- 单个任务应该完成一个明确的目标\n- 避免将多个不相关的任务合并为一个\n- 使用依赖关系组织复杂工作流\n\n### 4. 任务依赖规划\n\n```python\n# 正确的依赖设计\ntask_1 = Task(description=\"收集原始数据\", ...)\ntask_2 = Task(description=\"清洗数据\", dependencies=[task_1], ...)\ntask_3 = Task(description=\"数据分析\", dependencies=[task_2], ...)\ntask_4 = Task(description=\"生成可视化\", dependencies=[task_3], ...)\n```\n\n## 与 CrewBase 装饰器集成\n\n### 使用装饰器定义任务\n\n```python\nfrom crewai import Agent, Crew, Process, Task\nfrom crewai.project import CrewBase, agent, task\nfrom typing import List\n\n@CrewBase\nclass ResearchCrew():\n agents: List[Agent]\n tasks: List[Task]\n \n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n )\n\n @task\n def reporting_task(self) -> Task:\n return Task(\n config=self.tasks_config['reporting_task'],\n output_file='report.md'\n )\n\n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n )\n```\n\n资料来源：[lib/crewai/src/crewai/tasks/__init__.py]()\n\n## 执行状态与监控\n\n### 任务状态\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建任务\n Pending --> InProgress: 开始执行\n InProgress --> Completed: 正常完成\n InProgress --> Failed: 执行错误\n InProgress --> Retrying: 重试中\n Failed --> [*]\n Completed --> [*]\n```\n\n### 迭代控制\n\n```python\ntask = Task(\n description=\"复杂分析任务\",\n expected_output=\"分析结果\",\n max_iterations=10, # 最多迭代 10 次\n max_rpm=5 # 每分钟最多 5 次请求\n)\n```\n\n### Verbose 模式\n\n```python\n# 启用详细输出\ntask = Task(\n description=\"搜索并分析\",\n expected_output=\"结果摘要\",\n verbose=True # 显示详细执行日志\n)\n```\n\n## 总结\n\nTask 任务系统是 CrewAI 框架的核心组成部分，提供了：\n\n- **灵活的配置**：支持 YAML 和编程式两种定义方式\n- **结构化输出**：通过 Pydantic 模型实现类型安全的输出\n- **依赖管理**：支持任务的串行和条件执行\n- **输出验证**：Guardrails 机制确保输出质量\n- **上下文传递**：任务之间自动共享执行结果\n\n通过合理使用 Task 系统，可以构建复杂的多智能体工作流，实现自动化的问题解决流程。\n\n---\n\n\n\n## LLM 集成与提供者\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/llm.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llm.py)\n- [lib/crewai/src/crewai/llms/base_llm.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/base_llm.py)\n- [lib/crewai/src/crewai/llms/providers/openai/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/openai/completion.py)\n- [lib/crewai/src/crewai/llms/providers/anthropic/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/anthropic/completion.py)\n- [lib/crewai/src/crewai/llms/providers/bedrock/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/bedrock/completion.py)\n- [lib/crewai/src/crewai/llms/providers/gemini/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/gemini/completion.py)\n- [lib/crewai/src/crewai/llms/providers/azure/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/azure/completion.py)\n- [lib/crewai/src/crewai/hooks/llm_hooks.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/hooks/llm_hooks.py)\n\n \n\n# LLM 集成与提供者\n\n## 概述\n\nCrewAI 框架的 LLM（大型语言模型）集成系统为 AI Agent 提供了灵活的多提供者支持。该系统采用模块化架构，支持 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure 等主流 LLM 提供者，同时允许通过统一接口自定义配置。\n\n## 架构设计\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[Agent] --> B[LLM 接口层]\n B --> C[BaseLLM 抽象基类]\n C --> D[OpenAI Provider]\n C --> E[Anthropic Provider]\n C --> F[Gemini Provider]\n C --> G[Bedrock Provider]\n C --> H[Azure Provider]\n C --> I[自定义 Provider]\n```\n\n### 核心文件结构\n\n| 层级 | 文件路径 | 职责 |\n|------|----------|------|\n| 主接口 | `lib/crewai/src/crewai/llm.py` | LLM 主类，封装调用逻辑 |\n| 抽象基类 | `lib/crewai/src/crewai/llms/base_llm.py` | 定义提供者接口规范 |\n| 提供者实现 | `lib/crewai/src/crewai/llms/providers/*/completion.py` | 各提供者的具体实现 |\n| 钩子系统 | `lib/crewai/src/crewai/hooks/llm_hooks.py` | LLM 调用生命周期钩子 |\n\n## LLM 配置方式\n\n### 通过 Agent 配置\n\n在创建 Agent 时直接指定 LLM：\n\n```python\nfrom crewai import Agent\nfrom crewai.llm import LLM\n\nagent = Agent(\n role=\"研究助手\",\n goal=\"深入研究指定主题\",\n backstory=\"经验丰富的领域专家\",\n llm=LLM(model=\"gpt-4\", temperature=0.7)\n)\n```\n\n### 通过 config 字典配置\n\n支持使用配置字典自定义模型和嵌入层：\n\n```python\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n temperature=0.5,\n top_p=1,\n stream=True,\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md)\n\n## 支持的 LLM 提供者\n\n### 提供者配置对照表\n\n| 提供者 | 模型标识 | 配置参数 |\n|--------|----------|----------|\n| OpenAI | `gpt-4`, `gpt-4o`, `gpt-4o-mini` | temperature, max_tokens, top_p |\n| Anthropic | `claude-3-5-sonnet`, `claude-3-opus` | temperature, max_tokens |\n| Google Gemini | `gemini-pro`, `gemini-2.0-flash` | temperature, top_p |\n| AWS Bedrock | `anthropic.claude-*`, `amazon.titan-*` | region, model_id |\n| Azure | Azure OpenAI 部署名 | api_version, api_base |\n| Ollama | 本地模型 | model, base_url |\n\n### OpenAI Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/openai/completion.py\nclass OpenAICompletion:\n \"\"\"处理 OpenAI API 调用的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n self.temperature = kwargs.get(\"temperature\", 0.7)\n```\n\n### Anthropic Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/anthropic/completion.py\nclass AnthropicCompletion:\n \"\"\"Anthropic Claude 系列模型的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n self.max_tokens = kwargs.get(\"max_tokens\", 4096)\n```\n\n### Bedrock Provider 实现\n\n支持 AWS Bedrock 上的多种模型，包括 Anthropic Claude 和 Amazon Titan 系列：\n\n```python\n# lib/crewai/src/crewai/llms/providers/bedrock/completion.py\nclass BedrockCompletion:\n \"\"\"AWS Bedrock 提供者实现\"\"\"\n \n def __init__(self, model: str, region: str = \"us-east-1\", **kwargs):\n self.model = model\n self.region = region\n self.aws_access_key = kwargs.get(\"aws_access_key_id\")\n self.aws_secret_key = kwargs.get(\"aws_secret_access_key\")\n```\n\n### Gemini Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/gemini/completion.py\nclass GeminiCompletion:\n \"\"\"Google Gemini 模型的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n```\n\n### Azure Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/azure/completion.py\nclass AzureCompletion:\n \"\"\"Azure OpenAI Service 提供者实现\"\"\"\n \n def __init__(self, \n deployment_name: str,\n api_base: str,\n api_version: str = \"2024-02-01\",\n **kwargs):\n self.deployment_name = deployment_name\n self.api_base = api_base\n self.api_version = api_version\n```\n\n## BaseLLM 抽象基类\n\n所有 LLM 提供者必须继承自 `BaseLLM`，实现标准接口：\n\n```python\n# lib/crewai/src/crewai/llms/base_llm.py\nfrom abc import ABC, abstractmethod\n\nclass BaseLLM(ABC):\n \"\"\"LLM 提供者抽象基类\"\"\"\n \n @abstractmethod\n def call(self, prompt: str, **kwargs) -> str:\n \"\"\"执行 LLM 调用\"\"\"\n pass\n \n @abstractmethod\n def get_model_name(self) -> str:\n \"\"\"获取当前模型名称\"\"\"\n pass\n \n @property\n @abstractmethod\n def supports_system_prompts(self) -> bool:\n \"\"\"检查提供者是否支持系统提示\"\"\"\n pass\n \n @property\n @abstractmethod\n def supports_function_calling(self) -> bool:\n \"\"\"检查提供者是否支持函数调用\"\"\"\n pass\n```\n\n## LLM 钩子系统\n\n### llm_hooks.py 生命周期钩子\n\n```mermaid\ngraph LR\n A[LLM 调用开始] --> B[on_llm_new_token]\n B --> C[token 处理中]\n C --> D[on_llm_new_token]\n D --> E[调用完成]\n E --> F[on_llm_end]\n A --> F2[on_llm_start]\n```\n\n### 钩子类型\n\n| 钩子方法 | 触发时机 | 用途 |\n|----------|----------|------|\n| `on_llm_start` | 调用开始前 | 记录请求参数、设置上下文 |\n| `on_llm_new_token` | 每个新 token 生成时 | 流式输出处理、实时反馈 |\n| `on_llm_end` | 调用完成后 | 记录响应、执行后处理 |\n| `on_llm_error` | 发生错误时 | 错误处理、告警通知 |\n\n### 自定义钩子实现\n\n```python\n# lib/crewai/src/crewai/hooks/llm_hooks.py\nclass LLMCallbackHandler:\n \"\"\"LLM 回调处理器基类\"\"\"\n \n def on_llm_start(self, serialized, prompts, **kwargs):\n \"\"\"LLM 调用开始时的钩子\"\"\"\n pass\n \n def on_llm_new_token(self, token: str, **kwargs):\n \"\"\"新 token 生成时的钩子\"\"\"\n pass\n \n def on_llm_end(self, response, **kwargs):\n \"\"\"LLM 调用结束时的钩子\"\"\"\n pass\n \n def on_llm_error(self, error, **kwargs):\n \"\"\"LLM 调用出错时的钩子\"\"\"\n pass\n```\n\n## LLM 主类接口\n\n### llm.py 核心功能\n\n```python\n# lib/crewai/src/crewai/llm.py\nclass LLM:\n \"\"\"统一的 LLM 接口类\"\"\"\n \n def __init__(\n self,\n model: str,\n provider: str = \"openai\",\n temperature: float = 0.7,\n max_tokens: int | None = None,\n **kwargs\n ):\n \"\"\"初始化 LLM 实例\n \n Args:\n model: 模型标识符 (如 \"gpt-4\", \"claude-3-opus\")\n provider: 提供者名称 (默认 \"openai\")\n temperature: 生成温度 (0.0-1.0)\n max_tokens: 最大 token 数量限制\n **kwargs: 提供者特定参数\n \"\"\"\n self.model = model\n self.provider = provider\n self.temperature = temperature\n self.max_tokens = max_tokens\n self._setup_provider(**kwargs)\n```\n\n### 主要方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `call()` | prompt, system_prompt, **kwargs | str | 执行文本生成 |\n| `call_with_functions()` | prompt, functions, **kwargs | dict | 执行带函数调用的生成 |\n| `supports_function_calling()` | - | bool | 检查函数调用支持 |\n| `supports_vision()` | - | bool | 检查视觉输入支持 |\n\n## 环境变量配置\n\n### OpenAI 配置\n\n```bash\nOPENAI_API_KEY=sk-...\nOPENAI_API_BASE=https://api.openai.com/v1 # 可选，自定义端点\n```\n\n### Anthropic 配置\n\n```bash\nANTHROPIC_API_KEY=sk-ant-...\n```\n\n### Google Gemini 配置\n\n```bash\nGOOGLE_API_KEY=AIza...\n```\n\n### AWS Bedrock 配置\n\n```bash\nAWS_ACCESS_KEY_ID=AKIA...\nAWS_SECRET_ACCESS_KEY=...\nAWS_REGION=us-east-1\n```\n\n### Azure 配置\n\n```bash\nAZURE_OPENAI_API_KEY=...\nAZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com\nAZURE_OPENAI_API_VERSION=2024-02-01\n```\n\n## 最佳实践\n\n### 模型选择指南\n\n```mermaid\ngraph TD\n A[任务类型] --> B{需要函数调用?}\n B -->|是| C{预算有限?|\n C -->|是| D[GPT-4o-mini + function calling]\n C -->|否| E[GPT-4 + function calling]\n B -->|否| F{需要长上下文?|\n F -->|是| G[Claude 3.5 Sonnet]\n F -->|否| H[GPT-4o]\n```\n\n### 温度参数建议\n\n| 任务场景 | 建议温度值 | 说明 |\n|----------|------------|------|\n| 代码生成 | 0.0 - 0.2 | 需要精确、一致的输出 |\n| 创意写作 | 0.7 - 0.9 | 需要多样性和创意 |\n| 问答总结 | 0.3 - 0.5 | 平衡准确性和多样性 |\n| 结构化输出 | 0.0 - 0.1 | 最大化输出格式一致性 |\n\n### 错误处理模式\n\n```python\nfrom crewai.llm import LLM\nfrom crewai.llms.base_llm import LLMGenerationError\n\nllm = LLM(model=\"gpt-4\", temperature=0.7)\n\ntry:\n response = llm.call(\n prompt=\"解释量子计算原理\",\n system_prompt=\"你是一位物理学家\"\n )\nexcept LLMGenerationError as e:\n print(f\"LLM 生成失败: {e}\")\n # 实现降级逻辑或重试机制\n```\n\n## 版本检查功能\n\nCrewAI 提供内置版本检查机制：\n\n```python\n# lib/crewai/src/crewai/version.py\nfrom crewai.version import (\n check_version,\n get_crewai_version,\n is_newer_version_available,\n get_latest_version_from_pypi,\n)\n\n# 检查当前版本\ncurrent = get_crewai_version()\n\n# 检查是否有新版本\nif is_newer_version_available():\n latest = get_latest_version_from_pypi()\n print(f\"有新版本可用: {latest}\")\n```\n\n## 总结\n\nCrewAI 的 LLM 集成系统提供了：\n\n- **多提供者支持**：OpenAI、Anthropic、Gemini、Bedrock、Azure 等\n- **统一接口**：`BaseLLM` 抽象基类确保一致性\n- **灵活配置**：支持环境变量和代码配置\n- **生命周期钩子**：完整的调用监控和扩展能力\n- **版本管理**：自动检查更新，保持兼容性\n\n此架构使开发者能够轻松切换不同的 LLM 提供者，同时保持应用代码的稳定性和可移植性。\n\n---\n\n\n\n## 工具系统与 MCP 集成\n\n### 相关页面\n\n相关主题：[MCP 与 A2A 协议](#mcp-a2a), [Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/tools/base_tool.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/base_tool.py)\n- [lib/crewai/src/crewai/tools/structured_tool.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/structured_tool.py)\n- [lib/crewai/src/crewai/tools/tool_calling.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/tool_calling.py)\n- [lib/crewai/src/crewai/mcp/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/__init__.py)\n- [lib/crewai/src/crewai/mcp/client.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/client.py)\n- [lib/crewai/src/crewai/mcp/tool_resolver.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/tool_resolver.py)\n- [lib/crewai-tools/src/crewai_tools/tool.specs.json](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tool.specs.json)\n \n\n# 工具系统与 MCP 集成\n\n## 概述\n\nCrewAI 的工具系统是一个模块化的插件架构，允许 AI Agent 通过标准化的接口调用外部工具和资源。该系统支持两种主要的集成方式：内置工具和 MCP（Model Context Protocol）协议集成。通过统一的工具调用机制，Agent 可以执行文件操作、网络搜索、数据库查询、RAG 检索等复杂任务。\n\n工具系统的核心设计理念是将工具定义与工具执行解耦，每个工具通过 Pydantic Schema 定义参数和返回值，确保类型安全和参数验证。\n\n## 架构设计\n\n### 工具系统架构图\n\n```mermaid\ngraph TD\n subgraph \"工具层 Tool Layer\"\n A[BaseTool] --> B[StructuredTool]\n B --> C[内置工具]\n B --> D[MCP 工具]\n end\n \n subgraph \"工具注册层\"\n E[ToolRegistry] --> A\n F[MCPToolResolver] --> D\n end\n \n subgraph \"Agent 执行层\"\n G[Agent] --> H[ToolCalling]\n H --> E\n H --> F\n end\n \n subgraph \"外部系统\"\n I[MCP Server] --> F\n J[文件系统] --> C\n K[网络服务] --> C\n end\n```\n\n### 核心组件说明\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| BaseTool | `base_tool.py` | 工具基类，定义工具元数据和执行接口 |\n| StructuredTool | `structured_tool.py` | 结构化工具，支持 Pydantic 参数校验 |\n| ToolCalling | `tool_calling.py` | 工具调用控制器，管理工具执行流程 |\n| MCPToolResolver | `tool_resolver.py` | MCP 协议工具解析器 |\n| MCPClient | `client.py` | MCP 客户端，负责与 MCP 服务器通信 |\n\n## 内置工具详解\n\n### BaseTool 基类\n\n`BaseTool` 是所有工具的基类，提供了工具的基本属性和抽象方法。每个工具必须定义 `name`（名称）、`description`（描述）和 `_run`（执行方法）。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/base_tool.py\nname: str = \"tool_name\"\ndescription: str = \"A tool that...\"\n```\n\n### FileReadTool 文件读取工具\n\n`FileReadTool` 用于读取文件内容，支持按行范围读取和指定起始行。\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|-----|\n| file_path | str | 否 | 要读取的文件路径 |\n| start_line | int | 否 | 起始行号（从1开始） |\n| line_count | int | 否 | 要读取的行数 |\n\n```python\n# 初始化工具\ntool = FileReadTool(file_path=\"/path/to/file.txt\")\n\n# 读取整个文件\ncontent = tool.run()\n\n# 按行范围读取\ncontent = tool.run(start_line=100, line_count=50)\n```\n\n### FileWriterTool 文件写入工具\n\n`FileWriterTool` 用于将内容写入文件，支持自动创建目录。\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|-----|\n| filename | str | 是 | 要创建或覆盖的文件名 |\n| content | str | 是 | 要写入的内容 |\n| directory | str | 否 | 目标目录，默认为当前目录 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md\nfrom crewai_tools import FileWriterTool\n\nfile_writer = FileWriterTool()\nresult = file_writer._run('example.txt', '测试内容', 'test_directory')\n```\n\n### RagTool 检索增强生成工具\n\n`RagTool` 用于从文件、目录或网页加载内容构建知识库，支持 RAG 检索场景。\n\n| 方法 | 参数 | 说明 |\n|-----|------|-----|\n| from_file | path: str | 从单个文件加载内容 |\n| from_directory | path: str | 从目录加载所有文件 |\n| from_web_page | url: str | 从网页加载内容 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/rag/README.md\nfrom crewai_tools.tools.rag_tool import RagTool\n\n# 从文件加载\nrag_tool = RagTool().from_file('path/to/file.txt')\n\n# 从目录加载\nrag_tool = RagTool().from_directory('path/to/directory')\n\n# 从网页加载\nrag_tool = RagTool().from_web_page('https://example.com')\n```\n\n### 搜索工具集\n\ncrewai_tools 提供了多种搜索工具，用于 Agent 执行网络搜索任务。\n\n#### SerplySearchTool\n\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| proxy_location | str | 代理位置代码（如 JP、GB、DE） |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/serply_api_tool/README.md\nfrom crewai_tools import SerplyWebSearchTool\n\nsearch_tool = SerplyWebSearchTool()\n```\n\n#### LinkupSearchTool\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|--------|-----|\n| query | str | - | 搜索关键词 |\n| depth | str | \"standard\" | 搜索深度 |\n| output_type | str | \"searchResults\" | 输出类型 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/linkup/README.md\nfrom crewai_tools import LinkupSearchTool\n\nlinkup_tool = LinkupSearchTool()\nresponse = linkup_tool._run(\n query=\"Women Nobel Prize Physics\",\n depth=\"standard\",\n output_type=\"searchResults\"\n)\n```\n\n#### SerplyScholarSearchTool\n\n学术搜索工具，用于检索学术论文和文献。\n\n```python\nfrom crewai_tools import SerplyScholarSearchTool\n\nscholar_tool = SerplyScholarSearchTool()\nscholar_tool = SerplyScholarSearchTool(proxy_location=\"GB\")\n```\n\n## MCP 协议集成\n\n### MCP 概述\n\nMCP（Model Context Protocol）是一种标准化的协议，允许 AI 模型与外部工具和服务进行交互。CrewAI 通过 MCP 集成，可以调用远程 MCP 服务器提供的工具。\n\n### MCP 架构图\n\n```mermaid\ngraph LR\n subgraph \"CrewAI 运行时\"\n A[Agent] --> B[ToolCalling]\n B --> C[MCPToolResolver]\n C --> D[MCPClient]\n end\n \n subgraph \"MCP 协议层\"\n D <-->|JSON-RPC| E[MCP Server]\n end\n \n subgraph \"外部服务\"\n E --> F[文件系统工具]\n E --> G[数据库工具]\n E --> H[API 工具]\n end\n```\n\n### MCP 客户端\n\n`MCPClient` 负责建立和管理与 MCP 服务器的连接，处理协议握手、消息序列化和工具调用路由。\n\n```python\n# 资料来源：lib/crewai/src/crewai/mcp/client.py\nclass MCPClient:\n def __init__(\n self,\n server_url: str,\n api_key: Optional[str] = None,\n timeout: int = 60\n ):\n \"\"\"初始化 MCP 客户端\"\"\"\n```\n\n### MCP 工具解析器\n\n`MCPToolResolver` 负责将 MCP 服务器提供的工具 schema 转换为 CrewAI 可识别的工具格式，并处理工具调用请求。\n\n```python\n# 资料来源：lib/crewai/src/crewai/mcp/tool_resolver.py\nclass MCPToolResolver:\n def resolve_tools(self) -> List[StructuredTool]:\n \"\"\"解析 MCP 服务器提供的工具列表\"\"\"\n \n def call_tool(self, tool_name: str, arguments: dict) -> Any:\n \"\"\"调用指定工具并返回结果\"\"\"\n```\n\n### MCP 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ToolCalling\n participant MCPToolResolver\n participant MCPClient\n participant MCPServer\n \n Agent->>ToolCalling: 请求执行工具\n ToolCalling->>MCPToolResolver: 查找工具定义\n MCPToolResolver->>MCPClient: 发起工具调用\n MCPClient->>MCPServer: 发送 JSON-RPC 请求\n MCPServer-->>MCPClient: 返回执行结果\n MCPClient-->>MCPToolResolver: 解析响应\n MCPToolResolver-->>ToolCalling: 返回结构化结果\n ToolCalling-->>Agent: 返回工具执行结果\n```\n\n## 工具注册与调用\n\n### 工具调用机制\n\n`ToolCalling` 模块负责管理工具的注册、查找和执行流程。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/tool_calling.py\nclass ToolCalling:\n def register_tool(self, tool: StructuredTool) -> None:\n \"\"\"注册新工具\"\"\"\n \n def execute_tool(self, tool_name: str, **kwargs) -> Any:\n \"\"\"执行指定工具\"\"\"\n```\n\n### StructuredTool 结构化工具\n\n`StructuredTool` 扩展了 `BaseTool`，使用 Pydantic Schema 进行参数验证和类型检查。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/structured_tool.py\nfrom pydantic import BaseModel\n\nclass StructuredTool(BaseTool):\n args_schema: type[BaseModel]\n \n def _run(self, **kwargs) -> Any:\n \"\"\"执行工具逻辑\"\"\"\n```\n\n### Agent 中使用工具\n\n```python\n# 资料来源：lib/cli/src/crewai_cli/templates/AGENTS.md\nfrom crewai import Agent\nfrom crewai_tools import SerperDevTool\n\nresearcher = Agent(\n role=\"Senior Researcher\",\n goal=\"Uncover cutting-edge developments in {topic}\",\n backstory=\"An expert in online information retrieval...\",\n tools=[SerperDevTool()],\n verbose=True\n)\n```\n\n## 自定义工具开发\n\n### 工具开发模板\n\ncrewai 提供了标准化的工具开发模板，位于 `lib/cli/src/crewai_cli/templates/tool/`。\n\n```bash\ncrewai tool publish {{tool_name}}\ncrewai tool install {{tool_name}}\n```\n\n### 工具规范定义\n\n工具的元数据和参数规范定义在 `tool.specs.json` 中。\n\n```json\n// 资料来源：lib/crewai-tools/src/crewai_tools/tool.specs.json\n{\n \"name\": \"tool_name\",\n \"description\": \"Tool description\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {...}\n }\n}\n```\n\n### 工具开发示例\n\n```python\n# 创建自定义工具\nfrom crewai.tools.base_tool import BaseTool\nfrom pydantic import BaseModel\n\nclass MyToolInput(BaseModel):\n query: str\n limit: int = 10\n\nclass MyTool(BaseTool):\n name: str = \"my_custom_tool\"\n description: str = \"A custom tool for...\"\n args_schema: type[BaseModel] = MyToolInput\n \n def _run(self, query: str, limit: int = 10) -> str:\n # 工具执行逻辑\n return f\"Result for {query}\"\n```\n\n## 工具配置与模型自定义\n\n### LLM 和 Embedder 配置\n\n大多数工具支持自定义 LLM 和 Embedder 模型。\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md\nfrom crewai_tools import CodeDocsSearchTool\n\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n temperature=0.5,\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n### 支持的 LLM 提供商\n\n| 提供商 | 配置值 | 说明 |\n|-------|--------|-----|\n| OpenAI | openai | GPT 系列模型 |\n| Anthropic | anthropic | Claude 系列模型 |\n| Google | google | Gemini 系列模型 |\n| Ollama | ollama | 本地 LLM |\n| Llama2 | llama2 | Meta Llama2 |\n\n## 工作流集成\n\n### Crew 中使用工具\n\n```python\n# 资料来源：lib/cli/src/crewai_cli/templates/AGENTS.md\nfrom crewai import Agent, Crew, Task\nfrom crewai.project import CrewBase, agent, crew, task\n\n@CrewBase\nclass ResearchCrew:\n agents_config = \"config/agents.yaml\"\n tasks_config = \"config/tasks.yaml\"\n \n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config[\"researcher\"],\n tools=[SerperDevTool()],\n verbose=True,\n )\n```\n\n### Task 中配置工具\n\n```yaml\n# 在 tasks.yaml 中配置任务\nresearch_task:\n description: >\n Research the latest developments in {topic}\n expected_output: >\n A comprehensive report with sources and implications.\n agent: researcher\n tools: [search_tool]\n output_file: output/research.md\n```\n\n## 最佳实践\n\n### 工具选择策略\n\n1. **任务匹配**：根据任务类型选择最合适的工具\n2. **性能考虑**：优先使用轻量级工具，减少 API 调用开销\n3. **可靠性**：选择有稳定维护的官方工具\n4. **安全性**：敏感操作使用本地工具而非远程 API\n\n### 错误处理\n\n```python\ntry:\n result = tool._run(param=\"value\")\nexcept ToolExecutionError as e:\n logger.error(f\"Tool execution failed: {e}\")\n # 降级处理或重试逻辑\n```\n\n### 工具链组合\n\n多个工具可以组合使用实现复杂工作流：\n\n```python\n# 搜索 + 内容转换\nfrom crewai import Agent\nfrom crewai_tools import SerplyWebSearchTool, SerplyWebpageToMarkdownTool\n\nsearch_tool = SerplyWebSearchTool()\nconvert_to_markdown = SerplyWebpageToMarkdownTool()\n\nresearcher = Agent(\n role='Senior Researcher',\n goal='Uncover groundbreaking technologies in {topic}',\n tools=[search_tool, convert_to_markdown]\n)\n```\n\n## 总结\n\nCrewAI 的工具系统通过模块化的设计，为 AI Agent 提供了强大的外部能力扩展能力。内置工具覆盖了文件操作、网络搜索、RAG 检索等常见场景，而 MCP 协议集成则允许与任意支持 MCP 的外部服务进行交互。通过统一的工具调用接口和 Pydantic 参数校验机制，开发者可以快速构建功能丰富的多 Agent 应用。\n\n---\n\n\n\n## MCP 与 A2A 协议\n\n### 相关页面\n\n相关主题：[工具系统与 MCP 集成](#tools), [Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/mcp/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/__init__.py)\n- [lib/crewai/src/crewai/mcp/transports/stdio.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/stdio.py)\n- [lib/crewai/src/crewai/mcp/transports/sse.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/sse.py)\n- [lib/crewai/src/crewai/mcp/transports/http.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/http.py)\n- [lib/crewai/src/crewai/a2a/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/__init__.py)\n- [lib/crewai/src/crewai/a2a/types.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/types.py)\n- [lib/crewai/src/crewai/a2a/utils/delegation.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/utils/delegation.py)\n \n\n# MCP 与 A2A 协议\n\n## 概述\n\n在 CrewAI 框架中，**MCP (Model Context Protocol)** 和 **A2A (Agent-to-Agent)** 是两个核心的通信协议，分别用于 Agent 与外部工具服务的连接以及 Agent 之间的互操作。这两个协议共同构成了 CrewAI 多智能体系统的通信基础设施，使 Agent 能够与外部系统进行无缝集成和协作。\n\n## 协议架构总览\n\n```mermaid\ngraph TB\n subgraph \"CrewAI 通信层\"\n A1[\"Agent 1\"] --> A2[\"Agent 2\"]\n A1 --> A3[\"Agent 3\"]\n A2 --> A3\n end\n \n subgraph \"A2A 协议层\"\n A2A[\"Agent-to-Agent 通信\"]\n DEL[\"委派工具\"]\n TYPES[\"类型定义\"]\n end\n \n subgraph \"MCP 协议层\"\n MCP[\"Model Context Protocol\"]\n STDIO[\"stdio 传输\"]\n SSE[\"SSE 传输\"]\n HTTP[\"HTTP 传输\"]\n end\n \n subgraph \"外部服务\"\n TOOL[\"外部工具服务\"]\n API[\"第三方 API\"]\n end\n \n A1 -.-> A2A\n A2 -.-> A2A\n A2A -.-> DEL\n MCP -.-> TOOL\n MCP -.-> STDIO\n MCP -.-> SSE\n MCP -.-> HTTP\n```\n\n## MCP 协议 (Model Context Protocol)\n\nMCP 协议是 CrewAI 用于与外部工具和服务进行通信的标准协议。它定义了 Agent 如何连接到外部工具、发送请求并接收响应。CrewAI 的 MCP 实现支持多种传输方式，以适应不同的部署场景。\n\n### MCP 模块结构\n\n```mermaid\ngraph TD\n MCP[\"crewai.mcp 模块\"]\n INIT[\"__init__.py
MCP 包初始化\"]\n \n subgraph \"传输层 (transports)\"\n STDIO[\"stdio.py
标准输入输出传输\"]\n SSE[\"sse.py
Server-Sent Events 传输\"]\n HTTP[\"http.py
HTTP 请求传输\"]\n end\n \n MCP --> INIT\n INIT --> STDIO\n INIT --> SSE\n INIT --> HTTP\n```\n\n### 传输方式详解\n\n#### stdio 传输\n\nstdio 传输是 MCP 协议最常用的传输方式之一，特别适用于本地进程通信和命令行工具集成。通过标准输入输出流进行数据交换，具有低延迟和简单可靠的特点。\n\n主要特点：\n\n- **同步通信**：使用标准输入输出进行同步消息交换\n- **进程管理**：适合启动和管理本地子进程\n- **错误处理**：内置进程错误捕获和日志记录机制\n- **超时控制**：支持请求超时配置\n\n#### SSE 传输\n\nServer-Sent Events (SSE) 传输适用于需要服务器推送场景的 MCP 通信。它允许服务器主动向客户端发送事件流，特别适合长时间运行的任务和实时状态更新。\n\n使用场景：\n\n- 实时日志流推送\n- 长时间任务的进度更新\n- 异步操作的完成通知\n\n#### HTTP 传输\n\nHTTP 传输是最通用的 MCP 通信方式，适用于与基于 REST API 的外部服务进行交互。它支持完整的 HTTP 协议特性，包括认证、会话管理和请求/响应模式。\n\n### MCP 配置参数\n\n| 参数名称 | 类型 | 说明 | 默认值 |\n|---------|------|------|--------|\n| `timeout` | int | 请求超时时间（秒） | 60 |\n| `max_retries` | int | 最大重试次数 | 3 |\n| `retry_delay` | int | 重试间隔时间（秒） | 1 |\n| `headers` | dict | HTTP 请求头 | {} |\n\n## A2A 协议 (Agent-to-Agent)\n\nA2A 协议是 CrewAI 框架中用于 Agent 之间进行通信和协作的协议。它定义了 Agent 如何相互发送消息、委派任务、共享状态和协调工作流程。A2A 协议的核心目标是实现多 Agent 系统中的无缝协作。\n\n### A2A 核心组件\n\n```mermaid\ngraph LR\n subgraph \"A2A 协议栈\"\n A2A_INIT[\"__init__.py
A2A 包初始化\"]\n TYPES[\"types.py
类型定义与数据模型\"]\n DELEG[\"delegation.py
任务委派工具\"]\n end\n \n subgraph \"A2A 类型体系\"\n REQ[\"请求类型\"]\n RESP[\"响应类型\"]\n TASK[\"任务类型\"]\n STATE[\"状态类型\"]\n end\n \n subgraph \"A2A 工具集\"\n DEL_TOOL[\"委派工具\"]\n ROUTING[\"路由工具\"]\n end\n \n A2A_INIT --> TYPES\n A2A_INIT --> DELEG\n TYPES --> REQ\n TYPES --> RESP\n TYPES --> TASK\n TYPES --> STATE\n DELEG --> DEL_TOOL\n DELEG --> ROUTING\n```\n\n### A2A 类型系统\n\nA2A 协议定义了一套完整的类型系统，用于描述 Agent 通信中的各种数据结构。这些类型包括请求、响应、任务描述、状态信息等。类型系统的设计遵循以下原则：\n\n**设计原则：**\n\n- **类型安全**：使用 Python 类型注解确保编译时和运行时类型检查\n- **可扩展性**：支持通过继承和组合扩展新类型\n- **序列化兼容**：支持 JSON 等常见序列化格式\n\n### 任务委派机制\n\n任务委派是 A2A 协议的核心功能之一，允许一个 Agent 将任务委托给另一个 Agent 执行。委派过程涉及多个步骤，包括任务描述构建、目标 Agent 选择、执行状态跟踪和结果收集。\n\n```mermaid\nsequenceDiagram\n participant Agent_A as Agent A (发起者)\n participant A2A as A2A 协议层\n participant DEL as 委派工具\n participant Agent_B as Agent B (执行者)\n \n Agent_A->>A2A: 创建任务委派请求\n A2A->>DEL: 验证委派权限\n DEL->>DEL: 检查 Agent B 可用性\n DEL->>Agent_B: 发送任务描述\n Agent_B->>Agent_B: 执行任务\n Agent_B-->>DEL: 返回任务结果\n DEL-->>A2A: 格式化响应\n A2A-->>Agent_A: 返回执行结果\n```\n\n### 委派工具 (delegation.py)\n\n`delegation.py` 模块提供了 A2A 协议中任务委派的核心实现。该模块包含以下主要功能：\n\n| 功能 | 说明 |\n|------|------|\n| `delegate_task()` | 将任务委派给指定的 Agent |\n| `check_agent_availability()` | 检查目标 Agent 是否可用 |\n| `track_delegation_status()` | 跟踪委派任务的状态 |\n| `collect_delegation_result()` | 收集委派任务的结果 |\n\n### A2A 消息流\n\n```mermaid\ngraph LR\n subgraph \"消息生命周期\"\n CREATE[\"创建消息\"] --> SERIALIZE[\"序列化\"]\n SERIALIZE --> SEND[\"发送\"]\n SEND --> RECEIVE[\"接收\"]\n RECEIVE --> DESERIALIZE[\"反序列化\"]\n DESERIALIZE --> PROCESS[\"处理\"]\n PROCESS --> RESPOND[\"响应\"]\n RESPOND --> COMPLETE[\"完成\"]\n end\n \n subgraph \"消息类型\"\n REQ[\"请求消息\"]\n RESP[\"响应消息\"]\n EVENT[\"事件消息\"]\n ERROR[\"错误消息\"]\n end\n \n CREATE -.-> REQ\n PROCESS -.-> RESP\n PROCESS -.-> EVENT\n PROCESS -.-> ERROR\n```\n\n## 协议比较与选择\n\n| 特性 | MCP | A2A |\n|------|-----|-----|\n| **主要用途** | Agent 与外部工具/服务通信 | Agent 之间相互通信 |\n| **传输方式** | stdio, SSE, HTTP | 内部消息传递 |\n| **协议层次** | 基础设施层 | 应用层 |\n| **典型场景** | 工具调用、数据获取 | 任务委派、协作处理 |\n| **状态管理** | 无状态请求/响应 | 有状态的对话上下文 |\n\n## 实际应用示例\n\n### MCP 使用场景\n\n1. **文件操作**：读取本地文件、写入日志\n2. **网络请求**：调用外部 API、获取网页内容\n3. **数据库访问**：查询和更新数据存储\n4. **搜索功能**：文档搜索、网络搜索\n\n### A2A 使用场景\n\n1. **复杂任务分解**：将复杂任务分解为多个子任务\n2. **专家咨询**：向特定领域的 Agent 请求专业知识\n3. **协作验证**：多个 Agent 协作验证结果\n4. **负载均衡**：根据 Agent 负载分配任务\n\n## 最佳实践\n\n### MCP 最佳实践\n\n- **连接复用**：对于频繁调用的服务，保持 MCP 连接复用\n- **超时设置**：根据任务性质合理设置超时时间\n- **错误重试**：实现指数退避的重试机制\n- **资源清理**：确保使用完毕后正确关闭连接\n\n### A2A 最佳实践\n\n- **任务粒度**：合理划分任务粒度，避免过度委派\n- **状态同步**：使用适当的状态同步机制保持 Agent 间一致性\n- **超时处理**：设置合理的任务执行超时时间\n- **结果聚合**：建立有效的结果聚合和处理机制\n\n## 安全考虑\n\n| 安全维度 | MCP | A2A |\n|----------|-----|-----|\n| **认证** | API Key / OAuth | Agent 身份验证 |\n| **授权** | 工具级别权限控制 | 任务委派权限验证 |\n| **传输加密** | HTTPS 支持 | 内部通信加密 |\n| **输入验证** | 参数校验 | 消息格式验证 |\n\n## 总结\n\nMCP 和 A2A 协议共同构成了 CrewAI 多智能体系统的通信基础。MCP 协议侧重于 Agent 与外部世界的连接，提供了多种灵活的传输方式；A2A 协议则专注于 Agent 之间的协作，实现了任务委派、状态共享和协调工作等功能。理解这两个协议的设计和使用方法，对于构建高效、可靠的多智能体系统至关重要。\n\n通过合理地结合使用 MCP 和 A2A 协议，开发者可以构建出功能强大、架构灵活的多智能体应用，实现复杂任务的自动化处理和智能协作。\n\n---\n\n\n\n## 记忆与知识管理系统\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/memory/unified_memory.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/unified_memory.py)\n- [lib/crewai/src/crewai/memory/recall_flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/recall_flow.py)\n- [lib/crewai/src/crewai/memory/storage/lancedb_storage.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/storage/lancedb_storage.py)\n- [lib/crewai/src/crewai/knowledge/knowledge.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/knowledge.py)\n- [lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py)\n- [lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py)\n- [lib/crewai/src/crewai/knowledge/source/crew_docling_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/crew_docling_source.py)\n \n\n# 记忆与知识管理系统\n\nCrewAI 框架提供了一套完整的**记忆与知识管理系统**，用于支持多代理系统的上下文保持、跨会话学习和领域知识增强。该系统通过统一记忆模块和知识来源模块协同工作，使代理能够在长期运行中积累信息、保持状态连续性，并利用外部知识库进行推理。\n\n---\n\n## 系统概述\n\n### 设计目标\n\nCrewAI 的记忆与知识管理系统主要解决以下问题：\n\n| 问题领域 | 解决方案 |\n|---------|---------|\n| 上下文保持 | 统一记忆（Unified Memory）存储对话历史和任务执行记录 |\n| 跨会话学习 | 向量化存储支持语义检索，实现长期信息积累 |\n| 领域知识增强 | 知识来源（Knowledge Sources）模块加载外部文档 |\n| 代理状态管理 | 实体记忆和短时/长时记忆分类管理 |\n\n### 架构概览\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[Crew 实例] --> B[统一记忆模块]\n A --> C[知识来源模块]\n end\n \n subgraph \"记忆系统 Memory\"\n B --> D[短时记忆 Short-term]\n B --> E[长时记忆 Long-term]\n B --> F[实体记忆 Entities]\n B --> G[知识记忆 Knowledge]\n end\n \n subgraph \"存储层 Storage\"\n D --> H[内存存储 In-Memory]\n E --> I[向量数据库 LanceDB]\n F --> I\n G --> I\n end\n \n subgraph \"知识来源 Knowledge Sources\"\n C --> J[PDF 文档源]\n C --> K[CSV 数据源]\n C --> L[DOCling 源]\n end\n \n I --> M[向量嵌入模型]\n```\n\n---\n\n## 统一记忆模块\n\n统一记忆模块（Unified Memory）是 CrewAI 记忆系统的核心组件，负责协调管理不同类型的记忆存储。\n\n### 记忆类型分类\n\nCrewAI 将记忆划分为四种类型，分别处理不同维度的信息：\n\n| 记忆类型 | 用途 | 生命周期 | 存储方式 |\n|---------|------|---------|---------|\n| **短时记忆 (Short-term)** | 当前会话内的对话上下文 | 会话内 | 内存存储 |\n| **长时记忆 (Long-term)** | 历史会话积累的信息 | 持久化 | LanceDB 向量存储 |\n| **实体记忆 (Entities)** | 提取的实体信息和实体关系 | 可配置 | LanceDB 向量存储 |\n| **知识记忆 (Knowledge)** | 领域知识库检索结果 | 持久化 | LanceDB 向量存储 |\n\n### 记忆检索流程\n\n```mermaid\ngraph LR\n A[用户输入] --> B[Recall Flow]\n B --> C[短时记忆查询]\n B --> D[长时记忆查询]\n B --> E[实体记忆查询]\n B --> F[知识记忆查询]\n C --> G[相关记忆聚合]\n D --> G\n E --> G\n F --> G\n G --> H[增强上下文]\n H --> I[LLM 推理]\n```\n\n### 核心 API\n\n统一记忆模块提供以下核心方法：\n\n```python\n# 记忆写入\nmemory.insert(content: str, metadata: dict = None)\n\n# 记忆检索\nresults = memory.search(query: str, limit: int = 10)\n\n# 记忆重置\nmemory.reset(memory_type: str = \"all\")\n```\n\n---\n\n## 存储层实现\n\n### LanceDB 向量存储\n\nLanceDB 是 CrewAI 默认的向量数据库，用于持久化存储长时记忆、实体记忆和知识记忆。\n\n**核心特性**：\n\n| 特性 | 说明 |\n|-----|------|\n| 向量索引 | 支持 HNSW、FLAT 等索引类型 |\n| 相似度检索 | 基于余弦相似度的语义搜索 |\n| 元数据过滤 | 支持基于元数据的精确过滤 |\n| 持久化存储 | 本地文件系统存储，无需独立服务 |\n\n**配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `vector_dimension` | int | 1536 | 向量嵌入维度 |\n| `storage_path` | str | ./data/memory | 存储路径 |\n| `index_type` | str | \"hnsw\" | 索引类型 |\n\n### 检索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户查询\n participant M as Memory 模块\n participant V as Vector Store\n participant E as Embedding Model\n \n U->>M: search(query)\n M->>E: 生成查询向量\n E-->>M: query_vector\n M->>V: 相似度搜索\n V-->>M: 相关结果\n M->>M: 结果聚合与排序\n M-->>U: 检索结果\n```\n\n---\n\n## 知识来源模块\n\n知识来源（Knowledge Sources）模块允许 CrewAI 从外部文档中加载领域知识，为代理提供额外的参考资料。\n\n### 支持的文档类型\n\n| 文档类型 | 处理器 | 依赖库 |\n|---------|-------|-------|\n| PDF | `PDFKnowledgeSource` | pdfplumber, pypdf |\n| CSV | `CSVKnowledgeSource` | pandas |\n| DOCling | `CrewDoclingSource` | crewdocling |\n\n### 知识加载流程\n\n```mermaid\ngraph TD\n A[文档文件] --> B[解析器选择]\n B --> C{文档类型}\n C -->|PDF| D[PDF 解析器]\n C -->|CSV| E[CSV 解析器]\n C -->|DOCling| F[DOCling 解析器]\n \n D --> G[文本分块]\n E --> G\n F --> G\n \n G --> H[向量化处理]\n H --> I[存入向量存储]\n I --> J[可被代理检索]\n```\n\n### 使用示例\n\n```python\nfrom crewai import Agent, Task, Crew\nfrom crewai.knowledge import PDFKnowledgeSource\n\n# 加载知识来源\npdf_source = PDFKnowledgeSource(\n file_path=\"./documents/manual.pdf\",\n chunk_size=1000,\n chunk_overlap=200\n)\n\n# 创建代理并关联知识来源\nagent = Agent(\n role=\"技术顾问\",\n goal=\"基于知识库回答用户问题\",\n backstory=\"你是一个熟悉产品文档的专家\",\n knowledge_sources=[pdf_source]\n)\n\n# 创建任务\ntask = Task(\n description=\"回答用户关于产品功能的问题\",\n expected_output=\"基于文档的详细回答\",\n agent=agent\n)\n```\n\n---\n\n## CLI 记忆管理命令\n\nCrewAI CLI 提供了完整的记忆管理命令，用于重置和清理不同类型的记忆存储。\n\n### 命令列表\n\n| 命令 | 说明 | 适用范围 |\n|-----|------|---------|\n| `crewai reset-memories -a` | 重置所有记忆 | 全部记忆类型 |\n| `crewai reset-memories -s` | 重置短时记忆 | 当前会话 |\n| `crewai reset-memories -l` | 重置长时记忆 | 历史积累 |\n| `crewai reset-memories -e` | 重置实体记忆 | 实体信息 |\n| `crewai reset-memories -kn` | 重置知识记忆 | 知识来源 |\n| `crewai reset-memories -akn` | 重置代理知识 | 单代理知识 |\n\n### 使用示例\n\n```bash\n# 重置所有记忆（用于全新开始）\ncrewai reset-memories -a\n\n# 仅清理长时记忆（保留短时会话）\ncrewai reset-memories -l\n\n# 清理特定代理的知识\ncrewai reset-memories -akn\n```\n\n---\n\n## 最佳实践\n\n### 何时启用记忆\n\n| 场景 | 推荐配置 |\n|-----|---------|\n| 需要跨会话保持上下文 | 启用长时记忆 |\n| 当前任务依赖历史信息 | 启用短时+长时记忆 |\n| 领域特定问答 | 配置知识来源 |\n| 实体关系抽取 | 启用实体记忆 |\n\n### 配置建议\n\n```python\nfrom crewai import Crew\n\ncrew = Crew(\n agents=[...],\n tasks=[...],\n memory=True, # 启用统一记忆\n memory_config={\n \"short_term\": True,\n \"long_term\": True,\n \"entities\": True,\n \"knowledge\": True\n }\n)\n```\n\n### 性能优化\n\n1. **合理设置检索数量**：避免返回过多无关记忆，`limit` 参数建议设置为 5-10\n2. **知识分块策略**：大文档建议设置 `chunk_size=1000`, `chunk_overlap=200`\n3. **定期清理**：长时间运行的任务建议定期执行 `reset-memories -l`\n\n---\n\n## 源码文件索引\n\n| 模块 | 文件路径 | 主要功能 |\n|-----|---------|---------|\n| 统一记忆 | `lib/crewai/src/crewai/memory/unified_memory.py` | 记忆类型协调与聚合 |\n| 检索流程 | `lib/crewai/src/crewai/memory/recall_flow.py` | 记忆检索与上下文增强 |\n| 向量存储 | `lib/crewai/src/crewai/memory/storage/lancedb_storage.py` | LanceDB 持久化实现 |\n| 知识基类 | `lib/crewai/src/crewai/knowledge/knowledge.py` | 知识来源抽象 |\n| PDF 源 | `lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py` | PDF 文档处理 |\n| CSV 源 | `lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py` | CSV 数据处理 |\n| Docling 源 | `lib/crewai/src/crewai/knowledge/source/crew_docling_source.py` | Docling 格式支持 |\n\n---\n\n## 总结\n\nCrewAI 的记忆与知识管理系统通过统一记忆模块和知识来源模块的双层架构，实现了：\n\n- **上下文连续性**：短时记忆保持会话状态，长时记忆实现跨会话学习\n- **语义检索能力**：基于向量数据库的相似度搜索，快速定位相关信息\n- **知识增强**：支持多种文档格式的知识加载，丰富代理的推理依据\n- **灵活的 CLI 管理**：提供完整的命令行工具进行记忆维护\n\n该系统是 CrewAI 多代理协作能力的重要支撑，尤其适用于需要长期运行和知识积累的复杂任务场景。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：crewAIInc/crewAI\n\n摘要：发现 23 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine。\n\n## 1. 安装坑 · 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c38215ebb04a4fbc6e7c6d2fdb2469 | https://github.com/crewAIInc/crewAI/issues/5708 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 运行坑 · 来源证据：[BUG] Wrong code in document\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] Wrong code in document\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_390380af45524e959d558b160597b38b | https://github.com/crewAIInc/crewAI/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：[FEATURE] Enhance the document about @persisit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Enhance the document about @persisit\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_effef000d4cf47a892f17850aa033610 | https://github.com/crewAIInc/crewAI/issues/5372 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_858a1a8bead2456289d686ec0d2d802c | https://github.com/crewAIInc/crewAI/issues/4877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `crewai` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:710601088 | https://github.com/crewAIInc/crewAI | repo=crewai; install=skills\n\n## 6. 安装坑 · 来源证据：1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcfa2a852812414a82683392c2888795 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：1.14.4a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0de86b993ffa4d9298726daa189abf49 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：1.14.5a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.5a4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6db6cd94b6ef4bffa23da215458565b4 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Scans the client database to extract existing policy details.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Scans the client database to extract existing policy details.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8201c73155314e67801bd0b81ea9820d | https://github.com/crewAIInc/crewAI/issues/5760 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:710601088 | https://github.com/crewAIInc/crewAI | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：1.14.5a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：1.14.5a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4094bb55c234f1581b9879efd4994c6 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff4d292bd8984a039527502ef51aed98 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：1.14.5a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e5616e4bf1f47f59e10e83c1849c86a | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：1.14.5a3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba25d089d674407d83a29ec4caff6284 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Question: integration path for Agent Threat Rules detection in crewai/security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Question: integration path for Agent Threat Rules detection in crewai/security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_05e39d8c109f4ed0a2974d448468229f | https://github.com/crewAIInc/crewAI/issues/5763 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_028fe9ebbcc943f5a7134e08d0ed9450 | https://github.com/crewAIInc/crewAI/issues/5762 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6b9a787eb544f098525817b61476c11 | https://github.com/crewAIInc/crewAI/issues/5728 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：[FEATURE] Tool to add input_files\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Tool to add input_files\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca4885df9ee49459ce8502e94d11f50 | https://github.com/crewAIInc/crewAI/issues/5758 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | release_recency=unknown\n\n\n",
"markdown_key": "crewai",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:710601088",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/crewAIInc/crewAI"
},
{
"evidence_id": "art_54a9d78a76654ece9449751eb989967e",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/crewAIInc/crewAI#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "crewAI 说明书",
"toc": [
"https://github.com/crewAIInc/crewAI 项目说明书",
"目录",
"crewAI 简介与快速入门",
"什么是 crewAI？",
"安装与配置",
"创建第一个 Crew",
"集成工具生态",
"从文件加载",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "ba523f46c06289074b0267ab2689571398c7cc7b",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/enterprise-api.en.yaml",
"docs/reo-tracking.js",
"docs/enterprise-api.pt-BR.yaml",
"docs/enterprise-api.base.yaml",
"docs/index.mdx",
"docs/common-room-tracking.js",
"docs/docs.json",
"docs/enterprise-api.ko.yaml",
"docs/pt-BR/telemetry.mdx",
"docs/pt-BR/index.mdx",
"docs/pt-BR/installation.mdx",
"docs/pt-BR/quickstart.mdx",
"docs/pt-BR/changelog.mdx",
"docs/pt-BR/introduction.mdx",
"docs/pt-BR/skills.mdx",
"docs/ar/telemetry.mdx",
"docs/ar/index.mdx",
"docs/ar/installation.mdx",
"docs/ar/quickstart.mdx",
"docs/ar/changelog.mdx",
"docs/ar/introduction.mdx",
"docs/ar/skills.mdx",
"docs/en/telemetry.mdx",
"docs/en/index.mdx",
"docs/en/installation.mdx",
"docs/en/quickstart.mdx",
"docs/en/changelog.mdx",
"docs/en/introduction.mdx",
"docs/en/skills.mdx",
"docs/ko/telemetry.mdx",
"docs/ko/index.mdx",
"docs/ko/installation.mdx",
"docs/ko/quickstart.mdx",
"docs/ko/changelog.mdx",
"docs/ko/introduction.mdx",
"docs/ko/skills.mdx",
"docs/pt-BR/mcp/sse.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# crewai - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 crewai 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `/plugin marketplace add crewAIInc/skills` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `/plugin install crewai-skills@crewai-plugins` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx skills add crewaiinc/skills` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`, `lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`, `lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2947\n- 重要文件覆盖：40/2947\n- 证据索引条目：83\n- 角色 / Skill 条目：3\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 crewai 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 crewai 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 crewai 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 3 个角色 / Skill / 项目文档条目。\n\n- **Invalid--Name**（skill）：This skill has an invalid name. 激活提示：当用户任务与“Invalid--Name”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md`\n- **minimal-skill**（skill）：A minimal skill with only required fields. 激活提示：当用户任务与“minimal-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md`\n- **valid-skill**（skill）：A complete test skill with all optional directories. 激活提示：当用户任务与“valid-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 83 条证据。\n\n- **Fast and Flexible Multi-Agent Automation Framework**（documentation）：Homepage · Docs · Start Cloud Trial · Blog · Forum 证据：`README.md`\n- **crewai-cli**（documentation）：CLI for CrewAI — scaffold, run, deploy and manage AI agent crews without installing the full framework. 证据：`lib/cli/README.md`\n- **AGENTS.md — CrewAI Reference for AI Coding Assistants**（documentation）：AGENTS.md — CrewAI Reference for AI Coding Assistants 证据：`lib/cli/src/crewai_cli/templates/AGENTS.md`\n- **{{crew name}} Crew**（documentation）：Welcome to the {{crew name}} Crew project, powered by crewAI https://crewai.com . This template is designed to help you set up a multi-agent AI system with ease, leveraging the powerful and flexible framework provided by crewAI. Our goal is to enable your agents to collaborate effectively on complex tasks, maximizing their collective intelligence and capabilities. 证据：`lib/cli/src/crewai_cli/templates/crew/README.md`\n- **{{crew name}} Crew**（documentation）：Welcome to the {{crew name}} Crew project, powered by crewAI https://crewai.com . This template is designed to help you set up a multi-agent AI system with ease, leveraging the powerful and flexible framework provided by crewAI. Our goal is to enable your agents to collaborate effectively on complex tasks, maximizing their collective intelligence and capabilities. 证据：`lib/cli/src/crewai_cli/templates/flow/README.md`\n- **{{folder name}}**（documentation）：{{folder name}} is a CrewAI Tool. This template is designed to help you create custom tools to power up your crews. 证据：`lib/cli/src/crewai_cli/templates/tool/README.md`\n- **crewai-core**（documentation）：Shared utilities used by both crewai and crewai-cli : version lookup, storage paths, user-data helpers, telemetry, and the printer. 证据：`lib/crewai-core/README.md`\n- **crewai-files**（documentation）：File handling utilities for CrewAI multimodal inputs. 证据：`lib/crewai-files/README.md`\n- **CrewAI Tools**（documentation）：! Logo of crewAI, two people rowing on a boat ./assets/crewai logo.png 证据：`lib/crewai-tools/README.md`\n- **BedrockInvokeAgentTool**（documentation）：The BedrockInvokeAgentTool enables CrewAI agents to invoke Amazon Bedrock Agents and leverage their capabilities within your workflows. 证据：`lib/crewai-tools/src/crewai_tools/aws/bedrock/agents/README.md`\n- **AWS Bedrock Browser Tools**（documentation）：This toolkit provides a set of tools for interacting with web browsers through AWS Bedrock Browser. It enables your CrewAI agents to navigate websites, extract content, click elements, and more. 证据：`lib/crewai-tools/src/crewai_tools/aws/bedrock/browser/README.md`\n- **AWS Bedrock Code Interpreter Tools**（documentation）：This toolkit provides a set of tools for interacting with the AWS Bedrock Code Interpreter environment. It enables your CrewAI agents to execute code, run shell commands, manage files, and perform computational tasks in a secure, isolated environment. 证据：`lib/crewai-tools/src/crewai_tools/aws/bedrock/code_interpreter/README.md`\n- **BedrockKBRetrieverTool**（documentation）：The BedrockKBRetrieverTool enables CrewAI agents to retrieve information from Amazon Bedrock Knowledge Bases using natural language queries. 证据：`lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/README.md`\n- **AWS S3 Tools**（documentation）：These tools provide a way to interact with Amazon S3, a cloud storage service. 证据：`lib/crewai-tools/src/crewai_tools/aws/s3/README.md`\n- **AIMind Tool**（documentation）：Minds https://mindsdb.com/minds are AI systems provided by MindsDB https://mindsdb.com/ that work similarly to large language models LLMs but go beyond by answering any question from any data. 证据：`lib/crewai-tools/src/crewai_tools/tools/ai_mind_tool/README.md`\n- **ApifyActorsTool**（documentation）：Integrate Apify Actors https://apify.com/actors into your CrewAI workflows. 证据：`lib/crewai-tools/src/crewai_tools/tools/apify_actors_tool/README.md`\n- **ArxivPaperTool**（documentation）：The ArxivPaperTool is a utility for fetching metadata and optionally downloading PDFs of academic papers from the arXiv https://arxiv.org platform using its public API. It supports configurable queries, batch retrieval, PDF downloading, and clean formatting for summaries and metadata. This tool is particularly useful for researchers, students, academic agents, and AI tools performing automated literature reviews. 证据：`lib/crewai-tools/src/crewai_tools/tools/arxiv_paper_tool/README.md`\n- **BraveSearchTool Documentation**（documentation）：Description This tool is designed to perform a web search for a specified query from a text's content across the internet. It utilizes the Brave Web Search API, which is a REST API to query Brave Search and get back search results from the web. The following sections describe how to curate requests, including parameters and headers, to Brave Web Search API and get a JSON response back. 证据：`lib/crewai-tools/src/crewai_tools/tools/brave_search_tool/README.md`\n- **BrightData Tools Documentation**（documentation）：A comprehensive suite of CrewAI tools that leverage Bright Data's powerful infrastructure for web scraping, data extraction, and search operations. These tools provide three distinct capabilities: 证据：`lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/README.md`\n- **BrowserbaseLoadTool**（documentation）：Browserbase https://browserbase.com is a developer platform to reliably run, manage, and monitor headless browsers. 证据：`lib/crewai-tools/src/crewai_tools/tools/browserbase_load_tool/README.md`\n- **CodeDocsSearchTool**（documentation）：Description The CodeDocsSearchTool is a powerful RAG Retrieval-Augmented Generation tool designed for semantic searches within code documentation. It enables users to efficiently find specific information or topics within code documentation. By providing a docs url during initialization, the tool narrows down the search to that particular documentation site. Alternatively, without a specific docs url , it searches across a wide array of code documentation known or discovered throughout its execution, making it versatile for various documentation search needs. 证据：`lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md`\n- **ComposioTool Documentation**（documentation）：This tools is a wrapper around the composio toolset and gives your agent access to a wide variety of tools from the composio SDK. 证据：`lib/crewai-tools/src/crewai_tools/tools/composio_tool/README.md`\n- **ContextualAICreateAgentTool**（documentation）：Description This tool is designed to integrate Contextual AI's enterprise-grade RAG agents with CrewAI. This tool enables you to create a new Contextual RAG agent. It uploads your documents to create a datastore and returns the Contextual agent ID and datastore ID. 证据：`lib/crewai-tools/src/crewai_tools/tools/contextualai_create_agent_tool/README.md`\n- **ContextualAIParseTool**（documentation）：Description This tool is designed to integrate Contextual AI's enterprise-grade document parsing capabilities with CrewAI, enabling you to leverage advanced AI-powered document understanding for complex layouts, tables, and figures. Use this tool to extract structured content from your documents using Contextual AI's powerful document parser. 证据：`lib/crewai-tools/src/crewai_tools/tools/contextualai_parse_tool/README.md`\n- **ContextualAIQueryTool**（documentation）：Description This tool is designed to integrate Contextual AI's enterprise-grade RAG agents with CrewAI. Run this tool to query existing Contextual AI RAG agents that have been pre-configured with documents and knowledge bases. 证据：`lib/crewai-tools/src/crewai_tools/tools/contextualai_query_tool/README.md`\n- **ContextualAIRerankTool**（documentation）：Description This tool is designed to integrate Contextual AI's enterprise-grade instruction-following reranker with CrewAI, enabling you to intelligently reorder documents based on relevance and custom criteria. Use this tool to enhance search result quality and document retrieval for RAG systems using Contextual AI's reranking models that understand context and follow specific instructions for optimal document ordering. 证据：`lib/crewai-tools/src/crewai_tools/tools/contextualai_rerank_tool/README.md`\n- **CouchbaseFTSVectorSearchTool**（documentation）：CouchbaseFTSVectorSearchTool Description Couchbase is a NoSQL database with vector search capabilities. Users can store and query vector embeddings. You can learn more about Couchbase vector search here: https://docs.couchbase.com/cloud/vector-search/vector-search.html 证据：`lib/crewai-tools/src/crewai_tools/tools/couchbase_tool/README.md`\n- **CSVSearchTool**（documentation）：This tool is used to perform a RAG Retrieval-Augmented Generation search within a CSV file's content. It allows users to semantically search for queries in the content of a specified CSV file. This feature is particularly useful for extracting information from large CSV datasets where traditional search methods might be inefficient. All tools with \"Search\" in their name, including CSVSearchTool, are RAG tools designed for searching different sources of data. 证据：`lib/crewai-tools/src/crewai_tools/tools/csv_search_tool/README.md`\n- **DALL-E Tool**（documentation）：Description This tool is used to give the Agent the ability to generate images using the DALL-E model. It is a transformer-based model that generates images from textual descriptions. This tool allows the Agent to generate images based on the text input provided by the user. 证据：`lib/crewai-tools/src/crewai_tools/tools/dalle_tool/README.MD`\n- **Databricks Query Tool**（documentation）：This tool allows AI agents to execute SQL queries against Databricks workspace tables and retrieve the results. It provides a simple interface for querying data from Databricks tables using SQL, making it easy for agents to access and analyze data stored in Databricks. 证据：`lib/crewai-tools/src/crewai_tools/tools/databricks_query_tool/README.md`\n- **Daytona Sandbox Tools**（documentation）：Run shell commands, execute Python, and manage files inside a Daytona https://www.daytona.io/ sandbox. Daytona provides isolated, ephemeral compute environments suitable for agent-driven code execution. 证据：`lib/crewai-tools/src/crewai_tools/tools/daytona_sandbox_tool/README.md`\n- **DirectoryReadTool**（documentation）：Description The DirectoryReadTool is a highly efficient utility designed for the comprehensive listing of directory contents. It recursively navigates through the specified directory, providing users with a detailed enumeration of all files, including those nested within subdirectories. This tool is indispensable for tasks requiring a thorough inventory of directory structures or for validating the organization of files within directories. 证据：`lib/crewai-tools/src/crewai_tools/tools/directory_read_tool/README.md`\n- **DirectorySearchTool**（documentation）：Description This tool is designed to perform a semantic search for queries within the content of a specified directory. Utilizing the RAG Retrieval-Augmented Generation methodology, it offers a powerful means to semantically navigate through the files of a given directory. The tool can be dynamically set to search any directory specified at runtime or can be pre-configured to search within a specific directory upon initialization. 证据：`lib/crewai-tools/src/crewai_tools/tools/directory_search_tool/README.md`\n- **DOCXSearchTool**（documentation）：Description The DOCXSearchTool is a RAG tool designed for semantic searching within DOCX documents. It enables users to effectively search and extract relevant information from DOCX files using query-based searches. This tool is invaluable for data analysis, information management, and research tasks, streamlining the process of finding specific information within large document collections. 证据：`lib/crewai-tools/src/crewai_tools/tools/docx_search_tool/README.md`\n- **E2B Sandbox Tools**（documentation）：Run shell commands, execute Python, and manage files inside an E2B https://e2b.dev/ sandbox. E2B provides isolated, ephemeral VMs suitable for agent-driven code execution, with a Jupyter-style code interpreter for rich Python results. 证据：`lib/crewai-tools/src/crewai_tools/tools/e2b_sandbox_tool/README.md`\n- **ExaSearchTool Documentation**（documentation）：Description This tool lets CrewAI agents search the web using Exa https://exa.ai/ , the fastest and most accurate web search API. By default the tool returns token-efficient highlights of the most relevant results for any query; you can also opt in to full page content. 证据：`lib/crewai-tools/src/crewai_tools/tools/exa_tools/README.md`\n- **FileReadTool**（documentation）：The FileReadTool is a versatile component of the crewai tools package, designed to streamline the process of reading and retrieving content from files. It is particularly useful in scenarios such as batch text file processing, runtime configuration file reading, and data importation for analytics. This tool supports various text-based file formats including .txt , .csv , .json , and adapts its functionality based on the file type, for instance, converting JSON content into a Python dictionary for easy use. 证据：`lib/crewai-tools/src/crewai_tools/tools/file_read_tool/README.md`\n- **FileWriterTool Documentation**（documentation）：Here's the rewritten README for the FileWriterTool : 证据：`lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md`\n- **📦 FileCompressorTool**（documentation）：The FileCompressorTool is a utility for compressing individual files or entire directories including nested subdirectories into different archive formats, such as .zip or .tar including .tar.gz , .tar.bz2 , and .tar.xz . This tool is useful for archiving logs, documents, datasets, or backups in a compact format, and ensures flexibility in how the archives are created. 证据：`lib/crewai-tools/src/crewai_tools/tools/files_compressor_tool/README.md`\n- **FirecrawlCrawlWebsiteTool**（documentation）：Firecrawl https://firecrawl.dev is a platform for crawling and convert any website into clean markdown or structured data. 证据：`lib/crewai-tools/src/crewai_tools/tools/firecrawl_crawl_website_tool/README.md`\n- **FirecrawlScrapeWebsiteTool**（documentation）：Firecrawl https://firecrawl.dev is a platform for crawling and convert any website into clean markdown or structured data. 证据：`lib/crewai-tools/src/crewai_tools/tools/firecrawl_scrape_website_tool/README.md`\n- **FirecrawlSearchTool**（documentation）：Firecrawl https://firecrawl.dev is a platform for crawling and convert any website into clean markdown or structured data. 证据：`lib/crewai-tools/src/crewai_tools/tools/firecrawl_search_tool/README.md`\n- **GenerateCrewaiAutomationTool**（documentation）：The GenerateCrewaiAutomationTool integrates with CrewAI Studio API to generate complete CrewAI automations from natural language descriptions. It translates high-level requirements into functional CrewAI implementations and returns direct links to Studio projects. 证据：`lib/crewai-tools/src/crewai_tools/tools/generate_crewai_automation_tool/README.md`\n- **GithubSearchTool**（documentation）：Description The GithubSearchTool is a Retrieval Augmented Generation RAG tool specifically designed for conducting semantic searches within GitHub repositories. Utilizing advanced semantic search capabilities, it sifts through code, pull requests, issues, and repositories, making it an essential tool for developers, researchers, or anyone in need of precise information from GitHub. 证据：`lib/crewai-tools/src/crewai_tools/tools/github_search_tool/README.md`\n- **HyperbrowserLoadTool**（documentation）：Hyperbrowser https://hyperbrowser.ai is a platform for running and scaling headless browsers. It lets you launch and manage browser sessions at scale and provides easy to use solutions for any webscraping needs, such as scraping a single page or crawling an entire site. 证据：`lib/crewai-tools/src/crewai_tools/tools/hyperbrowser_load_tool/README.md`\n- **InvokeCrewAIAutomationTool**（documentation）：The InvokeCrewAIAutomationTool provides CrewAI Platform API integration with external crew services. This tool allows you to invoke and interact with CrewAI Platform automations from within your CrewAI agents, enabling seamless integration between different crew workflows. 证据：`lib/crewai-tools/src/crewai_tools/tools/invoke_crewai_automation_tool/README.md`\n- **JinaScrapeWebsiteTool**（documentation）：Description A tool designed to extract and read the content of a specified website by using Jina.ai reader. It is capable of handling various types of web pages by making HTTP requests and parsing the received HTML content. This tool can be particularly useful for web scraping tasks, data collection, or extracting specific information from websites. 证据：`lib/crewai-tools/src/crewai_tools/tools/jina_scrape_website_tool/README.md`\n- **JSONSearchTool**（documentation）：Description This tool is used to perform a RAG search within a JSON file's content. It allows users to initiate a search with a specific JSON path, focusing the search operation within that particular JSON file. If the path is provided at initialization, the tool restricts its search scope to the specified JSON file, thereby enhancing the precision of search results. 证据：`lib/crewai-tools/src/crewai_tools/tools/json_search_tool/README.md`\n- **Linkup Search Tool**（documentation）：The LinkupSearchTool is a tool designed for integration with the CrewAI framework. It provides the ability to query the Linkup API for contextual information and retrieve structured results. This tool is ideal for enriching workflows with up-to-date and reliable information from Linkup. 证据：`lib/crewai-tools/src/crewai_tools/tools/linkup/README.md`\n- **LlamaIndexTool Documentation**（documentation）：Description This tool is designed to be a general wrapper around LlamaIndex tools and query engines, enabling you to leverage LlamaIndex resources in terms of RAG/agentic pipelines as tools to plug into CrewAI agents. 证据：`lib/crewai-tools/src/crewai_tools/tools/llamaindex_tool/README.md`\n- **MDXSearchTool**（documentation）：Description The MDX Search Tool, a key component of the crewai tools package, is designed for advanced market data extraction, offering invaluable support to researchers and analysts requiring immediate market insights in the AI sector. With its ability to interface with various data sources and tools, it streamlines the process of acquiring, reading, and organizing market data efficiently. 证据：`lib/crewai-tools/src/crewai_tools/tools/mdx_search_tool/README.md`\n- **MergeAgentHandlerTool Documentation**（documentation）：MergeAgentHandlerTool Documentation 证据：`lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/README.md`\n- **MongoDBVectorSearchTool**（documentation）：Description This tool is specifically crafted for conducting vector searches within docs within a MongoDB database. Use this tool to find semantically similar docs to a given query. 证据：`lib/crewai-tools/src/crewai_tools/tools/mongodb_vector_search_tool/README.md`\n- **MultiOnTool Documentation**（documentation）：Description The MultiOnTool, integrated within the crewai tools package, empowers CrewAI agents with the capability to navigate and interact with the web through natural language instructions. Leveraging the Multion API, this tool facilitates seamless web browsing, making it an essential asset for projects requiring dynamic web data interaction. 证据：`lib/crewai-tools/src/crewai_tools/tools/multion_tool/README.md`\n- **MySQLSearchTool**（documentation）：Description This tool is designed to facilitate semantic searches within MySQL database tables. Leveraging the RAG Retrieve and Generate technology, the MySQLSearchTool provides users with an efficient means of querying database table content, specifically tailored for MySQL databases. It simplifies the process of finding relevant data through semantic search queries, making it an invaluable resource for users needing to perform advanced queries on extensive datasets within a MySQL database. 证据：`lib/crewai-tools/src/crewai_tools/tools/mysql_search_tool/README.md`\n- **NL2SQL Tool**（documentation）：This tool is used to convert natural language to SQL queries. When passed to the agent it will generate queries and then use them to interact with the database. 证据：`lib/crewai-tools/src/crewai_tools/tools/nl2sql/README.md`\n- **OCR Tool**（documentation）：This tool performs Optical Character Recognition OCR on images using supported LLMs. It can extract text from both local image files and images available via URLs. The tool leverages the LLM's vision capabilities to provide accurate text extraction from images. 证据：`lib/crewai-tools/src/crewai_tools/tools/ocr_tool/README.md`\n- **OxylabsAmazonProductScraperTool**（documentation）：Scrape any website with OxylabsAmazonProductScraperTool 证据：`lib/crewai-tools/src/crewai_tools/tools/oxylabs_amazon_product_scraper_tool/README.md`\n- **OxylabsAmazonSearchScraperTool**（documentation）：Scrape any website with OxylabsAmazonSearchScraperTool 证据：`lib/crewai-tools/src/crewai_tools/tools/oxylabs_amazon_search_scraper_tool/README.md`\n- **OxylabsGoogleSearchScraperTool**（documentation）：Scrape any website with OxylabsGoogleSearchScraperTool 证据：`lib/crewai-tools/src/crewai_tools/tools/oxylabs_google_search_scraper_tool/README.md`\n- 其余 23 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `lib/cli/README.md`, `lib/cli/src/crewai_cli/templates/AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `lib/cli/README.md`, `lib/cli/src/crewai_cli/templates/AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **crewAI 简介与快速入门**：importance `high`\n - source_paths: README.md, lib/crewai/README.md, lib/cli/src/crewai_cli/create_crew.py, lib/cli/src/crewai_cli/create_flow.py\n- **系统架构与模块设计**：importance `high`\n - source_paths: lib/crewai/pyproject.toml, lib/crewai/src/crewai/__init__.py, lib/crewai/src/crewai/crew.py, lib/crewai/src/crewai/flow/flow.py, lib/cli/pyproject.toml\n- **Agent 智能体系统**：importance `high`\n - source_paths: lib/crewai/src/crewai/agents/agent_builder/base_agent.py, lib/crewai/src/crewai/agent/core.py, lib/crewai/src/crewai/agents/crew_agent_executor.py, lib/crewai/src/crewai/agents/step_executor.py, lib/crewai/src/crewai/tools/agent_tools/agent_tools.py\n- **Crew 智能体团队**：importance `high`\n - source_paths: lib/crewai/src/crewai/crew.py, lib/crewai/src/crewai/process.py, lib/crewai/src/crewai/crews/crew_output.py, lib/crewai/src/crewai/agents/tools_handler.py, lib/cli/src/crewai_cli/templates/crew/crew.py\n- **Flow 事件驱动工作流**：importance `high`\n - source_paths: lib/crewai/src/crewai/flow/flow.py, lib/crewai/src/crewai/flow/flow_config.py, lib/crewai/src/crewai/flow/flow_context.py, lib/crewai/src/crewai/flow/persistence/decorators.py, lib/crewai/src/crewai/flow/persistence/sqlite.py\n- **Task 任务系统**：importance `high`\n - source_paths: lib/crewai/src/crewai/task.py, lib/crewai/src/crewai/tasks/__init__.py, lib/crewai/src/crewai/tasks/conditional_task.py, lib/crewai/src/crewai/tasks/task_output.py, lib/crewai/src/crewai/tasks/llm_guardrail.py\n- **LLM 集成与提供者**：importance `high`\n - source_paths: lib/crewai/src/crewai/llm.py, lib/crewai/src/crewai/llms/base_llm.py, lib/crewai/src/crewai/llms/providers/openai/completion.py, lib/crewai/src/crewai/llms/providers/anthropic/completion.py, lib/crewai/src/crewai/llms/providers/bedrock/completion.py\n- **工具系统与 MCP 集成**：importance `high`\n - source_paths: lib/crewai/src/crewai/tools/base_tool.py, lib/crewai/src/crewai/tools/structured_tool.py, lib/crewai/src/crewai/tools/tool_calling.py, lib/crewai/src/crewai/mcp/__init__.py, lib/crewai/src/crewai/mcp/client.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `ba523f46c06289074b0267ab2689571398c7cc7b`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/enterprise-api.en.yaml`, `docs/reo-tracking.js`, `docs/enterprise-api.pt-BR.yaml`, `docs/enterprise-api.base.yaml`, `docs/index.mdx`, `docs/common-room-tracking.js`, `docs/docs.json`, `docs/enterprise-api.ko.yaml`, `docs/pt-BR/telemetry.mdx`, `docs/pt-BR/index.mdx`, `docs/pt-BR/installation.mdx`, `docs/pt-BR/quickstart.mdx`, `docs/pt-BR/changelog.mdx`, `docs/pt-BR/introduction.mdx`, `docs/pt-BR/skills.mdx`, `docs/ar/telemetry.mdx`, `docs/ar/index.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a7c38215ebb04a4fbc6e7c6d2fdb2469 | https://github.com/crewAIInc/crewAI/issues/5708 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[BUG] Wrong code in document\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] Wrong code in document\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_390380af45524e959d558b160597b38b | https://github.com/crewAIInc/crewAI/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[FEATURE] Enhance the document about @persisit\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Enhance the document about @persisit\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_effef000d4cf47a892f17850aa033610 | https://github.com/crewAIInc/crewAI/issues/5372 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_858a1a8bead2456289d686ec0d2d802c | https://github.com/crewAIInc/crewAI/issues/4877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `crewai` 与安装入口 `skills` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:710601088 | https://github.com/crewAIInc/crewAI | repo=crewai; install=skills\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：1.14.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dcfa2a852812414a82683392c2888795 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：1.14.4a1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4a1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0de86b993ffa4d9298726daa189abf49 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：1.14.5a4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.5a4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6db6cd94b6ef4bffa23da215458565b4 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Scans the client database to extract existing policy details.\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Scans the client database to extract existing policy details.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8201c73155314e67801bd0b81ea9820d | https://github.com/crewAIInc/crewAI/issues/5760 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:710601088 | https://github.com/crewAIInc/crewAI | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：crewAIInc/crewAI\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[BUG] Wrong code in document（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[FEATURE] Enhance the document about @persisit（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/crewAIInc/crewAI 项目说明书\n\n生成时间：2026-05-11 07:12:58 UTC\n\n## 目录\n\n- [crewAI 简介与快速入门](#introduction)\n- [系统架构与模块设计](#architecture)\n- [Agent 智能体系统](#agents)\n- [Crew 智能体团队](#crews)\n- [Flow 事件驱动工作流](#flows)\n- [Task 任务系统](#tasks)\n- [LLM 集成与提供者](#llm-integration)\n- [工具系统与 MCP 集成](#tools)\n- [MCP 与 A2A 协议](#mcp-a2a)\n- [记忆与知识管理系统](#memory-knowledge)\n\n\n\n## crewAI 简介与快速入门\n\n### 相关页面\n\n相关主题：[系统架构与模块设计](#architecture), [Agent 智能体系统](#agents), [Crew 智能体团队](#crews)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/crewAIInc/crewAI/blob/main/README.md)\n- [lib/crewai/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/README.md)\n- [lib/cli/src/crewai_cli/templates/AGENTS.md](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/AGENTS.md)\n- [lib/crewai-tools/src/crewai_tools/tools/rag/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/rag/README.md)\n- [lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md)\n- [lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md)\n \n\n# crewAI 简介与快速入门\n\n## 什么是 crewAI？\n\ncrewAI 是一个先进的多代理自动化框架，旨在释放多代理自动化的真正潜力，提供最佳的**速度**与**智能组合**。该框架允许开发者创建能够协同工作的 AI 代理（Agent），使这些代理像团队一样处理复杂任务。\n\n资料来源：[README.md:1-15]()\n\n### 核心概念\n\ncrewAI 的架构围绕以下几个核心概念构建：\n\n| 概念 | 描述 |\n|------|------|\n| **Agent（代理）** | 具有特定角色、目标和背景故事的 AI 实体，可以拥有自己的工具和记忆 |\n| **Task（任务）** | 需要代理完成的具体工作单元，包含描述和预期输出 |\n| **Crew（团队）** | 由多个代理组成的协作单元，按照定义的流程协同工作 |\n| **Process（流程）** | 定义代理之间协作方式的工作流程机制 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:30-50]()\n\n### crewAI 架构图\n\n```mermaid\ngraph TD\n A[用户] --> B[Crew 团队]\n B --> C[Agent 1: Researcher]\n B --> D[Agent 2: Writer]\n B --> E[Agent N: ...]\n C --> F[Task 1: 研究任务]\n D --> G[Task 2: 写作任务]\n F --> H[结果输出]\n G --> H\n```\n\n## 安装与配置\n\n### 环境要求\n\ncrewAI 项目对环境有以下要求：\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | >=3.10, <3.14 |\n| 包管理工具 | 推荐使用 [UV](https://docs.astral.sh/uv/) |\n| 可选依赖 | crewai[tools] 用于工具支持 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:8-10]()\n\n### 安装步骤\n\n1. **安装 UV 包管理器**（如果尚未安装）：\n\n```bash\npip install uv\n```\n\n2. **创建 crewAI 项目**：\n\n```bash\ncrewai create crew --skip_provider\n```\n\n3. **安装项目依赖**：\n\n```bash\ncrewai install\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:15-22]()\n\n## 创建第一个 Crew\n\n### 项目结构\n\ncrewAI 项目通常包含以下结构：\n\n| 文件/目录 | 用途 |\n|-----------|------|\n| `src//crew.py` | Crew 类定义，包含代理和任务配置 |\n| `config/agents.yaml` | 代理的配置文件 |\n| `config/tasks.yaml` | 任务的配置文件 |\n| `src//main.py` | 项目入口文件 |\n| `pyproject.toml` | 项目依赖配置 |\n\n### 定义 Agent\n\ncrewAI 使用 `@agent` 装饰器来定义代理，代理可以从 YAML 配置文件中读取配置：\n\n```python\nfrom crewai import Agent\nfrom crewai.project import CrewBase, agent\nfrom crewai_tools import SerperDevTool\n\n@CrewBase\nclass ResearchCrew():\n \"\"\"研究团队\"\"\"\n\n agents_config = \"config/agents.yaml\"\n tasks_config = \"config/tasks.yaml\"\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config[\"researcher\"],\n tools=[SerperDevTool()],\n verbose=True,\n )\n\n @agent\n def writer(self) -> Agent:\n return Agent(\n config=self.agents_config[\"writer\"],\n verbose=True,\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:35-60]()\n\n### 定义 Task\n\n任务定义使用 `@task` 装饰器：\n\n```python\nfrom crewai import Task\nfrom crewai.project import CrewBase, task\n\n@CrewBase\nclass ResearchCrew():\n # ... agent 定义 ...\n\n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config[\"research_task\"],\n )\n\n @task\n def writing_task(self) -> Task:\n return Task(\n config=self.tasks_config[\"writing_task\"],\n output_file='output/article.md'\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:65-80]()\n\n### YAML 配置示例\n\n**agents.yaml 示例**：\n\n```yaml\nresearcher:\n role: Senior Research Analyst\n goal: Uncover groundbreaking technologies in {topic}\n backstory: |\n You are a Senior Research Analyst at a leading tech think tank.\n Your expertise lies in identifying emerging trends and technologies.\n verbose: true\n\nwriter:\n role: Content Writer\n goal: Write engaging article about {topic}\n backstory: |\n You are a skilled content writer known for your ability to explain complex topics.\n verbose: true\n```\n\n**tasks.yaml 示例**：\n\n```yaml\nresearch_task:\n description: >\n Conduct a thorough research on {topic}.\n Identify key trends, notable companies, and potential impact.\n expected_output: >\n A comprehensive research report with main topics, each with full section of information.\n agent: researcher\n\nwriting_task:\n description: >\n Write an article based on the research findings about {topic}.\n expected_output: >\n A polished 4-paragraph article formatted in markdown.\n agent: writer\n output_file: output/article.md\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md:5-30]()\n\n## 集成工具生态\n\ncrewAI 支持丰富的工具生态，以下是常用工具的集成方式：\n\n### RagTool - 知识库检索工具\n\nRagTool 支持从多种来源加载内容构建知识库：\n\n```python\nfrom crewai_tools.tools.rag_tool import RagTool\n\n# 从文件加载\nrag_tool = RagTool().from_file('path/to/your/file.txt')\n\n# 从目录加载\nrag_tool = RagTool().from_directory('path/to/your/directory')\n\n# 从网页加载\nrag_tool = RagTool().from_web_page('https://example.com')\n```\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/rag/README.md:25-35]()\n\n### FileWriterTool - 文件写入工具\n\nFileWriterTool 简化了向文件写入内容的过程，支持创建目录：\n\n```python\nfrom crewai_tools import FileWriterTool\n\n# 初始化工具\nfile_writer_tool = FileWriterTool()\n\n# 写入内容到指定目录\nresult = file_writer_tool._run(\n 'example.txt', \n 'This is a test content.', \n 'test_directory'\n)\n```\n\n| 参数 | 说明 |\n|------|------|\n| filename | 要创建或覆盖的文件名 |\n| content | 要写入的内容 |\n| directory | 文件所在目录路径（可选，默认为当前目录）|\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md:20-35]()\n\n### TavilyExtractorTool - 网页内容提取\n\nTavilyExtractorTool 允许从网页提取结构化内容：\n\n```python\nfrom crewai import Agent, Task, Crew\nfrom crewai_tools import TavilyExtractorTool\n\n# 初始化工具\ntavily_tool = TavilyExtractorTool()\n\n# 创建使用该工具的代理\nextractor_agent = Agent(\n role='Web Content Extractor',\n goal='Extract key information from specified web pages',\n backstory='You are an expert at extracting content from websites.',\n tools=[tavily_tool],\n verbose=True\n)\n```\n\n| 参数 | 说明 |\n|------|------|\n| 必需 | Tavily API Key（通过 TAVILY_API_KEY 环境变量设置） |\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md:15-40]()\n\n### 工具安装方式\n\n```bash\n# 使用 UV 安装 crewai 及其工具\nuv add 'crewai[tools]' tavily-python\n\n# 或使用 pip\npip install 'crewai[tools]' contextual-client\n```\n\n## 常用命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `crewai create crew ` | 创建新的 crew 项目 |\n| `crewai create flow ` | 创建新的 flow 项目 |\n| `crewai run` | 运行 crew 或 flow |\n| `crewai test` | 测试 crew（默认 2 次迭代）|\n| `crewai test -n 5 -m gpt-4o` | 自定义测试迭代次数和模型 |\n| `crewai train -n 5 -f training.json` | 训练 crew |\n| `crewai reset-memories -a` | 重置所有记忆 |\n| `crewai log-tasks-outputs` | 显示最新任务输出 |\n| `crewai replay -t ` | 从特定任务重新播放 |\n| `crewai tool publish ` | 发布自定义工具 |\n| `crewai tool install ` | 安装社区工具 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/tool/README.md:25-40]()\n\n## Crew 工作流程\n\n```mermaid\ngraph LR\n A[定义 Agents] --> B[定义 Tasks]\n B --> C[配置 Crew]\n C --> D[kickoff]\n D --> E{Process 执行}\n E -->|顺序| F[Sequential]\n E -->|层级| G[Hierarchical]\n E -->|协作| H[Collaborative]\n F --> I[结果聚合]\n G --> I\n H --> I\n I --> J[输出]\n```\n\n## 下一步\n\n- 阅读 [Agent 设计指南](/design-agent) 学习如何配置代理\n- 阅读 [Task 设计指南](/design-task) 学习如何编写任务描述\n- 探索 [官方文档](https://docs.crewai.com) 了解更多高级功能\n\n---\n\n\n\n## 系统架构与模块设计\n\n### 相关页面\n\n相关主题：[crewAI 简介与快速入门](#introduction), [Agent 智能体系统](#agents), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/pyproject.toml)\n- [lib/crewai/src/crewai/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/__init__.py)\n- [lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n- [lib/crewai/src/crewai/flow/flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow.py)\n- [lib/cli/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/pyproject.toml)\n- [lib/crewai-tools/pyproject.toml](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/pyproject.toml)\n \n\n# 系统架构与模块设计\n\n## 概述\n\ncrewAI 是一个多智能体协作框架，旨在通过编排多个 AI Agent 来完成复杂任务。该框架采用模块化架构设计，将核心功能分离到独立模块中，实现关注点分离（Separation of Concerns）原则。\n\n核心设计理念：\n\n- **模块化**：各功能组件独立封装，便于维护和扩展\n- **可组合性**：通过 Crew（团队）概念组合多个 Agent 协同工作\n- **流程控制**：提供 Flow 机制实现任务编排和状态管理\n- **工具扩展**：支持自定义工具扩展 Agent 能力\n\n资料来源：[lib/crewai/src/crewai/__init__.py]()\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n CLI[CLI 界面]\n API[API 接口]\n end\n\n subgraph \"核心层\"\n Crew[Crew 编排器]\n Agent[Agent 智能体]\n Task[Task 任务]\n Flow[Flow 流程]\n end\n\n subgraph \"工具层\"\n Tools[Tools 工具集]\n CustomTools[自定义工具]\n end\n\n subgraph \"底层服务\"\n LLM[大语言模型]\n Memory[记忆系统]\n end\n\n CLI --> Crew\n API --> Crew\n Crew --> Agent\n Crew --> Task\n Flow --> Crew\n Agent --> Tools\n Agent --> LLM\n Agent --> Memory\n```\n\n## 项目结构\n\n### 代码库组织\n\n| 目录 | 说明 | 配置文件 |\n|------|------|----------|\n| `lib/crewai/` | 核心框架代码 | `pyproject.toml` |\n| `lib/cli/` | 命令行工具 | `pyproject.toml` |\n| `lib/crewai-tools/` | 工具扩展包 | `pyproject.toml` |\n\n### 核心模块依赖关系\n\n```mermaid\ngraph LR\n A[crewai core] --> B[Agent]\n A --> C[Crew]\n A --> D[Task]\n A --> E[Flow]\n A --> F[Tools]\n B --> D\n C --> B\n C --> D\n F --> B\n```\n\n## 核心模块详解\n\n### Crew 编排器\n\n`Crew` 是 crewAI 的核心编排组件，负责管理多个 Agent 和 Task 的协作执行。\n\n主要职责：\n\n- 初始化和管理 Agent 列表\n- 协调任务执行顺序\n- 管理任务结果汇总\n- 处理异常和重试逻辑\n\n资料来源：[lib/crewai/src/crewai/crew.py]()\n\n```python\nclass Crew:\n def __init__(\n self,\n agents: List[Agent],\n tasks: List[Task],\n process: Process = Process.hierarchical,\n verbose: bool = False,\n ):\n self.agents = agents\n self.tasks = tasks\n self.process = process\n self.verbose = verbose\n```\n\n### Agent 智能体\n\n`Agent` 代表一个具有特定角色的 AI 实体，每个 Agent 拥有：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `role` | str | 角色名称 |\n| `goal` | str | 目标描述 |\n| `backstory` | str | 背景故事 |\n| `tools` | List[BaseTool] | 可用工具列表 |\n| `llm` | Optional[LLM] | 语言模型配置 |\n\n### Task 任务\n\n`Task` 定义了具体的工作单元，与特定 Agent 关联执行。\n\n### Flow 流程控制\n\n`Flow` 模块提供了高级的流程编排能力，支持状态管理和工作流控制。\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py]()\n\n```python\nclass Flow:\n def __init__(self):\n self.state: Dict[str, Any] = {}\n \n def kickoff(self):\n \"\"\"启动流程执行\"\"\"\n pass\n \n def crew(self):\n \"\"\"注册 Crew 到 Flow\"\"\"\n pass\n```\n\n## 工具系统架构\n\n### 工具层设计\n\n```mermaid\ngraph TD\n Tools[Tools 基类] --> FileTools[文件工具]\n Tools --> SearchTools[搜索工具]\n Tools --> APITools[API 工具]\n Tools --> BrowserTools[浏览器工具]\n \n FileTools --> ReadTool[读取工具]\n FileTools --> WriteTool[写入工具]\n```\n\n### 工具注册机制\n\ncrewAI 采用基于装饰器的工具注册模式，工具继承 `BaseTool` 基类并实现 `_run` 方法。\n\n资料来源：[lib/crewai-tools/pyproject.toml]()\n\n## CLI 模块设计\n\nCLI 模块提供命令行交互入口，支持项目管理、任务创建、执行监控等功能。\n\n| 命令 | 功能 |\n|------|------|\n| `crewai create` | 创建新项目 |\n| `crewai run` | 运行 Crew |\n| `crewai task` | 任务管理 |\n| `crewai agent` | Agent 管理 |\n\n资料来源：[lib/cli/pyproject.toml]()\n\n## 包依赖配置\n\n### 核心包依赖\n\n```toml\n# lib/crewai/pyproject.toml\n[project]\nname = \"crewai\"\nversion = \"0.1.0\"\ndependencies = [\n \"pydantic>=2.0.0\",\n \"langchain-core>=0.1.0\",\n \"langchain-openai>=0.0.5\",\n]\n```\n\n### 工具包依赖\n\n```toml\n# lib/crewai-tools/pyproject.toml\n[project]\nname = \"crewai-tools\"\ndependencies = [\n \"crewai>=0.1.0\",\n \"langchain-core>=0.1.0\",\n]\n```\n\n## 执行流程\n\n### Crew 执行流程\n\n```mermaid\ngraph TD\n A[初始化 Crew] --> B[加载 Agents]\n B --> C[加载 Tasks]\n C --> D{执行模式}\n D -->|顺序| E[按序执行 Task]\n D -->|层级| F[Manager Agent 分配]\n E --> G[汇总结果]\n F --> G\n G --> H[返回最终输出]\n```\n\n### Flow 与 Crew 集成\n\n```mermaid\ngraph LR\n A[Flow.kickoff] --> B[初始化 State]\n B --> C[执行 crew]\n C --> D[Agent 执行任务]\n D --> E[更新 State]\n E --> F{是否完成}\n F -->|否| D\n F -->|是| G[返回结果]\n```\n\n## 配置选项\n\n### Crew 配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `process` | `Process.hierarchical` | 执行流程模式 |\n| `verbose` | `False` | 是否输出详细日志 |\n| `memory` | `True` | 是否启用记忆功能 |\n| `max_rpm` | `None` | 每分钟最大请求数 |\n| `share_crew` | `False` | 是否共享 Crew 实例 |\n\n### Agent 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `role` | str | Agent 角色定义 |\n| `goal` | str | Agent 目标 |\n| `backstory` | str | Agent 背景 |\n| `allow_delegation` | bool | 是否允许委托任务 |\n| `tools` | List[BaseTool] | 绑定工具 |\n\n## 模块间通信\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Crew\n participant Agent\n participant Tools\n participant LLM\n \n User->>CLI: 发起请求\n CLI->>Crew: 创建 Crew 实例\n Crew->>Agent: 分配任务\n Agent->>Tools: 调用工具\n Tools-->>Agent: 返回结果\n Agent->>LLM: 请求推理\n LLM-->>Agent: 返回响应\n Agent-->>Crew: 汇报结果\n Crew-->>CLI: 汇总输出\n CLI-->>User: 显示结果\n```\n\n## 扩展机制\n\n### 自定义工具开发\n\n开发者可通过继承 `BaseTool` 类创建自定义工具：\n\n```python\nfrom crewai.tools import BaseTool\n\nclass MyCustomTool(BaseTool):\n name: str = \"my_custom_tool\"\n description: str = \"工具描述\"\n \n def _run(self, *args, **kwargs):\n # 工具实现逻辑\n return result\n```\n\n### Flow 自定义\n\n通过继承 `Flow` 类并重写钩子方法实现自定义流程：\n\n| 方法 | 说明 |\n|------|------|\n| `before_kickoff()` | 启动前执行 |\n| `after_kickoff()` | 完成后执行 |\n| `crew()` | 注册 Crew 实例 |\n\n## 版本与依赖管理\n\ncrewAI 采用 PEP 440 版本规范，核心包与扩展包版本需保持兼容：\n\n| 包名 | 最低版本 | 用途 |\n|------|----------|------|\n| `pydantic` | ≥2.0.0 | 数据验证 |\n| `langchain-core` | ≥0.1.0 | LLM 接口抽象 |\n| `langchain-openai` | ≥0.0.5 | OpenAI 集成 |\n\n资料来源：[lib/crewai/pyproject.toml](), [lib/crewai-tools/pyproject.toml](), [lib/cli/pyproject.toml]()\n\n---\n\n\n\n## Agent 智能体系统\n\n### 相关页面\n\n相关主题：[Crew 智能体团队](#crews), [Task 任务系统](#tasks), [LLM 集成与提供者](#llm-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/agents/agent_builder/base_agent.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/agent_builder/base_agent.py)\n- [lib/crewai/src/crewai/agent/core.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agent/core.py)\n- [lib/crewai/src/crewai/agents/crew_agent_executor.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/crew_agent_executor.py)\n- [lib/crewai/src/crewai/agents/step_executor.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/step_executor.py)\n- [lib/crewai/src/crewai/tools/agent_tools/agent_tools.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/agent_tools/agent_tools.py)\n- [lib/cli/src/crewai_cli/templates/crew/config/agents.yaml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/config/agents.yaml)\n \n\n# Agent 智能体系统\n\n## 概述\n\nAgent（智能体）是 CrewAI 框架的核心构建单元，代表能够自主执行任务的人工智能角色。每个 Agent 具有明确的角色（role）、目标（goal）和背景故事（backstory），并可配备各种工具（Tools）来扩展其能力。\n\nAgent 系统的主要职责包括：\n\n- 理解并执行分配的任务\n- 与其他 Agent 协作完成复杂目标\n- 访问和利用各种工具获取信息或执行操作\n- 通过大语言模型（LLM）进行推理和决策\n\n## Agent 核心组件\n\n### 架构概览\n\n```mermaid\ngraph TD\n A[Agent] --> B[BaseAgent]\n A --> C[Agent Config]\n B --> D[CrewAgentExecutor]\n B --> E[StepExecutor]\n D --> F[LLM]\n D --> G[Tools]\n E --> H[Memory]\n E --> I[Guardrails]\n```\n\n### 核心类结构\n\n| 类名 | 文件位置 | 职责描述 |\n|------|----------|----------|\n| `BaseAgent` | `lib/crewai/src/crewai/agents/agent_builder/base_agent.py` | Agent 的基础抽象类，定义通用接口和属性 |\n| `Agent` | `lib/crewai/src/crewai/agent/core.py` | Agent 的核心实现类 |\n| `CrewAgentExecutor` | `lib/crewai/src/crewai/agents/crew_agent_executor.py` | Agent 执行器，负责运行 Agent 逻辑 |\n| `StepExecutor` | `lib/crewai/src/crewai/agents/step_executor.py` | 单步执行器，处理 Agent 的单个执行步骤 |\n\n## Agent 配置\n\n### YAML 配置格式\n\nAgent 通过 `agents.yaml` 配置文件定义，支持以下核心属性：\n\n```yaml\n# lib/cli/src/crewai_cli/templates/crew/config/agents.yaml\nresearcher:\n role: >\n {topic} Senior Data Researcher\n goal: >\n Uncover cutting-edge developments in {topic}\n backstory: >\n You're a seasoned researcher with a knack for uncovering the latest\n developments in {topic}. Known for your ability to find the most relevant\n information and present it in a clear and concise manner.\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `role` | string | 是 | Agent 的角色名称，如\"研究员\"、\"分析师\"等 |\n| `goal` | string | 是 | Agent 的核心目标，描述其需要达成的目的 |\n| `backstory` | string | 是 | Agent 的背景故事，定义其经验和专业领域 |\n| `llm` | dict | 否 | 大语言模型配置，覆盖默认设置 |\n| `tools` | list | 否 | 分配给 Agent 的工具列表 |\n| `verbose` | bool | 否 | 是否输出详细日志，默认 false |\n| `allow_delegation` | bool | 否 | 是否允许委托任务给其他 Agent |\n\n## Agent 创建与使用\n\n### 使用装饰器创建 Agent\n\nCrewAI 推荐使用 `@agent` 装饰器在 Crew 类中定义 Agent：\n\n```python\n# lib/cli/src/crewai_cli/templates/crew/crew.py\nfrom crewai import Agent\nfrom crewai.project import CrewBase, agent\n\n@CrewBase\nclass LatestAiDevelopmentCrew():\n agents: List[BaseAgent]\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config['researcher'],\n verbose=True,\n tools=[SerperDevTool()]\n )\n```\n\n### 直接实例化 Agent\n\n也可以直接实例化 Agent 类：\n\n```python\nfrom crewai import Agent\n\nresearcher = Agent(\n role=\"Information Researcher\",\n goal=\"Fetch relevant results from search engines.\",\n backstory=\"An expert in online information retrieval...\",\n tools=[search_tool],\n verbose=True\n)\n```\n\n## Agent 工具系统\n\n### 内置工具\n\nAgent 可使用多种内置工具来扩展能力：\n\n| 工具名称 | 功能描述 | 资料来源 |\n|----------|----------|----------|\n| `SerperDevTool` | 网络搜索工具 | README.md |\n| `LinkupSearchTool` | Linkup 搜索服务 | `lib/crewai-tools/src/crewai_tools/tools/linkup/README.md` |\n| `TavilyExtractorTool` | 网页内容提取 | `lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md` |\n| `ApifyActorsTool` | Apify 自动化工具 | `lib/crewai-tools/src/crewai_tools/tools/apify_actors_tool/README.md` |\n| `CodeDocsSearchTool` | 代码文档搜索 | `lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md` |\n\n### 工具配置示例\n\n```python\n# 自定义 LLM 和 embeddings 配置\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n## Agent 执行流程\n\n### 执行器工作流程\n\n```mermaid\ngraph TD\n A[Task 任务] --> B[CrewAgentExecutor]\n B --> C{是否需要工具?}\n C -->|是| D[调用 Tool]\n C -->|否| E[直接 LLM 响应]\n D --> F[处理 Tool 结果]\n E --> G[StepExecutor 单步执行]\n F --> G\n G --> H[更新 Memory]\n H --> I[返回结果]\n```\n\n### 单步执行机制\n\nStepExecutor 负责处理 Agent 的单个执行步骤，包括：\n\n1. 解析当前任务上下文\n2. 生成 LLM 调用\n3. 处理工具调用请求\n4. 解析执行结果\n5. 更新 Agent 记忆\n\n## Agent 与 Crew 协作\n\n### Crew 组合架构\n\n```mermaid\ngraph LR\n A[Crew] --> B[Agent 1]\n A --> C[Agent 2]\n A --> D[Agent N]\n B --> E[Task 1]\n C --> F[Task 2]\n D --> G[Task N]\n E --> H[Process 流程]\n F --> H\n G --> H\n```\n\n### 任务委派\n\nAgent 可以将任务委派给其他 Agent：\n\n```python\n@agent\ndef manager(self) -> Agent:\n return Agent(\n config=self.agents_config['manager'],\n verbose=True,\n allow_delegation=True # 允许委派任务\n )\n```\n\n## 高级配置\n\n### 内存系统\n\nAgent 配备内存系统以维护对话上下文：\n\n- **短期记忆**：当前会话内的上下文信息\n- **长期记忆**：跨会话积累的知识\n- **实体记忆**：关于特定实体的详细信息\n\n### Guardrails 安全机制\n\nAgent 支持配置安全护栏（Guardrails），确保输出符合预期：\n\n```python\nfrom crewai import Agent\nfrom crewai.agents import Guardrail\n\nagent = Agent(\n role=\"Data Analyst\",\n goal=\"Analyze data accurately\",\n backstory=\"Expert in data analysis\",\n guardrails=[custom_guardrail]\n)\n```\n\n## 环境配置\n\n### 必要环境变量\n\n运行 Agent 前需要配置以下环境变量：\n\n| 变量名 | 描述 | 必需 |\n|--------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 是（使用 OpenAI 时） |\n| `SERPER_API_KEY` | Serper.dev API 密钥 | 使用搜索工具时 |\n| `TAVILY_API_KEY` | Tavily API 密钥 | 使用 Tavily 工具时 |\n| `OTEL_SDK_DISABLED` | 禁用遥测 | 否 |\n\n### 依赖安装\n\n```bash\n# 使用 uv 管理依赖\nuv sync\n\n# 或使用 crewai CLI\ncrewai install\n```\n\n## 最佳实践\n\n### 1. 角色设计\n\n- 角色名称应清晰表达 Agent 的专业领域\n- 目标描述应具体、可衡量\n- 背景故事应与任务需求匹配\n\n### 2. 工具选择\n\n- 只分配与任务相关的工具\n- 避免过多工具导致决策混乱\n- 正确配置工具 API 密钥\n\n### 3. 流程编排\n\n- sequential（顺序）流程：任务有明确依赖关系\n- hierarchical（层级）流程：需要管理角色协调\n\n## 测试与调试\n\n### 运行测试\n\n```bash\n# 默认测试（2 次迭代，使用 gpt-4o-mini）\ncrewai test\n\n# 自定义测试\ncrewai test -n 5 -m gpt-4o\n```\n\n### 查看输出\n\n```bash\n# 查看最新任务输出\ncrewai log-tasks-outputs\n\n# 重放特定任务\ncrewai replay -t \n```\n\n## 总结\n\nAgent 智能体系统是 CrewAI 框架的核心，通过结合角色定义、目标设定、工具扩展和记忆机制，实现了灵活且强大的多智能体协作能力。开发者可以通过 YAML 配置或 Python 代码定义 Agent，并将其组合成 Crew 来完成复杂任务。\n\n## 相关资源\n\n- [官方文档](https://docs.crewai.com)\n- [GitHub 仓库](https://github.com/crewAIInc/crewAI)\n- [Discord 社区](https://discord.gg/X4JWnZnxPb)\n\n---\n\n\n\n## Crew 智能体团队\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents), [Task 任务系统](#tasks), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n- [lib/crewai/src/crewai/process.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/process.py)\n- [lib/crewai/src/crewai/crews/crew_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crews/crew_output.py)\n- [lib/crewai/src/crewai/agents/tools_handler.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/tools_handler.py)\n- [lib/cli/src/crewai_cli/templates/crew/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/crew.py)\n \n\n# Crew 智能体团队\n\n## 概述\n\nCrew 是 CrewAI 框架中的核心编排单元，用于组织和管理多个 AI 智能体（Agent）协同完成复杂任务。Crew 本质上是一个任务编排容器，它将多个具有特定角色的智能体组合在一起，通过预定义的流程模式协调它们之间的工作。\n\nCrew 的设计理念是将自治性（Autonomy）和精确性（Precision）相结合，使得开发者能够灵活地构建从简单任务到企业级自动化的各类应用场景。\n\n## 核心架构\n\n### Crew 与 Agent 的关系\n\n```mermaid\ngraph TD\n A[Crew 智能体团队] --> B[Agent 1: 研究员]\n A --> C[Agent 2: 分析员]\n A --> D[Agent 3: 报告员]\n A --> E[Task 任务列表]\n A --> F[Process 进程模式]\n B -.-> E\n C -.-> E\n D -.-> E\n E -.-> F\n```\n\n一个 Crew 由以下核心元素组成：\n\n| 组件 | 描述 | 类型 |\n|------|------|------|\n| agents | 智能体列表 | List[BaseAgent] |\n| tasks | 任务列表 | List[Task] |\n| process | 进程模式 | Process Enum |\n| verbose | 详细输出控制 | bool |\n| memory | 记忆系统 | bool |\n\n## Crew 的创建方式\n\n### 使用装饰器模式（CrewBase）\n\nCrewAI 推荐使用 `@CrewBase` 装饰器来定义 Crew 类，这种方式将配置与代码分离，便于维护和修改。\n\n```python\nfrom crewai import Agent, Crew, Process, Task\nfrom crewai.project import CrewBase, agent, crew, task\nfrom typing import List\n\n@CrewBase\nclass MyCrew():\n \"\"\"我的智能体团队\"\"\"\n agents: List[BaseAgent]\n tasks: List[Task]\n\n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config['researcher'],\n verbose=True\n )\n\n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n )\n\n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n )\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/crew/crew.py:1-45]()\n\n### 直接实例化\n\n也可以不使用装饰器，直接通过代码创建 Crew：\n\n```python\nfrom crewai import Agent, Crew, Process, Task\n\nresearcher = Agent(role=\"研究员\", goal=\"研究最新AI发展\", backstory=\"...\")\ntask1 = Task(description=\"研究任务\", agent=researcher)\n\ncrew = Crew(\n agents=[researcher],\n tasks=[task1],\n process=Process.sequential,\n verbose=True\n)\n```\n\n## 进程模式（Process）\n\nCrew 支持两种主要的进程模式，用于控制智能体执行任务的顺序和方式。\n\n### 顺序执行（Sequential）\n\n顺序执行模式按照任务列表的定义顺序依次执行任务，每个任务完成后才启动下一个任务。\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n)\n```\n\n### 分层执行（Hierarchical）\n\n分层执行模式会自动分配一个管理员角色，负责协调和验证任务的规划与执行结果。\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.hierarchical,\n verbose=True,\n manager_agent=manager # 可选：自定义管理员\n)\n```\n\n### 进程模式对比\n\n| 模式 | 说明 | 适用场景 | 管理员 |\n|------|------|----------|--------|\n| Sequential | 按顺序执行任务 | 线性工作流 | 无 |\n| Hierarchical | 动态委托和验证 | 需要协调的复杂任务 | 自动或自定义 |\n\n资料来源：[lib/crewai/src/crewai/process.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/process.py)\n\n## Crew 配置参数\n\n### 主要参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| agents | List[BaseAgent] | 是 | - | 团队成员列表 |\n| tasks | List[Task] | 是 | - | 任务列表 |\n| process | Process | 否 | Process.sequential | 进程模式 |\n| verbose | bool | 否 | False | 是否输出详细日志 |\n| memory | bool | 否 | False | 启用记忆系统 |\n| max_rpm | int | 否 | None | 最大请求速率限制 |\n| language | str | 否 | en | 输出语言 |\n| config | dict | 否 | None | 自定义配置 |\n\n### 完整配置示例\n\n```python\ncrew = Crew(\n agents=[researcher, analyst, writer],\n tasks=[task1, task2, task3],\n process=Process.sequential,\n verbose=True,\n memory=True,\n max_rpm=60,\n respect_context_window=True,\n config={\n \"workflow\": \"research_report\",\n \"output_format\": \"markdown\"\n }\n)\n```\n\n资料来源：[lib/crewai/src/crewai/crew.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crew.py)\n\n## Crew 的生命周期\n\n```mermaid\ngraph TD\n A[创建 Crew 实例] --> B[初始化 Agents 和 Tasks]\n B --> C[调用 kickoff 方法]\n C --> D{进程模式}\n D -->|Sequential| E[按顺序执行任务]\n D -->|Hierarchical| F[管理员协调任务]\n E --> G[收集任务输出]\n F --> G\n G --> H[生成 CrewOutput]\n H --> I[返回最终结果]\n```\n\n### 执行入口\n\nCrew 的主入口方法是 `kickoff()`，它接收输入参数并启动整个团队的工作：\n\n```python\ninputs = {\n 'topic': 'AI Agents',\n 'format': 'markdown'\n}\n\nresult = my_crew.kickoff(inputs=inputs)\n```\n\n### 输出处理\n\nCrew 执行完成后会返回 `CrewOutput` 对象，包含所有任务的结果和元数据：\n\n```python\nclass CrewOutput(BaseOutput):\n tasks_output: List[TaskOutput]\n token_usage: Dict[str, Any]\n raw: Optional[str]\n```\n\n资料来源：[lib/crewai/src/crewai/crews/crew_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/crews/crew_output.py)\n\n## 记忆系统（Memory）\n\nCrew 支持可选的记忆系统，用于实现跨会话学习和上下文保持。\n\n### 记忆类型\n\n| 类型 | 参数 | 说明 |\n|------|------|------|\n| 短期记忆 | - | 当前会话的临时数据 |\n| 长期记忆 | - | 持久化的历史数据 |\n| 实体记忆 | - | 实体相关的信息 |\n| 知识库 | knowledge | 结构化的领域知识 |\n\n### 使用记忆\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n memory=True, # 启用记忆系统\n verbose=True\n)\n```\n\n## 工具集成\n\n### 工具处理器\n\n每个 Agent 可以配备多个工具，工具通过 `ToolsHandler` 进行管理和调用：\n\n```mermaid\ngraph LR\n A[Agent] --> B[ToolsHandler]\n B --> C[Tool 1]\n B --> D[Tool 2]\n B --> E[Tool N]\n```\n\n### 内置工具示例\n\nCrewAI 提供了丰富的内置工具：\n\n| 工具名称 | 功能 |\n|----------|------|\n| SerperDevTool | 网络搜索 |\n| LinkupSearchTool | 搜索增强 |\n| CodeDocsSearchTool | 代码文档搜索 |\n| TavilyExtractorTool | 网页内容提取 |\n\n### 自定义工具\n\n开发者可以创建自定义工具继承 `BaseTool` 类：\n\n```python\nfrom crewai.tools import BaseTool\n\nclass MyCustomTool(BaseTool):\n name: str = \"my_tool\"\n description: str = \"执行自定义任务\"\n\n def _run(self, **kwargs):\n # 工具逻辑\n return result\n```\n\n资料来源：[lib/crewai/src/crewai/agents/tools_handler.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/agents/tools_handler.py)\n\n## 最佳实践\n\n### 1. YAML 配置优先\n\n推荐使用 YAML 文件定义 agents 和 tasks，保持代码简洁：\n\n```\nsrc/my_project/\n├── config/\n│ ├── agents.yaml\n│ └── tasks.yaml\n├── crew.py\n└── main.py\n```\n\n### 2. 结构化输出\n\n对于需要跨任务传递的数据，使用 `output_pydantic` 定义数据结构：\n\n```python\nTask(\n config=self.tasks_config['task_name'],\n output_pydantic=ReportModel # 定义输出结构\n)\n```\n\n### 3. 速率限制\n\n生产环境中设置合理的 `max_rpm` 避免 API 限流：\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n max_rpm=60 # 每分钟最多60次请求\n)\n```\n\n### 4. 上下文窗口管理\n\n启用 `respect_context_window=True` 自动处理 token 限制：\n\n```python\ncrew = Crew(\n agents=self.agents,\n tasks=self.tasks,\n respect_context_window=True\n)\n```\n\n## 错误处理与调试\n\n### 日志输出\n\n使用 `verbose=True` 查看详细执行日志：\n\n```bash\ncrewai run # 运行并显示详细输出\ncrewai log-tasks-outputs # 查看任务输出\n```\n\n### 重放功能\n\n使用 `replay` 命令从特定任务重新执行：\n\n```bash\ncrewai replay -t \n```\n\n### 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 任务未执行 | 任务依赖未满足 | 检查 tasks_config |\n| API 超时 | 请求速率过高 | 降低 max_rpm |\n| 上下文过长 | token 超限 | 启用 respect_context_window |\n\n## 总结\n\nCrew 是 CrewAI 框架中用于组织多智能体协作的核心组件。通过合理配置 agents、tasks 和 process 模式，开发者可以构建从简单到复杂的各类自动化工作流。Crew 提供了灵活的架构，支持顺序执行、分层协调、记忆系统和丰富的工具集成，使其能够适应各种企业级应用场景。\n\n关键要点：\n- 使用 `@CrewBase` 装饰器实现声明式配置\n- 根据工作流特性选择合适的进程模式\n- 合理使用记忆系统和速率限制提升性能\n- 利用结构化输出确保任务间数据传递的准确性\n\n---\n\n\n\n## Flow 事件驱动工作流\n\n### 相关页面\n\n相关主题：[Crew 智能体团队](#crews), [Task 任务系统](#tasks), [系统架构与模块设计](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/flow/flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow.py)\n- [lib/crewai/src/crewai/flow/flow_config.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow_config.py)\n- [lib/crewai/src/crewai/flow/flow_context.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/flow_context.py)\n- [lib/crewai/src/crewai/flow/persistence/decorators.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/persistence/decorators.py)\n- [lib/crewai/src/crewai/flow/persistence/sqlite.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/flow/persistence/sqlite.py)\n- [lib/cli/src/crewai_cli/templates/flow/main.py](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/flow/main.py)\n \n\n# Flow 事件驱动工作流\n\n## 概述\n\nFlow 是 CrewAI 框架中的事件驱动工作流编排模块，专为复杂的多 Crew 协调场景设计。与 Crew 的自主性（Autonomy）定位不同，Flow 提供精确的（Precise）工作流控制能力，允许开发者通过事件机制实现复杂的任务管道编排。\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\nFlow 的核心设计理念包括：\n\n- **YAML 优先配置**：通过 YAML 文件定义 agents 和 tasks，保持 Crew 类的简洁性\n- **结构化流状态**：使用 Pydantic 模型替代非结构化字典，确保类型安全\n- **事件驱动架构**：通过 `@start`、`@listen`、`@router` 装饰器实现复杂的事件路由逻辑\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 核心组件\n\nFlow 模块主要由以下组件构成，它们共同实现了事件驱动的工作流编排能力：\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| Flow | `flow.py` | 工作流主类，负责事件分发和流程协调 |\n| FlowConfig | `flow_config.py` | 工作流配置管理 |\n| FlowContext | `flow_context.py` | 上下文状态管理，用于在流程中传递数据 |\n| Persistence | `persistence/` | 持久化层，支持流程状态的保存和恢复 |\n\n### Flow 主类\n\nFlow 类是整个事件驱动工作流的核心，负责：\n\n- 管理事件监听器注册\n- 分发事件到对应的处理器\n- 协调多个 Crew 的执行顺序\n\n```python\nclass Flow:\n def __init__(self):\n self._event_bus = EventBus()\n self._listeners = []\n \n def on(self, event_type):\n \"\"\"注册事件监听器\"\"\"\n def decorator(func):\n self._listeners.append((event_type, func))\n return func\n return decorator\n \n def emit(self, event):\n \"\"\"触发事件\"\"\"\n self._event_bus.emit(event)\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py](#)\n\n### FlowContext 上下文管理\n\nFlowContext 提供了流程内的状态共享机制，允许不同的事件处理器之间传递数据：\n\n```python\nclass FlowContext:\n def __init__(self, initial_state=None):\n self._state = initial_state or {}\n \n def set(self, key, value):\n \"\"\"设置状态值\"\"\"\n self._state[key] = value\n \n def get(self, key, default=None):\n \"\"\"获取状态值\"\"\"\n return self._state.get(key, default)\n \n def to_dict(self):\n \"\"\"导出为字典\"\"\"\n return self._state.copy()\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow_context.py](#)\n\n### FlowConfig 配置管理\n\nFlowConfig 负责管理工作流的配置信息，包括事件路由规则、超时设置等：\n\n```python\nclass FlowConfig:\n def __init__(\n self,\n max_retries: int = 3,\n timeout: int = 3600,\n enable_persistence: bool = True\n ):\n self.max_retries = max_retries\n self.timeout = timeout\n self.enable_persistence = enable_persistence\n```\n\n资料来源：[lib/crewai/src/crewai/flow/flow_config.py](#)\n\n## 事件驱动架构\n\n### 事件总线模式\n\nFlow 采用事件总线（Event Bus）模式进行事件分发，所有事件通过中央总线进行路由：\n\n```mermaid\ngraph TD\n A[事件源] --> B[EventBus 事件总线]\n B --> C[监听器 A]\n B --> D[监听器 B]\n B --> E[监听器 C]\n C --> F[事件处理]\n D --> G[事件处理]\n E --> H[事件处理]\n```\n\n事件总线的核心职责包括：\n\n- 维护事件类型与监听器的映射关系\n- 按顺序触发匹配的监听器\n- 处理事件传播中的异常\n\n资料来源：[lib/crewai/src/crewai/flow/flow.py](#)\n\n### 事件类型分类\n\nFlow 支持多种事件类型，覆盖完整的工作流生命周期：\n\n| 事件类别 | 描述 | 使用场景 |\n|----------|------|----------|\n| Crew 生命周期事件 | Crew 启动、完成、失败等 | 协调多 Crew 执行顺序 |\n| Agent 执行事件 | Agent 任务分配、执行结果 | 监控 Agent 状态 |\n| Task 管理事件 | 任务创建、执行、完成 | 任务依赖管理 |\n| Tool 使用事件 | 工具调用及结果 | 工具使用审计 |\n| Knowledge 检索事件 | 知识库查询 | RAG 相关处理 |\n| LLM 调用事件 | 模型交互记录 | 成本和性能监控 |\n| Memory 操作事件 | 记忆读写操作 | 会话状态管理 |\n| Flow 执行事件 | Flow 特有的流程控制 | 事件路由决策 |\n| Safety 事件 | 安全防护触发 | 内容过滤和验证 |\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n### 事件监听装饰器\n\nFlow 提供了三个核心装饰器用于定义事件处理器：\n\n| 装饰器 | 功能 | 示例 |\n|--------|------|------|\n| `@start` | 定义流程启动时的初始事件 | 触发第一个 Crew |\n| `@listen` | 监听特定事件并处理 | 响应 Crew 完成事件 |\n| `@router` | 根据条件路由到不同处理路径 | 条件分支逻辑 |\n\n```python\nfrom crewai.flow.flow import Flow, start, listen, router\n\nclass MyFlow(Flow):\n @start()\n def begin(self):\n \"\"\"流程启动事件\"\"\"\n return {\"action\": \"start_research\"}\n \n @listen(\"research_complete\")\n def process_results(self, event):\n \"\"\"监听研究完成事件\"\"\"\n return {\"action\": \"analyze\"}\n \n @router()\n def route_by_quality(self, event):\n \"\"\"条件路由\"\"\"\n if event.get(\"quality_score\", 0) > 0.8:\n return \"high_quality_path\"\n return \"standard_path\"\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 持久化层\n\n### SQLite 持久化\n\nFlow 内置了基于 SQLite 的持久化方案，用于保存工作流执行状态：\n\n```python\nclass SQLitePersistence:\n def __init__(self, db_path: str = \"crewai_flow.db\"):\n self.db_path = db_path\n \n def save_state(self, flow_id: str, state: dict):\n \"\"\"保存流程状态\"\"\"\n pass\n \n def load_state(self, flow_id: str) -> dict:\n \"\"\"加载流程状态\"\"\"\n pass\n \n def save_event(self, event: dict):\n \"\"\"保存事件历史\"\"\"\n pass\n```\n\n资料来源：[lib/crewai/src/crewai/flow/persistence/sqlite.py](#)\n\n### 持久化装饰器\n\n提供了用于标记持久化行为的装饰器：\n\n```python\n@persistence\nclass MyFlow(Flow):\n \"\"\"启用自动持久化的 Flow\"\"\"\n pass\n```\n\n资料来源：[lib/crewai/src/crewai/flow/persistence/decorators.py](#)\n\n### 持久化配置\n\n持久化支持以下配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `enable_persistence` | bool | True | 是否启用持久化 |\n| `db_path` | str | \"crewai_flow.db\" | 数据库路径 |\n| `auto_save` | bool | True | 是否自动保存状态 |\n| `save_interval` | int | 60 | 自动保存间隔（秒） |\n\n## 使用模式\n\n### 顺序执行模式\n\n适用于线性工作流，下一个任务依赖上一个任务的结果：\n\n```mermaid\ngraph LR\n A[开始] --> B[任务 1]\n B --> C[任务 2]\n C --> D[任务 3]\n D --> E[结束]\n```\n\n### 并行执行模式\n\n多个任务可以同时执行，提高效率：\n\n```mermaid\ngraph TD\n A[开始] --> B[任务 A]\n A --> C[任务 B]\n A --> D[任务 C]\n B --> E[汇合]\n C --> E\n D --> E\n E --> F[完成]\n```\n\n### 条件路由模式\n\n根据事件内容动态选择处理路径：\n\n```mermaid\ngraph TD\n A[事件] --> B{条件判断}\n B -->|条件 A| C[处理 A]\n B -->|条件 B| D[处理 B]\n B -->|条件 C| E[处理 C]\n C --> F[结束]\n D --> F\n E --> F\n```\n\n## 完整示例\n\n### 项目结构\n\n```\nmy_flow_project/\n├── src/\n│ └── my_flow/\n│ ├── __init__.py\n│ ├── crew.py # Crew 定义\n│ ├── flow.py # Flow 定义\n│ └── main.py # 入口文件\n└── config/\n ├── agents.yaml\n └── tasks.yaml\n```\n\n### Flow 定义示例\n\n```python\n# src/my_flow/flow.py\nfrom crewai.flow.flow import Flow\nfrom crewai import Crew, Agent, Task\nfrom crewai.flow.flow_context import FlowContext\nfrom pydantic import BaseModel\n\nclass FlowState(BaseModel):\n research_results: str = \"\"\n analysis_results: str = \"\"\n final_report: str = \"\"\n\nclass ResearchFlow(Flow):\n def __init__(self):\n super().__init__()\n self.state = FlowContext()\n \n def initialize_crew(self):\n \"\"\"初始化 Crew\"\"\"\n researcher = Agent(\n role=\"Researcher\",\n goal=\"Research the topic thoroughly\",\n backstory=\"Expert researcher\"\n )\n analyzer = Agent(\n role=\"Analyzer\",\n goal=\"Analyze research findings\",\n backstory=\"Expert analyst\"\n )\n \n research_task = Task(\n description=\"Research {topic}\",\n expected_output=\"Comprehensive research report\",\n agent=researcher\n )\n \n analysis_task = Task(\n description=\"Analyze research results\",\n expected_output=\"Analysis summary\",\n agent=analyzer\n )\n \n return Crew(\n agents=[researcher, analyzer],\n tasks=[research_task, analysis_task],\n process=\"sequential\"\n )\n \n def crew_callback(self, crew, output):\n \"\"\"Crew 执行回调\"\"\"\n self.state.set(\"last_output\", output.raw)\n return output\n\n# 导出 kickoff 方法供 CLI 调用\ndef kickoff():\n flow = ResearchFlow()\n result = flow.kickoff()\n return result\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/flow/main.py](#)\n\n### 入口文件\n\n```python\n# src/my_flow/main.py\nfrom crewai import Crew\nfrom crewai.flow.flow import Flow\nfrom crewai.project import CrewBase, agent, crew, task\n\n@CrewBase\nclass MyFlowCrew():\n \"\"\"Flow 内部使用的 Crew\"\"\"\n agents: list\n tasks: list\n \n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n verbose=True\n )\n\ndef run_flow(topic: str):\n \"\"\"运行 Flow\"\"\"\n flow = MyFlowCrew()\n result = flow.kickoff(inputs={\"topic\": topic})\n return result\n\nif __name__ == \"__main__\":\n result = run_flow(\"AI Agents\")\n print(result)\n```\n\n## CLI 命令\n\nFlow 项目支持以下命令行操作：\n\n| 命令 | 描述 |\n|------|------|\n| `crewai create flow ` | 创建新的 Flow 项目 |\n| `crewai run` | 运行 Flow（自动检测 pyproject.toml） |\n| `crewai flow kickoff` | 旧版 Flow 执行命令 |\n\n```bash\n# 创建 Flow 项目\ncrewai create flow my_flow --skip_provider\n\n# 安装依赖\ncrewai install\n\n# 运行 Flow\ncrewai run\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/AGENTS.md](#)\n\n## 最佳实践\n\n### 结构化状态管理\n\n始终使用 Pydantic 模型定义 Flow 状态，而非普通的字典：\n\n```python\nfrom pydantic import BaseModel\n\nclass FlowState(BaseModel):\n topic: str\n research_data: dict = {}\n analysis_result: str = \"\"\n report_path: str = \"\"\n```\n\n这样可以获得更好的类型检查和 IDE 支持。\n\n### 事件命名规范\n\n使用清晰的事件命名约定，便于追踪和调试：\n\n- `crew_kickoff_started`: Crew 开始执行\n- `crew_kickoff_completed`: Crew 执行完成\n- `task_completed`: 单个任务完成\n- `error_occurred`: 错误发生\n\n### 异常处理\n\n在事件处理器中添加适当的异常处理：\n\n```python\n@listen(\"external_event\")\ndef handle_external(self, event):\n try:\n result = process_event(event)\n return {\"status\": \"success\", \"data\": result}\n except Exception as e:\n return {\"status\": \"error\", \"message\": str(e)}\n```\n\n### 超时配置\n\n对于可能长时间运行的操作，设置合理的超时时间：\n\n```python\nflow_config = FlowConfig(\n timeout=3600, # 1 小时\n max_retries=3\n)\n```\n\n## 与 Crew 的对比\n\n| 特性 | Crew | Flow |\n|------|------|------|\n| **定位** | 自主性（Autonomy） | 精确性（Precise） |\n| **执行模式** | 并行/层次化 | 事件驱动 |\n| **任务协调** | 自动委托 | 显式路由 |\n| **适用场景** | 通用多 Agent 协作 | 复杂流程控制 |\n| **配置方式** | YAML + Python | Python 优先 |\n\n## 总结\n\nFlow 事件驱动工作流为 CrewAI 提供了强大的流程编排能力，特别适合以下场景：\n\n- 需要精确控制执行顺序的多步骤流程\n- 基于条件进行动态分支的业务逻辑\n- 需要保存和恢复执行状态的长时间运行任务\n- 需要事件日志和审计追踪的应用\n\n通过结合 Crew 的自主 Agent 能力和 Flow 的精确控制能力，开发者可以构建出既智能又可控的复杂 AI 工作流系统。\n\n---\n\n\n\n## Task 任务系统\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents), [Crew 智能体团队](#crews), [Flow 事件驱动工作流](#flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/task.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/task.py)\n- [lib/crewai/src/crewai/tasks/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/__init__.py)\n- [lib/crewai/src/crewai/tasks/conditional_task.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/conditional_task.py)\n- [lib/crewai/src/crewai/tasks/task_output.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/task_output.py)\n- [lib/crewai/src/crewai/tasks/llm_guardrail.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tasks/llm_guardrail.py)\n- [lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml](https://github.com/crewAIInc/crewAI/blob/main/lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml)\n \n\n# Task 任务系统\n\n## 概述\n\nTask 任务是 CrewAI 多智能体框架中的核心执行单元。每个 Task 代表一个具体的工作目标，由特定的 Agent 负责执行。Task 系统支持丰富的配置选项，包括输出结构化数据、任务依赖关系、条件执行、输出验证等功能。\n\nTask 系统的主要职责：\n\n- 定义具体的工作任务和预期输出\n- 管理 Agent 与 Task 之间的绑定关系\n- 处理任务之间的依赖关系和执行顺序\n- 支持结构化输出（Pydantic、JSON）\n- 提供输出验证和 Guardrails 机制\n\n## 核心组件\n\n### Task 类\n\n`Task` 是任务系统的核心类，位于 `lib/crewai/src/crewai/task.py`。\n\n```mermaid\nclassDiagram\n class Task {\n +str description\n +str expected_output\n +Agent agent\n +List~Task~ dependencies\n +str output_file\n +bool verbose\n +int max_iterations\n +float max_rpm\n +callbacks: List[Callback]\n +async_execute()\n +execute()\n +output: TaskOutput\n }\n```\n\n### TaskOutput 类\n\n`TaskOutput` 类封装任务的执行结果。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `description` | str | 任务描述 |\n| `pydantic` | BaseModel | Pydantic 模型实例（结构化输出） |\n| `json_dict` | dict | JSON 格式输出 |\n| `text` | str | 纯文本输出 |\n| `summary` | str | 任务执行摘要 |\n\n资料来源：[lib/crewai/src/crewai/tasks/task_output.py]()\n\n### ConditionalTask 类\n\n条件任务允许根据运行时条件决定是否执行任务。\n\n```python\n@task\ndef conditional_research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n condition=lambda context: len(context.get('topics', [])) > 0\n )\n```\n\n资料来源：[lib/crewai/src/crewai/tasks/conditional_task.py]()\n\n## Task 属性详解\n\n### 基础属性\n\n| 属性 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `description` | str | 是 | 任务的详细描述，描述 Agent 需要完成的工作 |\n| `expected_output` | str | 是 | 期望的输出格式和内容说明 |\n| `agent` | Agent | 否 | 负责执行此任务的 Agent，可为空让 Crew 自动分配 |\n| `dependencies` | List[Task] | 否 | 任务依赖列表，必须在依赖任务完成后才能执行 |\n| `output_file` | str | 否 | 输出文件路径，任务结果将写入此文件 |\n\n### 执行控制属性\n\n| 属性 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `verbose` | bool | False | 是否启用详细输出模式 |\n| `max_iterations` | int | 20 | 最大迭代次数，防止无限循环 |\n| `max_rpm` | int | 0 | 每分钟最大请求数（0 表示不限制） |\n| `respect_context_window` | bool | True | 是否尊重上下文窗口限制 |\n\n### 输出配置属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `output_pydantic` | BaseModel | Pydantic 模型类，用于结构化输出验证 |\n| `output_json` | Type[BaseModel] | JSON Schema 模型，用于 JSON 输出 |\n| `callback` | Any | 任务完成后的回调函数 |\n\n资料来源：[lib/crewai/src/crewai/task.py]()\n\n## Guardrails 机制\n\nGuardrails 用于验证和约束任务输出，确保输出符合预期标准。\n\n### LLM Guardrail\n\n基于 LLM 的输出验证器。\n\n```python\nfrom crewai.tasks.llm_guardrail import LLMGuardrail\n\nguardrail = LLMGuardrail(\n llm=agent.llm,\n threshold=0.7\n)\n```\n\n### Hallucination Guardrail\n\n检测输出中的幻觉内容（事实性错误）。\n\n```python\nfrom crewai.tasks.hallucination_guardrail import HallucinationGuardrail\n\nguardrail = HallucinationGuardrail(\n llm=agent.llm,\n context=\"参考文档内容...\",\n threshold=8.0\n)\n```\n\n| Guardrail 类型 | 用途 | 适用场景 |\n|---------------|------|----------|\n| `LLMGuardrail` | 通用的 LLM 输出验证 | 格式检查、风格验证 |\n| `HallucinationGuardrail` | 幻觉检测 | 事实性内容验证 |\n\n资料来源：[lib/crewai/src/crewai/tasks/llm_guardrail.py]()\n\n## 任务依赖与执行流程\n\n### 依赖关系管理\n\n```mermaid\ngraph TD\n A[Task A: 研究任务] --> B[Task B: 分析任务]\n A --> C[Task C: 报告撰写]\n B --> C\n D[Task D: 条件任务] -->|仅当条件满足| E[Task E: 后续任务]\n```\n\n### 顺序执行流程\n\n在 `Process.sequential` 模式下，任务按依赖顺序执行：\n\n1. 执行没有依赖的任务\n2. 等待所有依赖任务完成\n3. 收集依赖任务的输出作为上下文\n4. 执行当前任务\n5. 重复直到所有任务完成\n\n```python\nfrom crewai import Crew, Process, Task, Agent\n\nresearcher = Agent(role=\"研究员\", goal=\"收集信息\", backstory=\"...\")\nanalyst = Agent(role=\"分析师\", goal=\"分析数据\", backstory=\"...\")\n\nresearch_task = Task(\n description=\"研究最新 AI 发展\",\n expected_output=\"AI 发展摘要\",\n agent=researcher\n)\n\nanalysis_task = Task(\n description=\"分析研究结果\",\n expected_output=\"深度分析报告\",\n agent=analyst,\n dependencies=[research_task] # 依赖于研究任务\n)\n\ncrew = Crew(\n agents=[researcher, analyst],\n tasks=[research_task, analysis_task],\n process=Process.sequential\n)\n```\n\n资料来源：[lib/crewai/src/crewai/task.py:1-200]()\n\n## YAML 配置\n\n### tasks.yaml 配置示例\n\n```yaml\n# lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml\n\nresearch_task:\n description: >\n 深入研究 {topic} 相关信息，收集最新发展和趋势。\n 这包括新闻文章、学术论文和行业报告。\n expected_output: >\n 一份结构化的研究报告，包含关键发现、\n 数据来源和趋势分析。\n agent: researcher\n\nreporting_task:\n description: >\n 基于研究报告，创建一份全面的报告\n expected_output: >\n 一份完整的报告，包含主要主题，\n 每个主题都有详细信息。格式为 markdown，不包含代码块。\n agent: reporting_analyst\n output_file: report.md\n```\n\n### 条件任务配置\n\n```yaml\nconditional_research_task:\n description: >\n 仅当存在特定主题时执行深入研究\n expected_output: >\n 针对指定主题的详细研究报告\n agent: researcher\n condition: \"topics_exist\" # 条件标识符\n```\n\n资料来源：[lib/cli/src/crewai_cli/templates/crew/config/tasks.yaml]()\n\n## 编程式创建 Task\n\n### 基本用法\n\n```python\nfrom crewai import Agent, Task\n\nagent = Agent(\n role=\"高级数据研究员\",\n goal=\"发现 {topic} 的最新发展\",\n backstory=\"你是一名资深研究员...\"\n)\n\ntask = Task(\n description=\"深入研究 {topic}\",\n expected_output=\"一份详细的研究报告\",\n agent=agent,\n verbose=True\n)\n```\n\n### 结构化输出\n\n```python\nfrom pydantic import BaseModel, Field\nfrom crewai import Task\n\nclass ResearchOutput(BaseModel):\n summary: str = Field(description=\"研究摘要\")\n key_findings: list[str] = Field(description=\"关键发现\")\n sources: list[str] = Field(description=\"数据来源\")\n\ntask = Task(\n description=\"研究 AI Agents\",\n expected_output=\"结构化的研究结果\",\n agent=agent,\n output_pydantic=ResearchOutput\n)\n```\n\n### 带依赖的任务\n\n```python\nanalysis_task = Task(\n description=\"分析研究报告\",\n expected_output=\"分析结论\",\n agent=analyst,\n dependencies=[research_task] # 等待研究任务完成\n)\n```\n\n### 输出到文件\n\n```python\nreport_task = Task(\n description=\"撰写报告\",\n expected_output=\"完整的报告文档\",\n agent=writer,\n output_file=\"report.md\" # 结果将写入此文件\n)\n```\n\n## 任务执行上下文\n\n### 上下文传递机制\n\n```mermaid\ngraph LR\n A[Task A 输出] -->|context| B[Task B 输入]\n B -->|context| C[Task C 输入]\n C -->|最终结果| D[Result]\n```\n\n当一个任务完成后，其输出（`TaskOutput`）会自动传递给依赖它的任务作为上下文。上下文包含：\n\n- `task_output.text`: 文本输出\n- `task_output.pydantic`: Pydantic 模型实例\n- `task_output.json_dict`: JSON 字典格式\n- `task_output.summary`: 执行摘要\n\n### 访问上下文\n\n```python\ndef analysis_callback(context: dict):\n previous_results = context.get('previous_tasks', [])\n for result in previous_results:\n print(result.text)\n\ntask = Task(\n description=\"基于之前结果继续分析\",\n expected_output=\"深入分析\",\n agent=analyst,\n dependencies=[research_task],\n callback=analysis_callback\n)\n```\n\n## 最佳实践\n\n### 1. 清晰的任务描述\n\n```python\n# ✅ 推荐：清晰、具体的描述\ntask = Task(\n description=\"从 2024 年 1 月至 6 月的财经新闻中提取关于 AI 投资的信息\",\n expected_output=\"JSON 格式的投资信息列表，包含公司名、投资金额、投资轮次\"\n)\n\n# ❌ 避免：模糊的描述\ntask = Task(\n description=\"查一下新闻\"\n)\n```\n\n### 2. 明确的预期输出\n\n```python\ntask = Task(\n description=\"分析销售数据\",\n expected_output=\"\"\"\n 格式：Markdown 表格\n 列：产品名称 | 销量 | 增长率 | 市场份额\n 包含趋势分析和改进建议\n \"\"\"\n)\n```\n\n### 3. 合理的任务粒度\n\n- 单个任务应该完成一个明确的目标\n- 避免将多个不相关的任务合并为一个\n- 使用依赖关系组织复杂工作流\n\n### 4. 任务依赖规划\n\n```python\n# 正确的依赖设计\ntask_1 = Task(description=\"收集原始数据\", ...)\ntask_2 = Task(description=\"清洗数据\", dependencies=[task_1], ...)\ntask_3 = Task(description=\"数据分析\", dependencies=[task_2], ...)\ntask_4 = Task(description=\"生成可视化\", dependencies=[task_3], ...)\n```\n\n## 与 CrewBase 装饰器集成\n\n### 使用装饰器定义任务\n\n```python\nfrom crewai import Agent, Crew, Process, Task\nfrom crewai.project import CrewBase, agent, task\nfrom typing import List\n\n@CrewBase\nclass ResearchCrew():\n agents: List[Agent]\n tasks: List[Task]\n \n @task\n def research_task(self) -> Task:\n return Task(\n config=self.tasks_config['research_task'],\n )\n\n @task\n def reporting_task(self) -> Task:\n return Task(\n config=self.tasks_config['reporting_task'],\n output_file='report.md'\n )\n\n @crew\n def crew(self) -> Crew:\n return Crew(\n agents=self.agents,\n tasks=self.tasks,\n process=Process.sequential,\n verbose=True,\n )\n```\n\n资料来源：[lib/crewai/src/crewai/tasks/__init__.py]()\n\n## 执行状态与监控\n\n### 任务状态\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建任务\n Pending --> InProgress: 开始执行\n InProgress --> Completed: 正常完成\n InProgress --> Failed: 执行错误\n InProgress --> Retrying: 重试中\n Failed --> [*]\n Completed --> [*]\n```\n\n### 迭代控制\n\n```python\ntask = Task(\n description=\"复杂分析任务\",\n expected_output=\"分析结果\",\n max_iterations=10, # 最多迭代 10 次\n max_rpm=5 # 每分钟最多 5 次请求\n)\n```\n\n### Verbose 模式\n\n```python\n# 启用详细输出\ntask = Task(\n description=\"搜索并分析\",\n expected_output=\"结果摘要\",\n verbose=True # 显示详细执行日志\n)\n```\n\n## 总结\n\nTask 任务系统是 CrewAI 框架的核心组成部分，提供了：\n\n- **灵活的配置**：支持 YAML 和编程式两种定义方式\n- **结构化输出**：通过 Pydantic 模型实现类型安全的输出\n- **依赖管理**：支持任务的串行和条件执行\n- **输出验证**：Guardrails 机制确保输出质量\n- **上下文传递**：任务之间自动共享执行结果\n\n通过合理使用 Task 系统，可以构建复杂的多智能体工作流，实现自动化的问题解决流程。\n\n---\n\n\n\n## LLM 集成与提供者\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/llm.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llm.py)\n- [lib/crewai/src/crewai/llms/base_llm.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/base_llm.py)\n- [lib/crewai/src/crewai/llms/providers/openai/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/openai/completion.py)\n- [lib/crewai/src/crewai/llms/providers/anthropic/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/anthropic/completion.py)\n- [lib/crewai/src/crewai/llms/providers/bedrock/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/bedrock/completion.py)\n- [lib/crewai/src/crewai/llms/providers/gemini/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/gemini/completion.py)\n- [lib/crewai/src/crewai/llms/providers/azure/completion.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/llms/providers/azure/completion.py)\n- [lib/crewai/src/crewai/hooks/llm_hooks.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/hooks/llm_hooks.py)\n\n \n\n# LLM 集成与提供者\n\n## 概述\n\nCrewAI 框架的 LLM（大型语言模型）集成系统为 AI Agent 提供了灵活的多提供者支持。该系统采用模块化架构，支持 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure 等主流 LLM 提供者，同时允许通过统一接口自定义配置。\n\n## 架构设计\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[Agent] --> B[LLM 接口层]\n B --> C[BaseLLM 抽象基类]\n C --> D[OpenAI Provider]\n C --> E[Anthropic Provider]\n C --> F[Gemini Provider]\n C --> G[Bedrock Provider]\n C --> H[Azure Provider]\n C --> I[自定义 Provider]\n```\n\n### 核心文件结构\n\n| 层级 | 文件路径 | 职责 |\n|------|----------|------|\n| 主接口 | `lib/crewai/src/crewai/llm.py` | LLM 主类，封装调用逻辑 |\n| 抽象基类 | `lib/crewai/src/crewai/llms/base_llm.py` | 定义提供者接口规范 |\n| 提供者实现 | `lib/crewai/src/crewai/llms/providers/*/completion.py` | 各提供者的具体实现 |\n| 钩子系统 | `lib/crewai/src/crewai/hooks/llm_hooks.py` | LLM 调用生命周期钩子 |\n\n## LLM 配置方式\n\n### 通过 Agent 配置\n\n在创建 Agent 时直接指定 LLM：\n\n```python\nfrom crewai import Agent\nfrom crewai.llm import LLM\n\nagent = Agent(\n role=\"研究助手\",\n goal=\"深入研究指定主题\",\n backstory=\"经验丰富的领域专家\",\n llm=LLM(model=\"gpt-4\", temperature=0.7)\n)\n```\n\n### 通过 config 字典配置\n\n支持使用配置字典自定义模型和嵌入层：\n\n```python\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n temperature=0.5,\n top_p=1,\n stream=True,\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n资料来源：[lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md)\n\n## 支持的 LLM 提供者\n\n### 提供者配置对照表\n\n| 提供者 | 模型标识 | 配置参数 |\n|--------|----------|----------|\n| OpenAI | `gpt-4`, `gpt-4o`, `gpt-4o-mini` | temperature, max_tokens, top_p |\n| Anthropic | `claude-3-5-sonnet`, `claude-3-opus` | temperature, max_tokens |\n| Google Gemini | `gemini-pro`, `gemini-2.0-flash` | temperature, top_p |\n| AWS Bedrock | `anthropic.claude-*`, `amazon.titan-*` | region, model_id |\n| Azure | Azure OpenAI 部署名 | api_version, api_base |\n| Ollama | 本地模型 | model, base_url |\n\n### OpenAI Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/openai/completion.py\nclass OpenAICompletion:\n \"\"\"处理 OpenAI API 调用的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n self.temperature = kwargs.get(\"temperature\", 0.7)\n```\n\n### Anthropic Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/anthropic/completion.py\nclass AnthropicCompletion:\n \"\"\"Anthropic Claude 系列模型的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n self.max_tokens = kwargs.get(\"max_tokens\", 4096)\n```\n\n### Bedrock Provider 实现\n\n支持 AWS Bedrock 上的多种模型，包括 Anthropic Claude 和 Amazon Titan 系列：\n\n```python\n# lib/crewai/src/crewai/llms/providers/bedrock/completion.py\nclass BedrockCompletion:\n \"\"\"AWS Bedrock 提供者实现\"\"\"\n \n def __init__(self, model: str, region: str = \"us-east-1\", **kwargs):\n self.model = model\n self.region = region\n self.aws_access_key = kwargs.get(\"aws_access_key_id\")\n self.aws_secret_key = kwargs.get(\"aws_secret_access_key\")\n```\n\n### Gemini Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/gemini/completion.py\nclass GeminiCompletion:\n \"\"\"Google Gemini 模型的提供者实现\"\"\"\n \n def __init__(self, model: str, **kwargs):\n self.model = model\n self.api_key = kwargs.get(\"api_key\")\n```\n\n### Azure Provider 实现\n\n```python\n# lib/crewai/src/crewai/llms/providers/azure/completion.py\nclass AzureCompletion:\n \"\"\"Azure OpenAI Service 提供者实现\"\"\"\n \n def __init__(self, \n deployment_name: str,\n api_base: str,\n api_version: str = \"2024-02-01\",\n **kwargs):\n self.deployment_name = deployment_name\n self.api_base = api_base\n self.api_version = api_version\n```\n\n## BaseLLM 抽象基类\n\n所有 LLM 提供者必须继承自 `BaseLLM`，实现标准接口：\n\n```python\n# lib/crewai/src/crewai/llms/base_llm.py\nfrom abc import ABC, abstractmethod\n\nclass BaseLLM(ABC):\n \"\"\"LLM 提供者抽象基类\"\"\"\n \n @abstractmethod\n def call(self, prompt: str, **kwargs) -> str:\n \"\"\"执行 LLM 调用\"\"\"\n pass\n \n @abstractmethod\n def get_model_name(self) -> str:\n \"\"\"获取当前模型名称\"\"\"\n pass\n \n @property\n @abstractmethod\n def supports_system_prompts(self) -> bool:\n \"\"\"检查提供者是否支持系统提示\"\"\"\n pass\n \n @property\n @abstractmethod\n def supports_function_calling(self) -> bool:\n \"\"\"检查提供者是否支持函数调用\"\"\"\n pass\n```\n\n## LLM 钩子系统\n\n### llm_hooks.py 生命周期钩子\n\n```mermaid\ngraph LR\n A[LLM 调用开始] --> B[on_llm_new_token]\n B --> C[token 处理中]\n C --> D[on_llm_new_token]\n D --> E[调用完成]\n E --> F[on_llm_end]\n A --> F2[on_llm_start]\n```\n\n### 钩子类型\n\n| 钩子方法 | 触发时机 | 用途 |\n|----------|----------|------|\n| `on_llm_start` | 调用开始前 | 记录请求参数、设置上下文 |\n| `on_llm_new_token` | 每个新 token 生成时 | 流式输出处理、实时反馈 |\n| `on_llm_end` | 调用完成后 | 记录响应、执行后处理 |\n| `on_llm_error` | 发生错误时 | 错误处理、告警通知 |\n\n### 自定义钩子实现\n\n```python\n# lib/crewai/src/crewai/hooks/llm_hooks.py\nclass LLMCallbackHandler:\n \"\"\"LLM 回调处理器基类\"\"\"\n \n def on_llm_start(self, serialized, prompts, **kwargs):\n \"\"\"LLM 调用开始时的钩子\"\"\"\n pass\n \n def on_llm_new_token(self, token: str, **kwargs):\n \"\"\"新 token 生成时的钩子\"\"\"\n pass\n \n def on_llm_end(self, response, **kwargs):\n \"\"\"LLM 调用结束时的钩子\"\"\"\n pass\n \n def on_llm_error(self, error, **kwargs):\n \"\"\"LLM 调用出错时的钩子\"\"\"\n pass\n```\n\n## LLM 主类接口\n\n### llm.py 核心功能\n\n```python\n# lib/crewai/src/crewai/llm.py\nclass LLM:\n \"\"\"统一的 LLM 接口类\"\"\"\n \n def __init__(\n self,\n model: str,\n provider: str = \"openai\",\n temperature: float = 0.7,\n max_tokens: int | None = None,\n **kwargs\n ):\n \"\"\"初始化 LLM 实例\n \n Args:\n model: 模型标识符 (如 \"gpt-4\", \"claude-3-opus\")\n provider: 提供者名称 (默认 \"openai\")\n temperature: 生成温度 (0.0-1.0)\n max_tokens: 最大 token 数量限制\n **kwargs: 提供者特定参数\n \"\"\"\n self.model = model\n self.provider = provider\n self.temperature = temperature\n self.max_tokens = max_tokens\n self._setup_provider(**kwargs)\n```\n\n### 主要方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `call()` | prompt, system_prompt, **kwargs | str | 执行文本生成 |\n| `call_with_functions()` | prompt, functions, **kwargs | dict | 执行带函数调用的生成 |\n| `supports_function_calling()` | - | bool | 检查函数调用支持 |\n| `supports_vision()` | - | bool | 检查视觉输入支持 |\n\n## 环境变量配置\n\n### OpenAI 配置\n\n```bash\nOPENAI_API_KEY=sk-...\nOPENAI_API_BASE=https://api.openai.com/v1 # 可选，自定义端点\n```\n\n### Anthropic 配置\n\n```bash\nANTHROPIC_API_KEY=sk-ant-...\n```\n\n### Google Gemini 配置\n\n```bash\nGOOGLE_API_KEY=AIza...\n```\n\n### AWS Bedrock 配置\n\n```bash\nAWS_ACCESS_KEY_ID=AKIA...\nAWS_SECRET_ACCESS_KEY=...\nAWS_REGION=us-east-1\n```\n\n### Azure 配置\n\n```bash\nAZURE_OPENAI_API_KEY=...\nAZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com\nAZURE_OPENAI_API_VERSION=2024-02-01\n```\n\n## 最佳实践\n\n### 模型选择指南\n\n```mermaid\ngraph TD\n A[任务类型] --> B{需要函数调用?}\n B -->|是| C{预算有限?|\n C -->|是| D[GPT-4o-mini + function calling]\n C -->|否| E[GPT-4 + function calling]\n B -->|否| F{需要长上下文?|\n F -->|是| G[Claude 3.5 Sonnet]\n F -->|否| H[GPT-4o]\n```\n\n### 温度参数建议\n\n| 任务场景 | 建议温度值 | 说明 |\n|----------|------------|------|\n| 代码生成 | 0.0 - 0.2 | 需要精确、一致的输出 |\n| 创意写作 | 0.7 - 0.9 | 需要多样性和创意 |\n| 问答总结 | 0.3 - 0.5 | 平衡准确性和多样性 |\n| 结构化输出 | 0.0 - 0.1 | 最大化输出格式一致性 |\n\n### 错误处理模式\n\n```python\nfrom crewai.llm import LLM\nfrom crewai.llms.base_llm import LLMGenerationError\n\nllm = LLM(model=\"gpt-4\", temperature=0.7)\n\ntry:\n response = llm.call(\n prompt=\"解释量子计算原理\",\n system_prompt=\"你是一位物理学家\"\n )\nexcept LLMGenerationError as e:\n print(f\"LLM 生成失败: {e}\")\n # 实现降级逻辑或重试机制\n```\n\n## 版本检查功能\n\nCrewAI 提供内置版本检查机制：\n\n```python\n# lib/crewai/src/crewai/version.py\nfrom crewai.version import (\n check_version,\n get_crewai_version,\n is_newer_version_available,\n get_latest_version_from_pypi,\n)\n\n# 检查当前版本\ncurrent = get_crewai_version()\n\n# 检查是否有新版本\nif is_newer_version_available():\n latest = get_latest_version_from_pypi()\n print(f\"有新版本可用: {latest}\")\n```\n\n## 总结\n\nCrewAI 的 LLM 集成系统提供了：\n\n- **多提供者支持**：OpenAI、Anthropic、Gemini、Bedrock、Azure 等\n- **统一接口**：`BaseLLM` 抽象基类确保一致性\n- **灵活配置**：支持环境变量和代码配置\n- **生命周期钩子**：完整的调用监控和扩展能力\n- **版本管理**：自动检查更新，保持兼容性\n\n此架构使开发者能够轻松切换不同的 LLM 提供者，同时保持应用代码的稳定性和可移植性。\n\n---\n\n\n\n## 工具系统与 MCP 集成\n\n### 相关页面\n\n相关主题：[MCP 与 A2A 协议](#mcp-a2a), [Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/tools/base_tool.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/base_tool.py)\n- [lib/crewai/src/crewai/tools/structured_tool.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/structured_tool.py)\n- [lib/crewai/src/crewai/tools/tool_calling.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/tools/tool_calling.py)\n- [lib/crewai/src/crewai/mcp/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/__init__.py)\n- [lib/crewai/src/crewai/mcp/client.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/client.py)\n- [lib/crewai/src/crewai/mcp/tool_resolver.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/tool_resolver.py)\n- [lib/crewai-tools/src/crewai_tools/tool.specs.json](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tool.specs.json)\n \n\n# 工具系统与 MCP 集成\n\n## 概述\n\nCrewAI 的工具系统是一个模块化的插件架构，允许 AI Agent 通过标准化的接口调用外部工具和资源。该系统支持两种主要的集成方式：内置工具和 MCP（Model Context Protocol）协议集成。通过统一的工具调用机制，Agent 可以执行文件操作、网络搜索、数据库查询、RAG 检索等复杂任务。\n\n工具系统的核心设计理念是将工具定义与工具执行解耦，每个工具通过 Pydantic Schema 定义参数和返回值，确保类型安全和参数验证。\n\n## 架构设计\n\n### 工具系统架构图\n\n```mermaid\ngraph TD\n subgraph \"工具层 Tool Layer\"\n A[BaseTool] --> B[StructuredTool]\n B --> C[内置工具]\n B --> D[MCP 工具]\n end\n \n subgraph \"工具注册层\"\n E[ToolRegistry] --> A\n F[MCPToolResolver] --> D\n end\n \n subgraph \"Agent 执行层\"\n G[Agent] --> H[ToolCalling]\n H --> E\n H --> F\n end\n \n subgraph \"外部系统\"\n I[MCP Server] --> F\n J[文件系统] --> C\n K[网络服务] --> C\n end\n```\n\n### 核心组件说明\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| BaseTool | `base_tool.py` | 工具基类，定义工具元数据和执行接口 |\n| StructuredTool | `structured_tool.py` | 结构化工具，支持 Pydantic 参数校验 |\n| ToolCalling | `tool_calling.py` | 工具调用控制器，管理工具执行流程 |\n| MCPToolResolver | `tool_resolver.py` | MCP 协议工具解析器 |\n| MCPClient | `client.py` | MCP 客户端，负责与 MCP 服务器通信 |\n\n## 内置工具详解\n\n### BaseTool 基类\n\n`BaseTool` 是所有工具的基类，提供了工具的基本属性和抽象方法。每个工具必须定义 `name`（名称）、`description`（描述）和 `_run`（执行方法）。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/base_tool.py\nname: str = \"tool_name\"\ndescription: str = \"A tool that...\"\n```\n\n### FileReadTool 文件读取工具\n\n`FileReadTool` 用于读取文件内容，支持按行范围读取和指定起始行。\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|-----|\n| file_path | str | 否 | 要读取的文件路径 |\n| start_line | int | 否 | 起始行号（从1开始） |\n| line_count | int | 否 | 要读取的行数 |\n\n```python\n# 初始化工具\ntool = FileReadTool(file_path=\"/path/to/file.txt\")\n\n# 读取整个文件\ncontent = tool.run()\n\n# 按行范围读取\ncontent = tool.run(start_line=100, line_count=50)\n```\n\n### FileWriterTool 文件写入工具\n\n`FileWriterTool` 用于将内容写入文件，支持自动创建目录。\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|-----|\n| filename | str | 是 | 要创建或覆盖的文件名 |\n| content | str | 是 | 要写入的内容 |\n| directory | str | 否 | 目标目录，默认为当前目录 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/file_writer_tool/README.md\nfrom crewai_tools import FileWriterTool\n\nfile_writer = FileWriterTool()\nresult = file_writer._run('example.txt', '测试内容', 'test_directory')\n```\n\n### RagTool 检索增强生成工具\n\n`RagTool` 用于从文件、目录或网页加载内容构建知识库，支持 RAG 检索场景。\n\n| 方法 | 参数 | 说明 |\n|-----|------|-----|\n| from_file | path: str | 从单个文件加载内容 |\n| from_directory | path: str | 从目录加载所有文件 |\n| from_web_page | url: str | 从网页加载内容 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/rag/README.md\nfrom crewai_tools.tools.rag_tool import RagTool\n\n# 从文件加载\nrag_tool = RagTool().from_file('path/to/file.txt')\n\n# 从目录加载\nrag_tool = RagTool().from_directory('path/to/directory')\n\n# 从网页加载\nrag_tool = RagTool().from_web_page('https://example.com')\n```\n\n### 搜索工具集\n\ncrewai_tools 提供了多种搜索工具，用于 Agent 执行网络搜索任务。\n\n#### SerplySearchTool\n\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| proxy_location | str | 代理位置代码（如 JP、GB、DE） |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/serply_api_tool/README.md\nfrom crewai_tools import SerplyWebSearchTool\n\nsearch_tool = SerplyWebSearchTool()\n```\n\n#### LinkupSearchTool\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|--------|-----|\n| query | str | - | 搜索关键词 |\n| depth | str | \"standard\" | 搜索深度 |\n| output_type | str | \"searchResults\" | 输出类型 |\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/linkup/README.md\nfrom crewai_tools import LinkupSearchTool\n\nlinkup_tool = LinkupSearchTool()\nresponse = linkup_tool._run(\n query=\"Women Nobel Prize Physics\",\n depth=\"standard\",\n output_type=\"searchResults\"\n)\n```\n\n#### SerplyScholarSearchTool\n\n学术搜索工具，用于检索学术论文和文献。\n\n```python\nfrom crewai_tools import SerplyScholarSearchTool\n\nscholar_tool = SerplyScholarSearchTool()\nscholar_tool = SerplyScholarSearchTool(proxy_location=\"GB\")\n```\n\n## MCP 协议集成\n\n### MCP 概述\n\nMCP（Model Context Protocol）是一种标准化的协议，允许 AI 模型与外部工具和服务进行交互。CrewAI 通过 MCP 集成，可以调用远程 MCP 服务器提供的工具。\n\n### MCP 架构图\n\n```mermaid\ngraph LR\n subgraph \"CrewAI 运行时\"\n A[Agent] --> B[ToolCalling]\n B --> C[MCPToolResolver]\n C --> D[MCPClient]\n end\n \n subgraph \"MCP 协议层\"\n D <-->|JSON-RPC| E[MCP Server]\n end\n \n subgraph \"外部服务\"\n E --> F[文件系统工具]\n E --> G[数据库工具]\n E --> H[API 工具]\n end\n```\n\n### MCP 客户端\n\n`MCPClient` 负责建立和管理与 MCP 服务器的连接，处理协议握手、消息序列化和工具调用路由。\n\n```python\n# 资料来源：lib/crewai/src/crewai/mcp/client.py\nclass MCPClient:\n def __init__(\n self,\n server_url: str,\n api_key: Optional[str] = None,\n timeout: int = 60\n ):\n \"\"\"初始化 MCP 客户端\"\"\"\n```\n\n### MCP 工具解析器\n\n`MCPToolResolver` 负责将 MCP 服务器提供的工具 schema 转换为 CrewAI 可识别的工具格式，并处理工具调用请求。\n\n```python\n# 资料来源：lib/crewai/src/crewai/mcp/tool_resolver.py\nclass MCPToolResolver:\n def resolve_tools(self) -> List[StructuredTool]:\n \"\"\"解析 MCP 服务器提供的工具列表\"\"\"\n \n def call_tool(self, tool_name: str, arguments: dict) -> Any:\n \"\"\"调用指定工具并返回结果\"\"\"\n```\n\n### MCP 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ToolCalling\n participant MCPToolResolver\n participant MCPClient\n participant MCPServer\n \n Agent->>ToolCalling: 请求执行工具\n ToolCalling->>MCPToolResolver: 查找工具定义\n MCPToolResolver->>MCPClient: 发起工具调用\n MCPClient->>MCPServer: 发送 JSON-RPC 请求\n MCPServer-->>MCPClient: 返回执行结果\n MCPClient-->>MCPToolResolver: 解析响应\n MCPToolResolver-->>ToolCalling: 返回结构化结果\n ToolCalling-->>Agent: 返回工具执行结果\n```\n\n## 工具注册与调用\n\n### 工具调用机制\n\n`ToolCalling` 模块负责管理工具的注册、查找和执行流程。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/tool_calling.py\nclass ToolCalling:\n def register_tool(self, tool: StructuredTool) -> None:\n \"\"\"注册新工具\"\"\"\n \n def execute_tool(self, tool_name: str, **kwargs) -> Any:\n \"\"\"执行指定工具\"\"\"\n```\n\n### StructuredTool 结构化工具\n\n`StructuredTool` 扩展了 `BaseTool`，使用 Pydantic Schema 进行参数验证和类型检查。\n\n```python\n# 资料来源：lib/crewai/src/crewai/tools/structured_tool.py\nfrom pydantic import BaseModel\n\nclass StructuredTool(BaseTool):\n args_schema: type[BaseModel]\n \n def _run(self, **kwargs) -> Any:\n \"\"\"执行工具逻辑\"\"\"\n```\n\n### Agent 中使用工具\n\n```python\n# 资料来源：lib/cli/src/crewai_cli/templates/AGENTS.md\nfrom crewai import Agent\nfrom crewai_tools import SerperDevTool\n\nresearcher = Agent(\n role=\"Senior Researcher\",\n goal=\"Uncover cutting-edge developments in {topic}\",\n backstory=\"An expert in online information retrieval...\",\n tools=[SerperDevTool()],\n verbose=True\n)\n```\n\n## 自定义工具开发\n\n### 工具开发模板\n\ncrewai 提供了标准化的工具开发模板，位于 `lib/cli/src/crewai_cli/templates/tool/`。\n\n```bash\ncrewai tool publish {{tool_name}}\ncrewai tool install {{tool_name}}\n```\n\n### 工具规范定义\n\n工具的元数据和参数规范定义在 `tool.specs.json` 中。\n\n```json\n// 资料来源：lib/crewai-tools/src/crewai_tools/tool.specs.json\n{\n \"name\": \"tool_name\",\n \"description\": \"Tool description\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {...}\n }\n}\n```\n\n### 工具开发示例\n\n```python\n# 创建自定义工具\nfrom crewai.tools.base_tool import BaseTool\nfrom pydantic import BaseModel\n\nclass MyToolInput(BaseModel):\n query: str\n limit: int = 10\n\nclass MyTool(BaseTool):\n name: str = \"my_custom_tool\"\n description: str = \"A custom tool for...\"\n args_schema: type[BaseModel] = MyToolInput\n \n def _run(self, query: str, limit: int = 10) -> str:\n # 工具执行逻辑\n return f\"Result for {query}\"\n```\n\n## 工具配置与模型自定义\n\n### LLM 和 Embedder 配置\n\n大多数工具支持自定义 LLM 和 Embedder 模型。\n\n```python\n# 资料来源：lib/crewai-tools/src/crewai_tools/tools/code_docs_search_tool/README.md\nfrom crewai_tools import CodeDocsSearchTool\n\ntool = CodeDocsSearchTool(\n config=dict(\n llm=dict(\n provider=\"ollama\",\n config=dict(\n model=\"llama2\",\n temperature=0.5,\n ),\n ),\n embedder=dict(\n provider=\"google\",\n config=dict(\n model=\"models/embedding-001\",\n task_type=\"retrieval_document\",\n ),\n ),\n )\n)\n```\n\n### 支持的 LLM 提供商\n\n| 提供商 | 配置值 | 说明 |\n|-------|--------|-----|\n| OpenAI | openai | GPT 系列模型 |\n| Anthropic | anthropic | Claude 系列模型 |\n| Google | google | Gemini 系列模型 |\n| Ollama | ollama | 本地 LLM |\n| Llama2 | llama2 | Meta Llama2 |\n\n## 工作流集成\n\n### Crew 中使用工具\n\n```python\n# 资料来源：lib/cli/src/crewai_cli/templates/AGENTS.md\nfrom crewai import Agent, Crew, Task\nfrom crewai.project import CrewBase, agent, crew, task\n\n@CrewBase\nclass ResearchCrew:\n agents_config = \"config/agents.yaml\"\n tasks_config = \"config/tasks.yaml\"\n \n @agent\n def researcher(self) -> Agent:\n return Agent(\n config=self.agents_config[\"researcher\"],\n tools=[SerperDevTool()],\n verbose=True,\n )\n```\n\n### Task 中配置工具\n\n```yaml\n# 在 tasks.yaml 中配置任务\nresearch_task:\n description: >\n Research the latest developments in {topic}\n expected_output: >\n A comprehensive report with sources and implications.\n agent: researcher\n tools: [search_tool]\n output_file: output/research.md\n```\n\n## 最佳实践\n\n### 工具选择策略\n\n1. **任务匹配**：根据任务类型选择最合适的工具\n2. **性能考虑**：优先使用轻量级工具，减少 API 调用开销\n3. **可靠性**：选择有稳定维护的官方工具\n4. **安全性**：敏感操作使用本地工具而非远程 API\n\n### 错误处理\n\n```python\ntry:\n result = tool._run(param=\"value\")\nexcept ToolExecutionError as e:\n logger.error(f\"Tool execution failed: {e}\")\n # 降级处理或重试逻辑\n```\n\n### 工具链组合\n\n多个工具可以组合使用实现复杂工作流：\n\n```python\n# 搜索 + 内容转换\nfrom crewai import Agent\nfrom crewai_tools import SerplyWebSearchTool, SerplyWebpageToMarkdownTool\n\nsearch_tool = SerplyWebSearchTool()\nconvert_to_markdown = SerplyWebpageToMarkdownTool()\n\nresearcher = Agent(\n role='Senior Researcher',\n goal='Uncover groundbreaking technologies in {topic}',\n tools=[search_tool, convert_to_markdown]\n)\n```\n\n## 总结\n\nCrewAI 的工具系统通过模块化的设计，为 AI Agent 提供了强大的外部能力扩展能力。内置工具覆盖了文件操作、网络搜索、RAG 检索等常见场景，而 MCP 协议集成则允许与任意支持 MCP 的外部服务进行交互。通过统一的工具调用接口和 Pydantic 参数校验机制，开发者可以快速构建功能丰富的多 Agent 应用。\n\n---\n\n\n\n## MCP 与 A2A 协议\n\n### 相关页面\n\n相关主题：[工具系统与 MCP 集成](#tools), [Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/mcp/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/__init__.py)\n- [lib/crewai/src/crewai/mcp/transports/stdio.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/stdio.py)\n- [lib/crewai/src/crewai/mcp/transports/sse.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/sse.py)\n- [lib/crewai/src/crewai/mcp/transports/http.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/mcp/transports/http.py)\n- [lib/crewai/src/crewai/a2a/__init__.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/__init__.py)\n- [lib/crewai/src/crewai/a2a/types.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/types.py)\n- [lib/crewai/src/crewai/a2a/utils/delegation.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/a2a/utils/delegation.py)\n \n\n# MCP 与 A2A 协议\n\n## 概述\n\n在 CrewAI 框架中，**MCP (Model Context Protocol)** 和 **A2A (Agent-to-Agent)** 是两个核心的通信协议，分别用于 Agent 与外部工具服务的连接以及 Agent 之间的互操作。这两个协议共同构成了 CrewAI 多智能体系统的通信基础设施，使 Agent 能够与外部系统进行无缝集成和协作。\n\n## 协议架构总览\n\n```mermaid\ngraph TB\n subgraph \"CrewAI 通信层\"\n A1[\"Agent 1\"] --> A2[\"Agent 2\"]\n A1 --> A3[\"Agent 3\"]\n A2 --> A3\n end\n \n subgraph \"A2A 协议层\"\n A2A[\"Agent-to-Agent 通信\"]\n DEL[\"委派工具\"]\n TYPES[\"类型定义\"]\n end\n \n subgraph \"MCP 协议层\"\n MCP[\"Model Context Protocol\"]\n STDIO[\"stdio 传输\"]\n SSE[\"SSE 传输\"]\n HTTP[\"HTTP 传输\"]\n end\n \n subgraph \"外部服务\"\n TOOL[\"外部工具服务\"]\n API[\"第三方 API\"]\n end\n \n A1 -.-> A2A\n A2 -.-> A2A\n A2A -.-> DEL\n MCP -.-> TOOL\n MCP -.-> STDIO\n MCP -.-> SSE\n MCP -.-> HTTP\n```\n\n## MCP 协议 (Model Context Protocol)\n\nMCP 协议是 CrewAI 用于与外部工具和服务进行通信的标准协议。它定义了 Agent 如何连接到外部工具、发送请求并接收响应。CrewAI 的 MCP 实现支持多种传输方式，以适应不同的部署场景。\n\n### MCP 模块结构\n\n```mermaid\ngraph TD\n MCP[\"crewai.mcp 模块\"]\n INIT[\"__init__.py
MCP 包初始化\"]\n \n subgraph \"传输层 (transports)\"\n STDIO[\"stdio.py
标准输入输出传输\"]\n SSE[\"sse.py
Server-Sent Events 传输\"]\n HTTP[\"http.py
HTTP 请求传输\"]\n end\n \n MCP --> INIT\n INIT --> STDIO\n INIT --> SSE\n INIT --> HTTP\n```\n\n### 传输方式详解\n\n#### stdio 传输\n\nstdio 传输是 MCP 协议最常用的传输方式之一，特别适用于本地进程通信和命令行工具集成。通过标准输入输出流进行数据交换，具有低延迟和简单可靠的特点。\n\n主要特点：\n\n- **同步通信**：使用标准输入输出进行同步消息交换\n- **进程管理**：适合启动和管理本地子进程\n- **错误处理**：内置进程错误捕获和日志记录机制\n- **超时控制**：支持请求超时配置\n\n#### SSE 传输\n\nServer-Sent Events (SSE) 传输适用于需要服务器推送场景的 MCP 通信。它允许服务器主动向客户端发送事件流，特别适合长时间运行的任务和实时状态更新。\n\n使用场景：\n\n- 实时日志流推送\n- 长时间任务的进度更新\n- 异步操作的完成通知\n\n#### HTTP 传输\n\nHTTP 传输是最通用的 MCP 通信方式，适用于与基于 REST API 的外部服务进行交互。它支持完整的 HTTP 协议特性，包括认证、会话管理和请求/响应模式。\n\n### MCP 配置参数\n\n| 参数名称 | 类型 | 说明 | 默认值 |\n|---------|------|------|--------|\n| `timeout` | int | 请求超时时间（秒） | 60 |\n| `max_retries` | int | 最大重试次数 | 3 |\n| `retry_delay` | int | 重试间隔时间（秒） | 1 |\n| `headers` | dict | HTTP 请求头 | {} |\n\n## A2A 协议 (Agent-to-Agent)\n\nA2A 协议是 CrewAI 框架中用于 Agent 之间进行通信和协作的协议。它定义了 Agent 如何相互发送消息、委派任务、共享状态和协调工作流程。A2A 协议的核心目标是实现多 Agent 系统中的无缝协作。\n\n### A2A 核心组件\n\n```mermaid\ngraph LR\n subgraph \"A2A 协议栈\"\n A2A_INIT[\"__init__.py
A2A 包初始化\"]\n TYPES[\"types.py
类型定义与数据模型\"]\n DELEG[\"delegation.py
任务委派工具\"]\n end\n \n subgraph \"A2A 类型体系\"\n REQ[\"请求类型\"]\n RESP[\"响应类型\"]\n TASK[\"任务类型\"]\n STATE[\"状态类型\"]\n end\n \n subgraph \"A2A 工具集\"\n DEL_TOOL[\"委派工具\"]\n ROUTING[\"路由工具\"]\n end\n \n A2A_INIT --> TYPES\n A2A_INIT --> DELEG\n TYPES --> REQ\n TYPES --> RESP\n TYPES --> TASK\n TYPES --> STATE\n DELEG --> DEL_TOOL\n DELEG --> ROUTING\n```\n\n### A2A 类型系统\n\nA2A 协议定义了一套完整的类型系统，用于描述 Agent 通信中的各种数据结构。这些类型包括请求、响应、任务描述、状态信息等。类型系统的设计遵循以下原则：\n\n**设计原则：**\n\n- **类型安全**：使用 Python 类型注解确保编译时和运行时类型检查\n- **可扩展性**：支持通过继承和组合扩展新类型\n- **序列化兼容**：支持 JSON 等常见序列化格式\n\n### 任务委派机制\n\n任务委派是 A2A 协议的核心功能之一，允许一个 Agent 将任务委托给另一个 Agent 执行。委派过程涉及多个步骤，包括任务描述构建、目标 Agent 选择、执行状态跟踪和结果收集。\n\n```mermaid\nsequenceDiagram\n participant Agent_A as Agent A (发起者)\n participant A2A as A2A 协议层\n participant DEL as 委派工具\n participant Agent_B as Agent B (执行者)\n \n Agent_A->>A2A: 创建任务委派请求\n A2A->>DEL: 验证委派权限\n DEL->>DEL: 检查 Agent B 可用性\n DEL->>Agent_B: 发送任务描述\n Agent_B->>Agent_B: 执行任务\n Agent_B-->>DEL: 返回任务结果\n DEL-->>A2A: 格式化响应\n A2A-->>Agent_A: 返回执行结果\n```\n\n### 委派工具 (delegation.py)\n\n`delegation.py` 模块提供了 A2A 协议中任务委派的核心实现。该模块包含以下主要功能：\n\n| 功能 | 说明 |\n|------|------|\n| `delegate_task()` | 将任务委派给指定的 Agent |\n| `check_agent_availability()` | 检查目标 Agent 是否可用 |\n| `track_delegation_status()` | 跟踪委派任务的状态 |\n| `collect_delegation_result()` | 收集委派任务的结果 |\n\n### A2A 消息流\n\n```mermaid\ngraph LR\n subgraph \"消息生命周期\"\n CREATE[\"创建消息\"] --> SERIALIZE[\"序列化\"]\n SERIALIZE --> SEND[\"发送\"]\n SEND --> RECEIVE[\"接收\"]\n RECEIVE --> DESERIALIZE[\"反序列化\"]\n DESERIALIZE --> PROCESS[\"处理\"]\n PROCESS --> RESPOND[\"响应\"]\n RESPOND --> COMPLETE[\"完成\"]\n end\n \n subgraph \"消息类型\"\n REQ[\"请求消息\"]\n RESP[\"响应消息\"]\n EVENT[\"事件消息\"]\n ERROR[\"错误消息\"]\n end\n \n CREATE -.-> REQ\n PROCESS -.-> RESP\n PROCESS -.-> EVENT\n PROCESS -.-> ERROR\n```\n\n## 协议比较与选择\n\n| 特性 | MCP | A2A |\n|------|-----|-----|\n| **主要用途** | Agent 与外部工具/服务通信 | Agent 之间相互通信 |\n| **传输方式** | stdio, SSE, HTTP | 内部消息传递 |\n| **协议层次** | 基础设施层 | 应用层 |\n| **典型场景** | 工具调用、数据获取 | 任务委派、协作处理 |\n| **状态管理** | 无状态请求/响应 | 有状态的对话上下文 |\n\n## 实际应用示例\n\n### MCP 使用场景\n\n1. **文件操作**：读取本地文件、写入日志\n2. **网络请求**：调用外部 API、获取网页内容\n3. **数据库访问**：查询和更新数据存储\n4. **搜索功能**：文档搜索、网络搜索\n\n### A2A 使用场景\n\n1. **复杂任务分解**：将复杂任务分解为多个子任务\n2. **专家咨询**：向特定领域的 Agent 请求专业知识\n3. **协作验证**：多个 Agent 协作验证结果\n4. **负载均衡**：根据 Agent 负载分配任务\n\n## 最佳实践\n\n### MCP 最佳实践\n\n- **连接复用**：对于频繁调用的服务，保持 MCP 连接复用\n- **超时设置**：根据任务性质合理设置超时时间\n- **错误重试**：实现指数退避的重试机制\n- **资源清理**：确保使用完毕后正确关闭连接\n\n### A2A 最佳实践\n\n- **任务粒度**：合理划分任务粒度，避免过度委派\n- **状态同步**：使用适当的状态同步机制保持 Agent 间一致性\n- **超时处理**：设置合理的任务执行超时时间\n- **结果聚合**：建立有效的结果聚合和处理机制\n\n## 安全考虑\n\n| 安全维度 | MCP | A2A |\n|----------|-----|-----|\n| **认证** | API Key / OAuth | Agent 身份验证 |\n| **授权** | 工具级别权限控制 | 任务委派权限验证 |\n| **传输加密** | HTTPS 支持 | 内部通信加密 |\n| **输入验证** | 参数校验 | 消息格式验证 |\n\n## 总结\n\nMCP 和 A2A 协议共同构成了 CrewAI 多智能体系统的通信基础。MCP 协议侧重于 Agent 与外部世界的连接，提供了多种灵活的传输方式；A2A 协议则专注于 Agent 之间的协作，实现了任务委派、状态共享和协调工作等功能。理解这两个协议的设计和使用方法，对于构建高效、可靠的多智能体系统至关重要。\n\n通过合理地结合使用 MCP 和 A2A 协议，开发者可以构建出功能强大、架构灵活的多智能体应用，实现复杂任务的自动化处理和智能协作。\n\n---\n\n\n\n## 记忆与知识管理系统\n\n### 相关页面\n\n相关主题：[Agent 智能体系统](#agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/crewai/src/crewai/memory/unified_memory.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/unified_memory.py)\n- [lib/crewai/src/crewai/memory/recall_flow.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/recall_flow.py)\n- [lib/crewai/src/crewai/memory/storage/lancedb_storage.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/memory/storage/lancedb_storage.py)\n- [lib/crewai/src/crewai/knowledge/knowledge.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/knowledge.py)\n- [lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py)\n- [lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py)\n- [lib/crewai/src/crewai/knowledge/source/crew_docling_source.py](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/knowledge/source/crew_docling_source.py)\n \n\n# 记忆与知识管理系统\n\nCrewAI 框架提供了一套完整的**记忆与知识管理系统**，用于支持多代理系统的上下文保持、跨会话学习和领域知识增强。该系统通过统一记忆模块和知识来源模块协同工作，使代理能够在长期运行中积累信息、保持状态连续性，并利用外部知识库进行推理。\n\n---\n\n## 系统概述\n\n### 设计目标\n\nCrewAI 的记忆与知识管理系统主要解决以下问题：\n\n| 问题领域 | 解决方案 |\n|---------|---------|\n| 上下文保持 | 统一记忆（Unified Memory）存储对话历史和任务执行记录 |\n| 跨会话学习 | 向量化存储支持语义检索，实现长期信息积累 |\n| 领域知识增强 | 知识来源（Knowledge Sources）模块加载外部文档 |\n| 代理状态管理 | 实体记忆和短时/长时记忆分类管理 |\n\n### 架构概览\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[Crew 实例] --> B[统一记忆模块]\n A --> C[知识来源模块]\n end\n \n subgraph \"记忆系统 Memory\"\n B --> D[短时记忆 Short-term]\n B --> E[长时记忆 Long-term]\n B --> F[实体记忆 Entities]\n B --> G[知识记忆 Knowledge]\n end\n \n subgraph \"存储层 Storage\"\n D --> H[内存存储 In-Memory]\n E --> I[向量数据库 LanceDB]\n F --> I\n G --> I\n end\n \n subgraph \"知识来源 Knowledge Sources\"\n C --> J[PDF 文档源]\n C --> K[CSV 数据源]\n C --> L[DOCling 源]\n end\n \n I --> M[向量嵌入模型]\n```\n\n---\n\n## 统一记忆模块\n\n统一记忆模块（Unified Memory）是 CrewAI 记忆系统的核心组件，负责协调管理不同类型的记忆存储。\n\n### 记忆类型分类\n\nCrewAI 将记忆划分为四种类型，分别处理不同维度的信息：\n\n| 记忆类型 | 用途 | 生命周期 | 存储方式 |\n|---------|------|---------|---------|\n| **短时记忆 (Short-term)** | 当前会话内的对话上下文 | 会话内 | 内存存储 |\n| **长时记忆 (Long-term)** | 历史会话积累的信息 | 持久化 | LanceDB 向量存储 |\n| **实体记忆 (Entities)** | 提取的实体信息和实体关系 | 可配置 | LanceDB 向量存储 |\n| **知识记忆 (Knowledge)** | 领域知识库检索结果 | 持久化 | LanceDB 向量存储 |\n\n### 记忆检索流程\n\n```mermaid\ngraph LR\n A[用户输入] --> B[Recall Flow]\n B --> C[短时记忆查询]\n B --> D[长时记忆查询]\n B --> E[实体记忆查询]\n B --> F[知识记忆查询]\n C --> G[相关记忆聚合]\n D --> G\n E --> G\n F --> G\n G --> H[增强上下文]\n H --> I[LLM 推理]\n```\n\n### 核心 API\n\n统一记忆模块提供以下核心方法：\n\n```python\n# 记忆写入\nmemory.insert(content: str, metadata: dict = None)\n\n# 记忆检索\nresults = memory.search(query: str, limit: int = 10)\n\n# 记忆重置\nmemory.reset(memory_type: str = \"all\")\n```\n\n---\n\n## 存储层实现\n\n### LanceDB 向量存储\n\nLanceDB 是 CrewAI 默认的向量数据库，用于持久化存储长时记忆、实体记忆和知识记忆。\n\n**核心特性**：\n\n| 特性 | 说明 |\n|-----|------|\n| 向量索引 | 支持 HNSW、FLAT 等索引类型 |\n| 相似度检索 | 基于余弦相似度的语义搜索 |\n| 元数据过滤 | 支持基于元数据的精确过滤 |\n| 持久化存储 | 本地文件系统存储，无需独立服务 |\n\n**配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `vector_dimension` | int | 1536 | 向量嵌入维度 |\n| `storage_path` | str | ./data/memory | 存储路径 |\n| `index_type` | str | \"hnsw\" | 索引类型 |\n\n### 检索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户查询\n participant M as Memory 模块\n participant V as Vector Store\n participant E as Embedding Model\n \n U->>M: search(query)\n M->>E: 生成查询向量\n E-->>M: query_vector\n M->>V: 相似度搜索\n V-->>M: 相关结果\n M->>M: 结果聚合与排序\n M-->>U: 检索结果\n```\n\n---\n\n## 知识来源模块\n\n知识来源（Knowledge Sources）模块允许 CrewAI 从外部文档中加载领域知识，为代理提供额外的参考资料。\n\n### 支持的文档类型\n\n| 文档类型 | 处理器 | 依赖库 |\n|---------|-------|-------|\n| PDF | `PDFKnowledgeSource` | pdfplumber, pypdf |\n| CSV | `CSVKnowledgeSource` | pandas |\n| DOCling | `CrewDoclingSource` | crewdocling |\n\n### 知识加载流程\n\n```mermaid\ngraph TD\n A[文档文件] --> B[解析器选择]\n B --> C{文档类型}\n C -->|PDF| D[PDF 解析器]\n C -->|CSV| E[CSV 解析器]\n C -->|DOCling| F[DOCling 解析器]\n \n D --> G[文本分块]\n E --> G\n F --> G\n \n G --> H[向量化处理]\n H --> I[存入向量存储]\n I --> J[可被代理检索]\n```\n\n### 使用示例\n\n```python\nfrom crewai import Agent, Task, Crew\nfrom crewai.knowledge import PDFKnowledgeSource\n\n# 加载知识来源\npdf_source = PDFKnowledgeSource(\n file_path=\"./documents/manual.pdf\",\n chunk_size=1000,\n chunk_overlap=200\n)\n\n# 创建代理并关联知识来源\nagent = Agent(\n role=\"技术顾问\",\n goal=\"基于知识库回答用户问题\",\n backstory=\"你是一个熟悉产品文档的专家\",\n knowledge_sources=[pdf_source]\n)\n\n# 创建任务\ntask = Task(\n description=\"回答用户关于产品功能的问题\",\n expected_output=\"基于文档的详细回答\",\n agent=agent\n)\n```\n\n---\n\n## CLI 记忆管理命令\n\nCrewAI CLI 提供了完整的记忆管理命令，用于重置和清理不同类型的记忆存储。\n\n### 命令列表\n\n| 命令 | 说明 | 适用范围 |\n|-----|------|---------|\n| `crewai reset-memories -a` | 重置所有记忆 | 全部记忆类型 |\n| `crewai reset-memories -s` | 重置短时记忆 | 当前会话 |\n| `crewai reset-memories -l` | 重置长时记忆 | 历史积累 |\n| `crewai reset-memories -e` | 重置实体记忆 | 实体信息 |\n| `crewai reset-memories -kn` | 重置知识记忆 | 知识来源 |\n| `crewai reset-memories -akn` | 重置代理知识 | 单代理知识 |\n\n### 使用示例\n\n```bash\n# 重置所有记忆（用于全新开始）\ncrewai reset-memories -a\n\n# 仅清理长时记忆（保留短时会话）\ncrewai reset-memories -l\n\n# 清理特定代理的知识\ncrewai reset-memories -akn\n```\n\n---\n\n## 最佳实践\n\n### 何时启用记忆\n\n| 场景 | 推荐配置 |\n|-----|---------|\n| 需要跨会话保持上下文 | 启用长时记忆 |\n| 当前任务依赖历史信息 | 启用短时+长时记忆 |\n| 领域特定问答 | 配置知识来源 |\n| 实体关系抽取 | 启用实体记忆 |\n\n### 配置建议\n\n```python\nfrom crewai import Crew\n\ncrew = Crew(\n agents=[...],\n tasks=[...],\n memory=True, # 启用统一记忆\n memory_config={\n \"short_term\": True,\n \"long_term\": True,\n \"entities\": True,\n \"knowledge\": True\n }\n)\n```\n\n### 性能优化\n\n1. **合理设置检索数量**：避免返回过多无关记忆，`limit` 参数建议设置为 5-10\n2. **知识分块策略**：大文档建议设置 `chunk_size=1000`, `chunk_overlap=200`\n3. **定期清理**：长时间运行的任务建议定期执行 `reset-memories -l`\n\n---\n\n## 源码文件索引\n\n| 模块 | 文件路径 | 主要功能 |\n|-----|---------|---------|\n| 统一记忆 | `lib/crewai/src/crewai/memory/unified_memory.py` | 记忆类型协调与聚合 |\n| 检索流程 | `lib/crewai/src/crewai/memory/recall_flow.py` | 记忆检索与上下文增强 |\n| 向量存储 | `lib/crewai/src/crewai/memory/storage/lancedb_storage.py` | LanceDB 持久化实现 |\n| 知识基类 | `lib/crewai/src/crewai/knowledge/knowledge.py` | 知识来源抽象 |\n| PDF 源 | `lib/crewai/src/crewai/knowledge/source/pdf_knowledge_source.py` | PDF 文档处理 |\n| CSV 源 | `lib/crewai/src/crewai/knowledge/source/csv_knowledge_source.py` | CSV 数据处理 |\n| Docling 源 | `lib/crewai/src/crewai/knowledge/source/crew_docling_source.py` | Docling 格式支持 |\n\n---\n\n## 总结\n\nCrewAI 的记忆与知识管理系统通过统一记忆模块和知识来源模块的双层架构，实现了：\n\n- **上下文连续性**：短时记忆保持会话状态，长时记忆实现跨会话学习\n- **语义检索能力**：基于向量数据库的相似度搜索，快速定位相关信息\n- **知识增强**：支持多种文档格式的知识加载，丰富代理的推理依据\n- **灵活的 CLI 管理**：提供完整的命令行工具进行记忆维护\n\n该系统是 CrewAI 多代理协作能力的重要支撑，尤其适用于需要长期运行和知识积累的复杂任务场景。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：crewAIInc/crewAI\n\n摘要：发现 23 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine。\n\n## 1. 安装坑 · 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c38215ebb04a4fbc6e7c6d2fdb2469 | https://github.com/crewAIInc/crewAI/issues/5708 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 运行坑 · 来源证据：[BUG] Wrong code in document\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] Wrong code in document\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_390380af45524e959d558b160597b38b | https://github.com/crewAIInc/crewAI/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：[FEATURE] Enhance the document about @persisit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Enhance the document about @persisit\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_effef000d4cf47a892f17850aa033610 | https://github.com/crewAIInc/crewAI/issues/5372 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_858a1a8bead2456289d686ec0d2d802c | https://github.com/crewAIInc/crewAI/issues/4877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `crewai` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:710601088 | https://github.com/crewAIInc/crewAI | repo=crewai; install=skills\n\n## 6. 安装坑 · 来源证据：1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcfa2a852812414a82683392c2888795 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：1.14.4a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0de86b993ffa4d9298726daa189abf49 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：1.14.5a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.5a4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6db6cd94b6ef4bffa23da215458565b4 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Scans the client database to extract existing policy details.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Scans the client database to extract existing policy details.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8201c73155314e67801bd0b81ea9820d | https://github.com/crewAIInc/crewAI/issues/5760 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:710601088 | https://github.com/crewAIInc/crewAI | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：1.14.5a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：1.14.5a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4094bb55c234f1581b9879efd4994c6 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff4d292bd8984a039527502ef51aed98 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：1.14.5a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e5616e4bf1f47f59e10e83c1849c86a | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：1.14.5a3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba25d089d674407d83a29ec4caff6284 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Question: integration path for Agent Threat Rules detection in crewai/security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Question: integration path for Agent Threat Rules detection in crewai/security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_05e39d8c109f4ed0a2974d448468229f | https://github.com/crewAIInc/crewAI/issues/5763 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_028fe9ebbcc943f5a7134e08d0ed9450 | https://github.com/crewAIInc/crewAI/issues/5762 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6b9a787eb544f098525817b61476c11 | https://github.com/crewAIInc/crewAI/issues/5728 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：[FEATURE] Tool to add input_files\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Tool to add input_files\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca4885df9ee49459ce8502e94d11f50 | https://github.com/crewAIInc/crewAI/issues/5758 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：crewAIInc/crewAI\n\n摘要：发现 23 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine。\n\n## 1. 安装坑 · 来源证据：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Implement Process.consensual with a pluggable ConsensusEngine\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c38215ebb04a4fbc6e7c6d2fdb2469 | https://github.com/crewAIInc/crewAI/issues/5708 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 运行坑 · 来源证据：[BUG] Wrong code in document\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[BUG] Wrong code in document\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_390380af45524e959d558b160597b38b | https://github.com/crewAIInc/crewAI/issues/5378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：[FEATURE] Enhance the document about @persisit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Enhance the document about @persisit\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_effef000d4cf47a892f17850aa033610 | https://github.com/crewAIInc/crewAI/issues/5372 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] GuardrailProvider interface for pre-tool-call authorization\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_858a1a8bead2456289d686ec0d2d802c | https://github.com/crewAIInc/crewAI/issues/4877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `crewai` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:710601088 | https://github.com/crewAIInc/crewAI | repo=crewai; install=skills\n\n## 6. 安装坑 · 来源证据：1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcfa2a852812414a82683392c2888795 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：1.14.4a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.4a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0de86b993ffa4d9298726daa189abf49 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：1.14.5a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.14.5a4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6db6cd94b6ef4bffa23da215458565b4 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Scans the client database to extract existing policy details.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Scans the client database to extract existing policy details.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8201c73155314e67801bd0b81ea9820d | https://github.com/crewAIInc/crewAI/issues/5760 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:710601088 | https://github.com/crewAIInc/crewAI | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：1.14.5a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：1.14.5a1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4094bb55c234f1581b9879efd4994c6 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:710601088 | https://github.com/crewAIInc/crewAI | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff4d292bd8984a039527502ef51aed98 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：1.14.5a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e5616e4bf1f47f59e10e83c1849c86a | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：1.14.5a3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：1.14.5a3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba25d089d674407d83a29ec4caff6284 | https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Question: integration path for Agent Threat Rules detection in crewai/security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Question: integration path for Agent Threat Rules detection in crewai/security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_05e39d8c109f4ed0a2974d448468229f | https://github.com/crewAIInc/crewAI/issues/5763 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard – protect CrewAI agents from memory poisoning\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_028fe9ebbcc943f5a7134e08d0ed9450 | https://github.com/crewAIInc/crewAI/issues/5762 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Request to enable Private Vulnerability Reporting / coordinate channel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6b9a787eb544f098525817b61476c11 | https://github.com/crewAIInc/crewAI/issues/5728 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：[FEATURE] Tool to add input_files\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Tool to add input_files\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca4885df9ee49459ce8502e94d11f50 | https://github.com/crewAIInc/crewAI/issues/5758 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:710601088 | https://github.com/crewAIInc/crewAI | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# crewAI - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 crewAI 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：crewAI 简介与快速入门。围绕“crewAI 简介与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构与模块设计。围绕“系统架构与模块设计”模拟一次用户任务，不展示安装或运行结果。\n3. agents：Agent 智能体系统。围绕“Agent 智能体系统”模拟一次用户任务，不展示安装或运行结果。\n4. crews：Crew 智能体团队。围绕“Crew 智能体团队”模拟一次用户任务，不展示安装或运行结果。\n5. flows：Flow 事件驱动工作流。围绕“Flow 事件驱动工作流”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“crewAI 简介与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构与模块设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. agents\n输入：用户提供的“Agent 智能体系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. crews\n输入：用户提供的“Crew 智能体团队”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. flows\n输入：用户提供的“Flow 事件驱动工作流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“crewAI 简介与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构与模块设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / agents：Step 3 必须围绕“Agent 智能体系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / crews：Step 4 必须围绕“Crew 智能体团队”形成一个小中间产物，并等待用户确认。\n- Step 5 / flows：Step 5 必须围绕“Flow 事件驱动工作流”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/crewAIInc/crewAI\n- https://github.com/crewAIInc/crewAI#readme\n- lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md\n- lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md\n- lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md\n- README.md\n- lib/crewai/README.md\n- lib/cli/src/crewai_cli/create_crew.py\n- lib/cli/src/crewai_cli/create_flow.py\n- lib/crewai/pyproject.toml\n- lib/crewai/src/crewai/__init__.py\n- lib/crewai/src/crewai/crew.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 crewAI 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：crewAIInc/crewAI\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx skills\n```\n\n来源：https://github.com/crewAIInc/crewAI#readme\n\n## 来源\n\n- repo: https://github.com/crewAIInc/crewAI\n- docs: https://github.com/crewAIInc/crewAI#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_a860c3e6178142e3b92fd4a77029872b"
}