agentcrew/
├── menu.md                          # ⭐ 导航中枢（从这里开始）
├── README.md                        # 文档概述
├── docs/
│   ├── getting-started/             # 入门指南
│   │   ├── 01-introduction.md       # 框架简介、Flow/Crew 架构
│   │   └── 02-installation.md       # 安装步骤、项目脚手架
│   ├── core-concepts/               # 核心概念
│   │   ├── 01-agents.md             # Agent 属性、创建方式、工具集成
│   │   ├── 02-tasks.md              # Task 配置、输出格式、Guardrails
│   │   ├── 03-flows.md              # Flow 装饰器、状态管理、路由
│   │   ├── 04-crews.md              # Crew 编排、执行流程、重放
│   │   ├── 05-knowledge.md          # RAG 知识库、向量存储
│   │   ├── 06-memory.md             # 短期/长期/实体记忆
│   │   ├── 07-reasoning.md          # Agent 推理与任务反思
│   │   └── 08-planning.md           # Crew 级任务规划
│   ├── design-guides/               # 设计指南
│   │   ├── 01-evaluating-use-cases.md   # 复杂度-精度矩阵
│   │   ├── 02-first-crew.md             # 第一个 Crew 完整流程
│   │   ├── 03-first-flow.md             # 第一个 Flow 完整流程
│   │   └── 04-customizing-prompts.md    # 提示词自定义
│   ├── tools/                       # 工具集
│   │   ├── 01-file-document.md      # 文件读写、PDF/JSON/CSV
│   │   ├── 02-web-scraping.md       # 网页抓取
│   │   ├── 03-search-research.md    # 搜索与研究
│   │   └── 04-integrations.md       # 外部集成
│   └── observability/               # 可观测性
│       └── tracing.md               # 追踪与监控

# 1. 安装 uv 包管理器
# macOS / Linux
curl -LsSf https://astral.org.cn/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c \"irm https://astral.org.cn/uv/install.ps1 | iex\"

# 2. 安装 CrewAI CLI
uv tool install crewai

# 3. 验证
uv tool list
# 输出：crewai v0.102.0

# 创建 Crew 项目
crewai create crew my_agent_project
cd my_agent_project

# 创建 Flow 项目（如需事件驱动编排）
crewai create flow my_flow_project
cd my_flow_project

crewai install

# 如需额外包
uv add <package-name>

researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering the latest
    developments in {topic}. Known for your ability to find the most relevant
    information and present it in a clear and concise manner.

reporting_analyst:
  role: >
    {topic} Reporting Analyst
  goal: >
    Create detailed reports based on {topic} data analysis and research findings
  backstory: >
    You're a meticulous analyst with a keen eye for detail. You're known for
    your ability to turn complex data into clear and concise reports.

from crewai import Agent
from crewai_tools import SerperDevTool

# 基础研究 Agent
research_agent = Agent(
    role=\"Research Analyst\",
    goal=\"Find and summarize information about specific topics\",
    backstory=\"You are an experienced researcher with attention to detail\",
    tools=[SerperDevTool()],
    verbose=True
)

# 代码开发 Agent
dev_agent = Agent(
    role=\"Senior Python Developer\",
    goal=\"Write and debug Python code\",
    backstory=\"Expert Python developer with 10 years of experience\",
    allow_code_execution=True,
    code_execution_mode=\"safe\",   # Docker 隔离执行
    max_execution_time=300,
    max_retry_limit=3
)

# 推理型 Agent
reasoning_agent = Agent(
    role=\"Strategic Planner\",
    goal=\"Analyze complex problems and create detailed execution plans\",
    backstory=\"Expert strategic planner who methodically breaks down complex challenges\",
    reasoning=True,               # 启用推理
    max_reasoning_attempts=3,
    verbose=True
)

research_task:
  description: >
    Conduct a thorough research about {topic}
    Make sure you find any interesting and relevant information given
    the current year is 2025.
  expected_output: >
    A list with 10 bullet points of the most relevant information about {topic}
  agent: researcher

reporting_task:
  description: >
    Review the context you got and expand each topic into a full section for a report.
    Make sure the report is detailed and contains any and all relevant information.
  expected_output: >
    A fully fledge reports with the mains topics, each with a full section of information.
    Formatted as markdown without '```'
  agent: reporting_analyst
  markdown: true
  output_file: report.md

