部署前准备

Note

在部署到 CrewAI AMP 之前，先验证你的项目结构是否正确非常重要。Crew 和 Flow 都可以作为 “automations” 部署，但它们有不同的项目结构和要求，必须满足这些要求才能成功部署。

理解 Automations

在 CrewAI AMP 中，automations 是可部署 Agentic AI 项目的总称。一个 automation 可以是：

• Crew：一个独立的 AI 智能体团队，协同完成任务
• Flow：一个编排型工作流，可以组合多个 crews、直接 LLM 调用以及流程逻辑

明确你要部署的是哪一种非常重要，因为它们的项目结构和入口点不同。

Crews vs Flows：关键区别

Crew 项目

独立的 AI 智能体团队。新的 crews 采用 JSON-first 结构，使用 crew.jsonc 和 agents/；经典 crews 仍然可以使用 crew.py。

Flow 项目

带有嵌入式 crews 的编排型工作流，位于 crews/ 文件夹中。最适合复杂、多阶段流程。

方面	Crew	Flow
项目结构	项目根目录包含 crew.jsonc 和 agents/	src/project_name/，并包含 crews/ 文件夹
主逻辑位置	crew.jsonc（经典方式：src/project_name/crew.py）	src/project_name/main.py（Flow 类）
入口函数	从 crew.jsonc 加载（经典方式：main.py 中的 run()）	main.py 中的 kickoff()
pyproject.toml 类型	type = "crew"	type = "flow"
CLI 创建命令	crewai create crew name	crewai create flow name
配置位置	crew.jsonc、agents/、可选 tools/	src/project_name/crews/crew_name/config/ 或嵌入式 JSON crew 文件夹
是否可包含其他 crews	否	是（在 crews/ 文件夹中）

项目结构参考

Crew 项目结构

运行 crewai create crew my_crew 后，你会得到 JSON-first 结构：

my_crew/
├── .gitignore
├── pyproject.toml          # Must have type = "crew"
├── README.md
├── .env
├── uv.lock                  # REQUIRED for deployment
├── crew.jsonc               # Crew settings, tasks, process, inputs
├── agents/
│   └── researcher.jsonc     # Agent definitions
├── tools/                   # Optional custom:<name> tools
├── knowledge/
└── skills/

Warning

对于 JSON-first crews，请将 crew.jsonc、agents/、tools/、knowledge/ 和 skills/ 保持在项目根目录。把它们放在 src/ 下会导致 crewai run 和部署验证找不到 crew 定义。

Info

使用 crewai create crew my_crew --classic 创建的经典项目，会使用旧的 src/project_name/crew.py、src/project_name/config/agents.yaml 和 src/project_name/config/tasks.yaml 布局。该布局仍然支持基于装饰器的 Python crews。

Flow 项目结构

运行 crewai create flow my_flow 后，你会得到如下结构：

my_flow/
├── .gitignore
├── pyproject.toml          # Must have type = "flow"
├── README.md
├── .env
├── uv.lock                  # REQUIRED for deployment
└── src/
    └── my_flow/
        ├── __init__.py
        ├── main.py          # Entry point with kickoff() function + Flow class
        ├── crews/           # Embedded crews folder
        │   └── poem_crew/
        │       ├── __init__.py
        │       ├── poem_crew.py  # Crew with @CrewBase decorator
        │       └── config/
        │           ├── agents.yaml
        │           └── tasks.yaml
        └── tools/
            ├── __init__.py
            └── custom_tool.py

Info

JSON-first standalone crews 使用项目根目录中的 JSON 文件。Flows 仍然使用 src/project_name/，并且可以包含经典嵌入式 crews，或者使用 crewai.project.load_crew 加载的嵌入式 JSON crew 文件夹。

部署前清单

使用这个清单验证你的项目已准备好部署。

1. 验证 pyproject.toml 配置

你的 pyproject.toml 必须包含正确的 [tool.crewai] 部分：

For Crews

[tool.crewai]
type = "crew"

For Flows

[tool.crewai]
type = "flow"

Warning

如果 type 与项目结构不匹配，构建将失败，或者 automation 无法正常运行。

2. 确保 uv.lock 文件存在

CrewAI 使用 uv 进行依赖管理。uv.lock 文件可确保构建可复现，并且部署时必需。

# Generate or update the lock file
uv lock

# Verify it exists
ls -la uv.lock

如果该文件不存在，请运行 uv lock 并将其提交到仓库：

