SkillsCoding:CrewAI企业级Agent开发实操&成品分享

admin 2026-06-04 04:12:23 网络安全文章 来源:ZONE.CI 全球网 0 阅读模式

文章总结: 该文档详细介绍了CrewAI企业级Agent开发框架的实操方法,包含手动配置与VibeCoding自动生成两种开发模式。核心内容涵盖环境部署、Agent创建、Task配置、Flow设计等完整开发流程,并提供了SecurityAuditFlow安全审计实例。文档强调以menu.md为导航中枢的项目目录结构,并附带了YAML配置示例、属性速查表等实用资源,为开发者提供从入门到实战的全面指导。 综合评分: 78 文章分类: 安全开发,安全工具,安全运营,解决方案,技术标准


cover_image

SkillsCoding:CrewAI 企业级 Agent 开发实操&成品分享

原创

Lior1969 Lior1969

Moonlight安全

2026年6月2日 21:06 北京

在小说阅读器读本章

去阅读

#

前半部分:以 menu.md 为导航中枢的传统操作手册 | 后半部分:VibeCoding + 8 个 CrewSkills 自动生成,附 Security Audit Flow 完整实例


一、概念说明

1.1 你的”Agent 开发地图”:menu.md

在开始编码之前,先打开 agentcrew/menu.md——这是整个 CrewAI 生态的导航地图。它按功能模块组织了所有文档的入口,你只需三步即可完成开发:

menu.md(找功能)→ 对应文档(看实例)→ 复制代码(改参数)→

你的 Agent 就绪

1.2 项目目录结构

本手册基于以下目录结构,所有路径均可直接使用

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.3 两种开发模式:手动 vs 自动

在实际开发中,你通常会经历两个阶段:

① 学习阶段(第一~九章)——按 menu.md 的导航手动配置 Agent/Task/Crew,深入理解每个参数的作用。适合刚接触 CrewAI 的开发者。

② 加速阶段(第十~十一章)——当理解了核心概念后,切换到 VibeCoding + 8 个 CrewSkills 模式,用自然语言描述需求,AI 自动生成完整项目代码。适合需要快速交付的团队。

💡 建议:先手动理解核心概念(30分钟),再切换到 VibeCoding 模式提效。两种方式不冲突,推荐先手动理解再自动加速。

二、环境部署

2.1 安装 CrewAI

📍 对应文件:docs/getting-started/02-installation.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

2.2 生成项目脚手架

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

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

2.3 安装依赖

crewai install

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

三、Agent 创建

3.1 快速创建第一个 Agent

📍 对应文件:docs/core-concepts/01-agents.md 📍 menu.md 定位路径:核心概念 → 01-agents.md → “创建代理” 章节

操作步骤:打开 menu.md → 找到”核心概念”表格 → 点击 01-agents.md → 翻到”创建代理” → 复制代码。

YAML 配置方式(推荐)

文件:src/my_project/config/agents.yaml

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

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

Python 代码定义方式

文件:src/my_project/crew.py

from crewai import Agent
from crewai_tools import SerperDevTool

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

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

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

3.2 Agent 属性速查表

📍 来源:docs/core-concepts/01-agents.md 中的属性表

| 属性 | 类型 | 说明 | | — | — | — | | role | str | Agent 角色定义 | | goal | str | 指导决策的个体目标 | | backstory | str | 背景故事,丰富交互 | | llm | str/LLM | 语言模型,默认 “gpt-4” | | tools | List[BaseTool] | 可用工具列表 | | verbose | bool | 详细日志,默认 False | | allow_delegation | bool | 允许委托任务,默认 False | | reasoning | bool | 启用任务前推理,默认 False | | max_iter | int | 最大迭代次数,默认 20 | | max_execution_time | int | 最大执行时间(秒) | | allow_code_execution | bool | 允许代码执行,默认 False | | memory | bool | 启用记忆,默认 False | | cache | bool | 缓存工具调用,默认 True |

四、配置编辑

4.1 创建 Task(任务定义)

📍 对应文件:docs/core-concepts/02-tasks.md 📍 menu.md 定位路径:核心概念 → 02-tasks.md → “创建任务” 章节

文件:src/my_project/config/tasks.yaml

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

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

Task 高级特性:Guardrails 输出验证

📍 来源:docs/core-concepts/02-tasks.md → “任务防护措施” 章节

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

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

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

Task 高级特性:结构化输出

from pydantic import BaseModel

class Blog(BaseModel):
&nbsp; &nbsp; title: str
&nbsp; &nbsp; content: str

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

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

4.2 创建 Crew(团队编排)

📍 对应文件:docs/core-concepts/04-crews.md 📍 menu.md 定位路径:核心概念 → 04-crews.md → “创建团队” 章节

文件:src/my_project/crew.py

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

