【零基础部署】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. 项目结构

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

mkdir-p~/crewai-projectcd~/crewai-project

创建以下目录结构：

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

3. 编写 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

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：

# 使用 OpenAIOPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxOPENAI_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：

fromcrewaiimportAgentdefcreate_researcher(llm):"""创建研究员 Agent"""returnAgent(role="资深研究员",goal="深入搜索和分析指定主题的最新信息",backstory="""你是一位经验丰富的研究员，擅长从多个信息源 获取和整合信息。你能够快速识别关键数据和趋势， 并以清晰的方式呈现研究结果。""",verbose=True,allow_delegation=False,llm=llm,)defcreate_writer(llm):"""创建写作者 Agent"""returnAgent(role="技术写作者",goal="将复杂的技术概念转化为通俗易懂的文章",backstory="""你是一位优秀的技术写作者，擅长将复杂的 技术概念用简单易懂的语言解释。你的文章结构清晰、 逻辑严密，深受读者喜爱。""",verbose=True,allow_delegation=False,llm=llm,)defcreate_editor(llm):"""创建编辑者 Agent"""returnAgent(role="资深编辑",goal="确保文章质量，修正错误，优化表达",backstory="""你是一位资深编辑，拥有敏锐的文字感知力。 你能够发现文章中的逻辑漏洞、事实错误和表达不当之处， 并提出具体的修改建议。""",verbose=True,allow_delegation=False,llm=llm,)

7. 编写 Task 定义

创建app/tasks.py：

fromcrewaiimportTaskdefcreate_research_task(agent,topic):"""创建研究任务"""returnTask(description=f"""对主题 "{topic}" 进行深入研究： 1. 搜索该主题的最新发展和趋势 2. 整理关键概念和技术要点 3. 收集实际应用案例 4. 总结核心观点和结论 研究主题：{topic}""",expected_output="""一份详细的研究报告，包含： - 主题概述 - 核心概念和技术要点 - 最新发展趋势 - 实际应用案例 - 总结与展望""",agent=agent,)defcreate_writing_task(agent,context_tasks):"""创建写作任务"""returnTask(description="""基于研究报告，撰写一篇技术文章： 1. 文章结构要清晰，使用标题和子标题 2. 语言通俗易懂，适合初学者阅读 3. 包含实际的代码示例或操作步骤 4. 文章长度 1500-2000 字""",expected_output="""一篇高质量的技术文章，格式为 Markdown， 包含完整的标题、正文和代码示例。""",agent=agent,context=context_tasks,)defcreate_editing_task(agent,context_tasks):"""创建编辑任务"""returnTask(description="""审核和修改文章： 1. 检查事实准确性 2. 修正语法和表达错误 3. 优化文章结构和逻辑 4. 确保技术术语使用正确""",expected_output="""最终修改后的文章，包含编辑批注 和修改说明。""",agent=agent,context=context_tasks,)

8. 编写主程序

创建app/main.py：

importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromcrewaiimportCrew,Processfromagentsimportcreate_researcher,create_writer,create_editorfromtasksimportcreate_research_task,create_writing_task,create_editing_task# 加载环境变量load_dotenv()defmain():# 初始化 LLMllm=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 技术的发展趋势与应用前景"# 创建 Agentsresearcher=create_researcher(llm)writer=create_writer(llm)editor=create_editor(llm)# 创建 Tasksresearch_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：

services:crewai:build:.container_name:crewai-appenv_file:-.envvolumes:-./app:/app/app-./output:/app/outputenvironment:-PYTHONPATH=/app-PYTHONUNBUFFERED=1restart:unless-stoppednetworks:-crewai-netnetworks:crewai-net:driver:bridge

10. 启动服务

10.1 构建并启动

cd~/crewai-project# 构建镜像dockercompose build# 启动服务dockercompose up

10.2 查看日志

# 实时查看日志dockercompose 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 后台运行

# 后台运行dockercompose up-d# 查看日志dockercompose logs-f# 停止服务dockercompose down

11. 进阶配置

11.1 使用本地 Ollama 模型

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

修改.env：

OPENAI_API_KEY=ollamaOPENAI_API_BASE=http://host.docker.internal:11434/v1OPENAI_MODEL_NAME=qwen2.5:14b

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

services:crewai:build:.container_name:crewai-appenv_file:-.envextra_hosts:-"host.docker.internal:host-gateway"volumes:-./app:/app/apprestart:unless-stopped

11.2 添加自定义工具

创建app/tools/search_tool.py：

fromcrewai.toolsimportBaseToolfromtypingimportTypefrompydanticimportBaseModel,FieldimportrequestsclassSearchInput(BaseModel):query:str=Field(description="搜索关键词")classWebSearchTool(BaseTool):name:str="web_search"description:str="搜索互联网获取最新信息"args_schema:Type[BaseModel]=SearchInputdef_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,)returnresponse.textexceptExceptionase:returnf"搜索失败：{str(e)}"

在 Agent 中使用工具：

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

11.3 使用层级管理

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 依赖安装失败

# 重新构建镜像dockercompose build --no-cache

13. 总结

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

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

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