uv lock
git add uv.lock
git commit -m "Add uv.lock for deployment"
git push

3. 验证 Crew 定义

JSON-first Crews

JSON-first crews 必须在项目根目录中拥有 crew.jsonc 或 crew.json 文件。 agents 数组必须引用 agents/ 中的文件，并且每个任务都应引用有效的 agent 名称。

{
  "name": "Research Crew",
  "agents": ["researcher"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Research {topic}.",
      "expected_output": "A concise report.",
      "agent": "researcher"
    }
  ],
  "inputs": {
    "topic": "AI Agents"
  }
}

自定义工具以 "custom:<name>" 的形式引用，并且必须在 tools/<name>.py 中通过 BaseTool 子类实现。

Classic Python/YAML Crews

经典 crews 和嵌入在 Flows 中的 Python crews 必须使用 @CrewBase 装饰器。

from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List

@CrewBase
class MyCrew():
    """My crew description"""

    agents: List[BaseAgent]
    tasks: List[Task]

    @agent
    def my_agent(self) -> Agent:
        return Agent(
            config=self.agents_config['my_agent'],  # type: ignore[index]
            verbose=True
        )

    @task
    def my_task(self) -> Task:
        return Task(
            config=self.tasks_config['my_task']  # type: ignore[index]
        )

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

4. 检查项目入口点

JSON-first standalone crews 不需要手写的 src/project_name/main.py；crewai run 和部署打包会直接加载 crew.jsonc。经典 crews 和 Flows 使用 Python 入口点：

JSON-first Crews

在项目根目录从本地运行：

crewai run

Classic Crews

入口点使用 run() 函数：

src/my_crew/main.py

from my_crew.crew import MyCrew

def run():
    """Run the crew."""
    inputs = {'topic': 'AI in Healthcare'}
    result = MyCrew().crew().kickoff(inputs=inputs)
    return result

if __name__ == "__main__":
    run()

For Flows

入口点使用带 Flow 类的 kickoff() 函数：

src/my_flow/main.py

from crewai.flow import Flow, listen, start
from my_flow.crews.poem_crew.poem_crew import PoemCrew

class MyFlow(Flow):
    @start()
    def begin(self):
        # Flow logic here
        result = PoemCrew().crew().kickoff(inputs={...})
        return result

def kickoff():
    """Run the flow."""
    MyFlow().kickoff()

if __name__ == "__main__":
    kickoff()

5. 准备环境变量

在部署前，确保你已经准备好：

1. LLM API keys（OpenAI、Anthropic、Google 等）
2. 工具 API keys（如果使用外部工具，如 Serper 等）

Info

如果你的项目依赖来自私有 PyPI registry 的包，你还需要将 registry 认证凭据配置为环境变量。详细信息请参阅 Private Package Registries 指南。

Tip

在部署前先用相同的环境变量在本地测试项目，以尽早发现配置问题。

快速验证命令

在项目根目录运行这些命令，可快速验证你的设置：

# 1. Check project type in pyproject.toml
grep -A2 "\[tool.crewai\]" pyproject.toml

# 2. Verify uv.lock exists
ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'"

# 3. For JSON-first crews, verify crew.jsonc and agents/ exist
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found"
test -d agents || echo "No agents/ directory found"

# 4. For classic Crews - verify crew.py exists
ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)"

# 5. For Flows - verify crews/ folder exists
ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)"

# 6. For classic Python crews - check for CrewBase usage
grep -r "@CrewBase" . --include="*.py"

常见设置错误

错误	症状	修复
缺少 uv.lock	构建在依赖解析阶段失败	运行 uv lock 并提交
pyproject.toml 中的 type 错误	构建成功但运行时失败	改成正确的 type
JSON-first crew 中缺少 crew.jsonc 或 agents/	找不到 crew 定义	将 crew.jsonc 和 agents/ 保持在项目根目录
经典 crew 中缺少 @CrewBase 装饰器	”Config not found” 错误	为所有经典 crew 类添加装饰器
经典文件放在根目录而不是 src/	找不到入口点	将经典 Python 文件移动到 src/project_name/
缺少 run() 或 kickoff()	无法启动自动化	添加正确的入口函数

下一步

当你的项目通过所有清单项后，就可以开始部署了：

部署到 AMP

按照部署指南，使用 CLI、Web 界面或 CI/CD 集成将你的 Crew 或 Flow 部署到 CrewAI AMP。