@CrewBase
class MyCrewProject:
&nbsp; &nbsp; """我的自定义 Crew 项目"""

&nbsp; &nbsp; agents_config = 'config/agents.yaml'
&nbsp; &nbsp; tasks_config = 'config/tasks.yaml'

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

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

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

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

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

4.3 创建 Flow(事件驱动编排)

📍 对应文件:docs/core-concepts/03-flows.md 📍 menu.md 定位路径:核心概念 → 03-flows.md → “开始入门” 章节

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

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

class MyFlow(Flow[MyState]):

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

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

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

&nbsp; &nbsp; @listen("success_route")
&nbsp; &nbsp; def handle_success(self):
&nbsp; &nbsp; &nbsp; &nbsp; print("✅ 成功")

&nbsp; &nbsp; @listen("failure_route")
&nbsp; &nbsp; def handle_failure(self):
&nbsp; &nbsp; &nbsp; &nbsp; print("❌ 失败")

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

4.4 启用记忆系统

📍 对应文件:docs/core-concepts/06-memory.md 📍 menu.md 定位路径:核心概念 → 06-memory.md → “基本记忆系统”

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

4.5 注入知识库(RAG)

📍 对应文件:docs/core-concepts/05-knowledge.md 📍 menu.md 定位路径:核心概念 → 05-knowledge.md → “基本字符串知识示例”

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(
&nbsp; &nbsp; file_path="docs/coding-standards.md"
)

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

4.6 为 Agent 配备工具

📍 对应文件:docs/tools/01-file-document.md02-web-scraping.md03-search-research.md 📍 menu.md 定位路径:工具 → 按需选择 → 复制代码

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

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

五、调试

5.1 CLI 命令速查

📍 来源:agentcrew/menu.md → “CLI命令” 章节

| 命令 | 用途 | | — | — | | crewai run | 运行 Crew 或 Flow | | crewai test | 测试 Crew 并评估性能 | | crewai replay -t <task_id> | 从指定任务重放执行 | | crewai log-tasks-outputs | 查看最新任务输出 | | crewai reset-memories | 重置记忆 | | crewai chat | 交互式会话调试 | | crewai train | 训练 Crew 指定迭代次数 |

5.2 调试流程

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

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

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

# 4. 交互式排查
crewai chat

5.3 启用可观测性

📍 对应文件:docs/observability/tracing.md 📍 menu.md 定位路径:可观测性 → tracing.md

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

六、发布

6.1 本地运行与测试

# 安装依赖
crewai install

# 本地运行
crewai run

# 运行测试
crewai test

6.2 Git 版本管理

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

6.3 部署到 CrewAI AMP 平台

crewai login
crewai deploy

6.4 团队协作

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

七、企业级安全管控

7.1 安全防护体系

📍 来源:docs/core-concepts/02-tasks.md → “任务防护措施” + docs/core-concepts/01-agents.md → “安全与代码执行”

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

7.2 Guardrails 安全验证

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

7.3 代码安全执行

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

7.4 MCP 工具安全

📍 对应文件:docs/mcp/mcp.md 📍 menu.md 定位路径:MCP集成 → mcp.md

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

八、最佳实践

8.1 开发工作流总览

使用 menu.md 的标准开发流程:

1打开 menu.md,找到你要的功能模块

2点击链接跳转到对应 .md 文档

3在文档中找到代码示例,直接复制

4修改 role/goal/backstory 适配你的业务

5crewai run → 验证 → 迭代

8.2 场景速查:从需求到文档的映射

| 你的需求 | menu.md 定位路径 | 关键文件 | | — | — | — | | 我想创建一个会搜索的研究 Agent | 核心概念 → 01-agents.md | 01-agents.md → “基本研究代理” | | 我想让 Agent 记住上次的结果 | 核心概念 → 06-memory.md | 06-memory.md → memory=True | | 我想给 Agent 注入公司文档 | 核心概念 → 05-knowledge.md | 05-knowledge.md → StringKnowledgeSource | | 我想让 Agent 输出结构化 JSON | 核心概念 → 02-tasks.md | 02-tasks.md → output_pydantic | | 我想控制任务执行顺序 | 核心概念 → 04-crews.md | 04-crews.md → Process.sequential | | 我想让 Agent 写代码并执行 | 核心概念 → 01-agents.md | 01-agents.md → “代码开发代理” | | 我想在工作流中加条件分支 | 核心概念 → 03-flows.md | 03-flows.md → @router() | | 我想自定义 Agent 的提示词 | 设计指南 → 04-customizing-prompts.md | 04-customizing-prompts.md | | 我想让 Agent 读取 PDF 文件 | 工具 → 01-file-document.md | 01-file-document.md → PDFSearchTool | | 我想监控 Agent 的执行过程 | 可观测性 → tracing.md | tracing.md → tracing=True |