from typing import Tuple, Any
from crewai import Task, TaskOutput

# 基于函数的验证
def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]:
    word_count = len(result.raw.split())
    if word_count > 200:
        return (False, \"Blog content exceeds 200 words\")
    return (True, result.raw.strip())

blog_task = Task(
    description=\"Write a blog post about AI\",
    expected_output=\"A blog post under 200 words\",
    agent=blog_agent,
    guardrail=validate_blog_content,
    guardrail_max_retries=3
)

from pydantic import BaseModel

class Blog(BaseModel):
    title: str
    content: str

task = Task(
    description=\"Create a blog title and content on a given topic.\",
    expected_output=\"A compelling blog title and well-written content.\",
    agent=blog_agent,
    output_pydantic=Blog,   # 自动解析为 Pydantic 对象
)

result = crew.kickoff()
print(result.pydantic.title)    # 直接访问结构化字段
print(result.pydantic.content)

from crewai import Agent, Crew, Task, Process
from crewai.project import CrewBase, agent, task, crew

@CrewBase
class MyCrewProject:
    \"\"\"我的自定义 Crew 项目\"\"\"

    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            verbose=True,
            tools=[SerperDevTool()]
        )

    @agent
    def reporting_analyst(self) -> Agent:
        return Agent(
            config=self.agents_config['reporting_analyst'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def reporting_task(self) -> Task:
        return Task(
            config=self.tasks_config['reporting_task'],
            output_file='output/report.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,   # 顺序执行
            memory=True,                   # 启用记忆
            planning=True,                 # 启用规划
            verbose=True,
        )

from crewai.flow.flow import Flow, listen, start, router
from pydantic import BaseModel

class MyState(BaseModel):
    \"\"\"Flow 状态定义\"\"\"
    input_data: str = \"\"
    result: str = \"\"

class MyFlow(Flow[MyState]):

    @start()
    def step_one(self):
        \"\"\"入口步骤\"\"\"
        print(f\"开始处理: {self.state.input_data}\")
        return self.state.input_data

    @listen(step_one)
    def step_two(self, data: str):
        \"\"\"监听 step_one 的输出\"\"\"
        processed = f\"处理完成: {data}\"
        self.state.result = processed
        return processed

    @router(step_two)
    def decide_next(self):
        \"\"\"条件路由\"\"\"
        if \"error\" in self.state.result:
            return \"failure_route\"
        return \"success_route\"

    @listen(\"success_route\")
    def handle_success(self):
        print(\"✅ 成功\")

    @listen(\"failure_route\")
    def handle_failure(self):
        print(\"❌ 失败\")

flow = MyFlow()
result = flow.kickoff(inputs={\"input_data\": \"Hello Vibe Coding\"})

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,   # 一行启用：短期 + 长期 + 实体记忆
    embedder={
        \"provider\": \"openai\",
        \"config\": {\"model_name\": \"text-embedding-3-small\"}
    }
)

from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource

# 字符串知识源
content = \"Users name is John. He is 30 years old and lives in San Francisco.\"
string_source = StringKnowledgeSource(content=content)

# 文件知识源
file_source = TextFileKnowledgeSource(
    file_path=\"docs/coding-standards.md\"
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    knowledge_sources=[string_source, file_source],
)

from crewai_tools import (
    FileReadTool,        # 文件读取 → tools/01-file-document.md
    PDFSearchTool,       # PDF 搜索 → tools/01-file-document.md
    JSONSearchTool,      # JSON 搜索 → tools/01-file-document.md
    SerperDevTool,       # 网页搜索 → tools/03-search-research.md
    ScrapeWebsiteTool,   # 网页抓取 → tools/02-web-scraping.md
    GithubSearchTool,    # GitHub 搜索 → tools/03-search-research.md
)

agent = Agent(
    role=\"Document Analyst\",
    tools=[FileReadTool(), PDFSearchTool(), SerperDevTool()],
    goal=\"Process and analyze various document types\"
)

# 1. 先查看任务输出日志
crewai log-tasks-outputs

# 2. 从失败任务重放
crewai replay -t <task_id>

# 3. 如果需要全新开始
crewai reset-memories

# 4. 交互式排查
crewai chat

crew = Crew(
    agents=[...],
    tasks=[...],
    tracing=True,   # 启用内置追踪 → CrewAI AMP 平台
    verbose=True
)

# 安装依赖
crewai install

# 本地运行
crewai run

# 运行测试
crewai test

git add src/ .env
git commit -m \"feat: 完成自定义 Crew Agent 开发\"
git push origin main

# 打版本标签
git tag -a v1.0.0 -m \"First release\"
git push origin --tags

crewai login
crewai deploy

# 团队成员
git pull origin main
crewai install
# 编辑 .env 填入 API 密钥
crewai run

安全五层防护：
┌──────────────────────────────┐
│ 1. Guardrails 输出验证        │  ← 02-tasks.md
│ 2. 代码安全执行 (Docker)      │  ← 01-agents.md
│ 3. MCP 工具过滤              │  ← mcp/mcp.md
│ 4. 工具白名单最小化            │  ← 配置层
│ 5. 审计日志 (tracing)        │  ← observability/
└──────────────────────────────┘

# 多层验证链
task = Task(
    description=\"Write a blog post about AI\",
    expected_output=\"A well-formatted blog post between 100-500 words\",
    agent=blog_agent,
    guardrails=[
        validate_word_count,     # 字数验证
        validate_no_profanity,   # 内容过滤
        format_output            # 格式检查
    ],
    guardrail_max_retries=3
)

agent = Agent(
    role=\"Developer\",
    allow_code_execution=True,
    code_execution_mode=\"safe\",   # Docker 隔离 → 生产环境必须
    max_execution_time=300,       # 5 分钟超时
)

agent = Agent(
    role=\"Research Analyst\",
    mcps=[\"https://mcp.exa.ai/mcp?api_key=your_key\"],
    # MCP 支持：Stdio(本地) / SSE(远程流) / HTTP(远程灵活)
)

crewai create crew tech_research
cd tech_research

researcher:
  role: >
    {topic} 技术调研专家
  goal: >
    深入调研 {topic} 的最新技术动态，找到最有价值的信息
  backstory: >
    你是一位资深技术调研专家，擅长从海量信息中提取关键洞察。
    你的调研报告总是全面、准确、有深度。
  verbose: true

analyst:
  role: >
    {topic} 技术分析顾问
  goal: >
    基于调研结果，输出结构化的分析报告，包含趋势判断和行动建议
  backstory: >
    你是一位顶级技术顾问，曾为多家 Fortune 500 企业提供技术战略咨询。
    你的分析总是直击要害，让决策者一目了然。
  verbose: true

research_task:
  description: >
    对 {topic} 进行全面调研，重点关注：
    1. 核心技术概念与原理
    2. 最新发展趋势（2025）
    3. 主要应用场景与案例
    4. 头部企业与开源项目
    5. 未来展望
  expected_output: >
    一份结构化的调研笔记，包含以上 5 个维度的详细信息
  agent: researcher

analysis_task:
  description: >
    基于调研结果，撰写一份专业分析报告，包含：
    1. 执行摘要
    2. 技术成熟度评估
    3. 竞争格局分析
    4. 机会与风险
    5. 行动建议
  expected_output: >
    一份格式精美的 Markdown 分析报告
  agent: analyst
  context:
    - research_task
  markdown: true
  output_file: output/report.md

from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool

@CrewBase
class TechResearchCrew:
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            tools=[SerperDevTool()]   # 来自 tools/03-search-research.md
        )

    @agent
    def analyst(self) -> Agent:
        return Agent(
            config=self.agents_config['analyst']
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def analysis_task(self) -> Task:
        return Task(
            config=self.tasks_config['analysis_task'],
            output_file='output/report.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True
        )

crewai install
crewai run

Agent(
    max_execution_time=300,   # 5 分钟超时
    max_iter=15,              # 最多 15 次迭代
)

VibeCoding 六阶段流水线（8 Skills 全覆盖）：
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│Brainstorm│ →  │   Plan   │ →  │ CodeGen  │ →  │  Review  │ →  │  Commit  │ →  │  Debug   │
│  需求分析  │    │  架构设计  │    │  代码生成  │    │  代码审查  │    │  规范提交  │    │  诊断修复  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                                                     ↑
                                                              ┌──────────────────────┤
                                                              │   Observability      │  Deploy  │
                                                              │   可观测性集成        │  发布部署  │
                                                              └──────────────────────┴──────────┘