【零基础部署】Docker 部署 CrewAI 多 Agent 编排框架保姆级教程

CrewAI 是一个热门的多 Agent 编排框架，它让多个 AI Agent 像一个团队一样协作完成复杂任务。每个 Agent 有自己的角色、目标和工具，通过任务分配和协作来完成工作。本教程将手把手教你用 Docker 部署 CrewAI，并运行一个多 Agent 协作的示例。

1. CrewAI 简介

1.1 什么是 CrewAI？

CrewAI 是一个 Python 框架，核心理念是：

Agent：AI 角色，有特定的专业领域和工具
Task：具体任务，分配给某个 Agent 执行
Crew：一组 Agent 和 Task 的组合，负责协调执行
Process：执行策略，支持顺序执行和层级管理

1.2 架构概览

复制代码

┌─────────────────────────────────────────┐
│                  Crew                    │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │ Agent A  │  │ Agent B  │  │ Agent C  │ │
│  │ 研究员    │  │ 写作者    │  │ 编辑者    │ │
│  └────┬────┘  └────┬────┘  └────┬────┘ │
│       │            │            │       │
│  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐ │
│  │ Task 1   │  │ Task 2   │  │ Task 3   │ │
│  │ 搜索资料  │  │ 撰写文章  │  │ 审核修改  │ │
│  └─────────┘  └─────────┘  └─────────┘ │
└─────────────────────────────────────────┘

1.3 环境要求

操作系统：Ubuntu 20.04+ / Debian 11+
Docker：20.10+
Docker Compose：V2
内存：至少 2GB
磁盘：至少 5GB 可用空间
LLM API Key：OpenAI、Anthropic 或其他兼容 API

2. 项目结构

在开始之前，先创建项目目录：

bash 复制代码

mkdir -p ~/crewai-project
cd ~/crewai-project

创建以下目录结构：

复制代码

crewai-project/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── .env
└── app/
    ├── main.py
    ├── agents.py
    ├── tasks.py
    └── tools/
        └── search_tool.py

3. 编写 Dockerfile

dockerfile 复制代码

FROM python:3.11-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY app/ ./app/

# 设置环境变量
ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

CMD ["python", "app/main.py"]

4. 编写 requirements.txt

txt 复制代码

crewai[tools]==0.108.0
crewai-tools==0.38.1
langchain-openai==0.3.8
python-dotenv==1.1.0
requests==2.32.3

5. 配置环境变量

创建 .env 文件，填入你的 LLM API Key：

bash 复制代码

# 使用 OpenAI
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL_NAME=gpt-4o-mini

# 或者使用兼容的 API（如 DeepSeek、Qwen）
# OPENAI_API_KEY=your-api-key
# OPENAI_API_BASE=https://api.deepseek.com/v1
# OPENAI_MODEL_NAME=deepseek-chat

注意：请将 sk-xxxxxxxxxxxxxxxxxxxxxxxx 替换为你的真实 API Key。不要将 .env 文件提交到版本控制系统。

6. 编写 Agent 定义

创建 app/agents.py：

python 复制代码

from crewai import Agent


def create_researcher(llm):
    """创建研究员 Agent"""
    return Agent(
        role="资深研究员",
        goal="深入搜索和分析指定主题的最新信息",
        backstory="""你是一位经验丰富的研究员，擅长从多个信息源
        获取和整合信息。你能够快速识别关键数据和趋势，
        并以清晰的方式呈现研究结果。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )


def create_writer(llm):
    """创建写作者 Agent"""
    return Agent(
        role="技术写作者",
        goal="将复杂的技术概念转化为通俗易懂的文章",
        backstory="""你是一位优秀的技术写作者，擅长将复杂的
        技术概念用简单易懂的语言解释。你的文章结构清晰、
        逻辑严密，深受读者喜爱。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )


def create_editor(llm):
    """创建编辑者 Agent"""
    return Agent(
        role="资深编辑",
        goal="确保文章质量，修正错误，优化表达",
        backstory="""你是一位资深编辑，拥有敏锐的文字感知力。
        你能够发现文章中的逻辑漏洞、事实错误和表达不当之处，
        并提出具体的修改建议。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )

7. 编写 Task 定义

创建 app/tasks.py：

python 复制代码

from crewai import Task


def create_research_task(agent, topic):
    """创建研究任务"""
    return Task(
        description=f"""对主题 "{topic}" 进行深入研究：
        1. 搜索该主题的最新发展和趋势
        2. 整理关键概念和技术要点
        3. 收集实际应用案例
        4. 总结核心观点和结论
        
        研究主题：{topic}""",
        expected_output="""一份详细的研究报告，包含：
        - 主题概述
        - 核心概念和技术要点
        - 最新发展趋势
        - 实际应用案例
        - 总结与展望""",
        agent=agent,
    )


def create_writing_task(agent, context_tasks):
    """创建写作任务"""
    return Task(
        description="""基于研究报告，撰写一篇技术文章：
        1. 文章结构要清晰，使用标题和子标题
        2. 语言通俗易懂，适合初学者阅读
        3. 包含实际的代码示例或操作步骤
        4. 文章长度 1500-2000 字""",
        expected_output="""一篇高质量的技术文章，格式为 Markdown，
        包含完整的标题、正文和代码示例。""",
        agent=agent,
        context=context_tasks,
    )


def create_editing_task(agent, context_tasks):
    """创建编辑任务"""
    return Task(
        description="""审核和修改文章：
        1. 检查事实准确性
        2. 修正语法和表达错误
        3. 优化文章结构和逻辑
        4. 确保技术术语使用正确""",
        expected_output="""最终修改后的文章，包含编辑批注
        和修改说明。""",
        agent=agent,
        context=context_tasks,
    )

8. 编写主程序

创建 app/main.py：

python 复制代码

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from crewai import Crew, Process

from agents import create_researcher, create_writer, create_editor
from tasks import create_research_task, create_writing_task, create_editing_task

# 加载环境变量
load_dotenv()


def main():
    # 初始化 LLM
    llm = ChatOpenAI(
        model=os.getenv("OPENAI_MODEL_NAME", "gpt-4o-mini"),
        openai_api_key=os.getenv("OPENAI_API_KEY"),
        openai_api_base=os.getenv("OPENAI_API_BASE"),
        temperature=0.7,
    )

    # 定义研究主题
    topic = "2026 年 AI Agent 技术的发展趋势与应用前景"

    # 创建 Agents
    researcher = create_researcher(llm)
    writer = create_writer(llm)
    editor = create_editor(llm)

    # 创建 Tasks
    research_task = create_research_task(researcher, topic)
    writing_task = create_writing_task(writer, [research_task])
    editing_task = create_editing_task(editor, [writing_task])

    # 创建 Crew 并执行
    crew = Crew(
        agents=[researcher, writer, editor],
        tasks=[research_task, writing_task, editing_task],
        process=Process.sequential,  # 顺序执行
        verbose=True,
    )

    print("=" * 50)
    print("CrewAI 多 Agent 协作开始")
    print(f"研究主题：{topic}")
    print("=" * 50)

    # 启动执行
    result = crew.kickoff()

    print("\n" + "=" * 50)
    print("最终结果：")
    print("=" * 50)
    print(result)


if __name__ == "__main__":
    main()

9. 编写 Docker Compose

创建 docker-compose.yml：

yaml 复制代码

services:
  crewai:
    build: .
    container_name: crewai-app
    env_file:
      - .env
    volumes:
      - ./app:/app/app
      - ./output:/app/output
    environment:
      - PYTHONPATH=/app
      - PYTHONUNBUFFERED=1
    restart: unless-stopped
    networks:
      - crewai-net

networks:
  crewai-net:
    driver: bridge

10. 启动服务

10.1 构建并启动

bash 复制代码

cd ~/crewai-project

# 构建镜像
docker compose build

# 启动服务
docker compose up

10.2 查看日志

bash 复制代码

# 实时查看日志
docker compose logs -f

你会看到类似这样的输出：

复制代码

crewai-app  | ==================================================
crewai-app  | CrewAI 多 Agent 协作开始
crewai-app  | 研究主题：2026 年 AI Agent 技术的发展趋势与应用前景
crewai-app  | ==================================================
crewai-app  | 
crewai-app  | [资深研究员] 开始执行任务...
crewai-app  | 搜索 AI Agent 最新技术发展...
crewai-app  | 整理核心概念和技术要点...
crewai-app  | 
crewai-app  | [技术写作者] 开始执行任务...
crewai-app  | 基于研究结果撰写文章...
crewai-app  | 
crewai-app  | [资深编辑] 开始执行任务...
crewai-app  | 审核文章质量...

10.3 后台运行

bash 复制代码

# 后台运行
docker compose up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

11. 进阶配置

11.1 使用本地 Ollama 模型

如果你想使用本地模型而不是云端 API，可以配合 Ollama：

修改 .env：

bash 复制代码

OPENAI_API_KEY=ollama
OPENAI_API_BASE=http://host.docker.internal:11434/v1
OPENAI_MODEL_NAME=qwen2.5:14b

修改 docker-compose.yml，添加网络配置：

yaml 复制代码

services:
  crewai:
    build: .
    container_name: crewai-app
    env_file:
      - .env
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./app:/app/app
    restart: unless-stopped

11.2 添加自定义工具

创建 app/tools/search_tool.py：

python 复制代码

from crewai.tools import BaseTool
from typing import Type
from pydantic import BaseModel, Field
import requests


class SearchInput(BaseModel):
    query: str = Field(description="搜索关键词")


class WebSearchTool(BaseTool):
    name: str = "web_search"
    description: str = "搜索互联网获取最新信息"
    args_schema: Type[BaseModel] = SearchInput

    def _run(self, query: str) -> str:
        # 这里可以接入真实的搜索 API
        # 例如 Tavily、SerpAPI 等
        try:
            response = requests.get(
                "https://api.search.example.com/search",
                params={"q": query, "limit": 5},
                timeout=10,
            )
            return response.text
        except Exception as e:
            return f"搜索失败：{str(e)}"

在 Agent 中使用工具：

python 复制代码

from tools.search_tool import WebSearchTool

researcher = Agent(
    role="资深研究员",
    goal="搜索最新信息",
    tools=[WebSearchTool()],
    # ...
)

11.3 使用层级管理

python 复制代码

crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,      # 层级管理
    manager_llm=llm,                   # 管理者使用的模型
    verbose=True,
)

12. 常见问题排查

12.1 API Key 错误

复制代码

错误：AuthenticationError: Incorrect API key

解决方法：

检查 .env 中的 OPENAI_API_KEY 是否正确
确认 API Key 没有过期
如果使用第三方 API，确认 OPENAI_API_BASE 配置正确

12.2 模型不可用

复制代码

错误：Model not found

解决方法：

检查 OPENAI_MODEL_NAME 是否拼写正确
确认你的账户有权限使用该模型
尝试使用更常见的模型名称

12.3 网络连接问题

复制代码

错误：ConnectionError

解决方法：

检查服务器是否能访问外部 API
如果使用代理，在 .env 中配置 HTTPS_PROXY
如果使用本地 Ollama，确认 Ollama 服务已启动

12.4 依赖安装失败

bash 复制代码

# 重新构建镜像
docker compose build --no-cache

13. 总结

通过本教程，你已经成功部署了 CrewAI 多 Agent 编排框架：

使用 Docker 容器化部署，环境隔离、一键启动
创建了三个协作 Agent：研究员、写作者、编辑者
配置了顺序执行的任务流水线
学会了使用云端 API 和本地 Ollama 模型
掌握了自定义工具和层级管理的进阶用法

CrewAI 的核心价值在于让 AI Agent 之间实现真正的协作，而不是简单的链式调用。通过合理的角色设计和任务分配，你可以构建出强大的 AI 工作流。