8.3 完整示例:从零创建一个”技术调研 Crew”

场景:需要一个会自动搜索、分析、输出 Markdown 报告的技术调研团队。

第 1 步:打开 menu.md,找到需要的功能:

  • Agent 创建 → core-concepts/01-agents.md
  • Task 定义 → core-concepts/02-tasks.md
  • Crew 编排 → core-concepts/04-crews.md
  • 搜索工具 → tools/03-search-research.md

第 2 步:创建项目

crewai create crew tech_research
cd tech_research

第 3 步:编辑 config/agents.yaml(从 01-agents.md 复制模板)

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

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

第 4 步:编辑 config/tasks.yaml(从 02-tasks.md 复制模板)

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

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

第 5 步:编辑 crew.py(从 04-crews.md 复制模板)

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

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

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

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

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

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

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

第 6 步:运行

crewai install
crewai run

九、FAQ

Q1:如何快速找到某个功能的实现代码?

A:打开 agentcrew/menu.md,按功能分类定位:

  • 创建 Agent

    → 核心概念表格 → 01-agents.md

  • 定义 Task

    → 核心概念表格 → 02-tasks.md

  • 编排 Crew

    → 核心概念表格 → 04-crews.md

  • 事件驱动 Flow

    → 核心概念表格 → 03-flows.md

  • 添加记忆

    → 核心概念表格 → 06-memory.md

  • 注入知识库

    → 核心概念表格 → 05-knowledge.md

  • 配备工具

    → 工具表格 → 按类型选择

  • 启用监控

    → 可观测性表格 → tracing.md

Q2:menu.md 中的文件路径怎么使用?

A:所有路径相对于 agentcrew/ 根目录。例如 menu.md 中写 [01-agents.md](docs/core-concepts/01-agents.md),实际文件在 agentcrew/docs/core-concepts/01-agents.md

Q3:我应该用 YAML 配置还是 Python 代码定义 Agent?

A:推荐 YAML。YAML 配置更清晰、更易维护、更易团队协作。Python 代码适合需要动态构建 Agent 的场景。

Q4:Crew 和 Flow 应该怎么选?

A:参考 design-guides/01-evaluating-use-cases.md 中的复杂性-精度矩阵:

  • 简单任务

    :直接用 Crew(顺序执行即可)

  • 需要条件分支/状态管理

    :用 Flow 编排 Crew

  • 复杂系统

    :Flow 编排多个 Crew

Q5:如何让 Agent 记住上次执行的结果?

A:在 Crew 中设置 memory=True,参考 core-concepts/06-memory.md。记忆数据存储在本地 SQLite 中,跨执行持久化。

Q6:Agent 执行超时怎么办?

A:设置 max_execution_time 和 max_iter

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

Q7:如何确保 Agent 输出的格式符合预期?

A:三种方式(参考 02-tasks.md):

  • output_pydantic

    :强制 Pydantic 结构化输出

  • guardrails

    :输出验证函数链

  • expected_output

    :在 Task 中详细描述期望格式

Q8:如何在现有项目中逐步引入 CrewAI?

A:从最小单元开始:

  1. 先用一个 Agent + 一个 Task 跑通流程
  2. 逐步添加更多 Agent 组成 Crew
  3. 需要复杂编排时引入 Flow
  4. 最后启用 memory 和 knowledge 增强能力

十、VibeCoding Skills 能力体系

10.1 什么是 VibeCoding Skills?

基于本手册的 agentcrew/ 文档体系,我们构建了一套可直接被 Claude Code 加载的 Superpowers 格式 Skills 工具集,覆盖从需求分析到生产部署的完整 VibeCoding 流水线。每个 Skill 都是一个独立的 JSON 配置文件,包含完整的 AI prompt、诊断流程、代码示例和最佳实践。

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

下一篇文章 展示了Crew编排的代码审计Agent->Security Audit Flow 完整实例

Skills项目地址 https://github.com/8eeth0ven/CrewAI-AgentCodingSkills


免责声明:

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景,旨在提升网络安全防护能力,具有明确的技术研究属性。

任何单位或个人未经授权,将本文内容用于攻击、破坏等非法用途的,由此引发的全部法律责任、民事赔偿及连带责任,均由行为人独立承担,本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布,若存在版权侵权或其他异议,请通过邮件联系处理,具体联系方式可点击页面上方的联系我

本文转载自:Moonlight安全 Lior1969 Lior1969《SkillsCoding:CrewAI 企业级 Agent 开发实操&成品分享》

喜欢数学的小姑娘 网络安全文章

喜欢数学的小姑娘

文章总结: 本文作者推荐数学手游Pythagorea激发女儿数学兴趣,描述女儿从应试数学转向内驱热爱的转变过程,反思早期未进行系统数学训练的遗憾,但强调保护天性
评论:0   参与:  0