福桃九分饱最近在做AI代理落地的项目，核心诉求很直接：让一个能理解自然语言的代理跑起来，能调用外部工具，还要能对外提供HTTP接口，最后能一键部署到服务器上。调研之后我确定了LangGraph、FastAPI、MCP和Docker这个组合，整套流程跑通之后收获很大，今天把完整的整合过程和技术取舍记录一下。这套技术栈的定位很清楚：LangGraph负责代理的工作流编排，解决"代理如何思考、如何调用工具、如何维护状态"的问题；FastAPI负责把代理能力封装成REST接口，让其他系统能通过HTTP调用；MCP是代理和外部工具之间的标准化协议，避免每个工具都写一套定制接入；Docker则把整个环境固化下来，解决依赖混乱和部署困难的问题。
如果你是后端工程师想做AI代理，或者已经在用LangChain/LangGraph但不知道怎么对外提供服务，又或者是在研究MCP怎么落地，这篇文章应该能帮你省不少折腾时间。我会从架构设计、环境准备、核心代码、容器化部署到问题排查，完整走一遍，把关键选择和踩过的坑都讲清楚。
1. 技术选型与整体架构设计
1.1 为什么是这四个组件
先聊LangGraph。做AI代理，我之前用过纯LangChain的AgentExecutor，也尝试过自己手写状态机。LangChain的AgentExecutor在简单场景下够用，但一旦涉及多步骤任务、条件回退、人工确认这类复杂流程，它的控制能力就很弱。LangGraph把代理建模成一张有向图，节点是处理步骤，边是状态转移，这个思路跟传统后端开发里的状态机非常像，只不过状态里存的是对话历史、任务上下文这些内容。有向图的结构意味着你可以精确控制代理每一步做什么、什么时候循环、什么时候结束，这在生产环境里是刚需。
FastAPI的选择比较轻松。Python生态里做API服务，FastAPI现在的成熟度已经很高了，异步原生支持、基于类型提示的请求校验、自动生成OpenAPI文档，对AI应用这种经常要挂长连接和流式响应的场景非常友好。而且LangGraph天然支持异步节点，FastAPI的异步支持能直接对接，不需要额外的适配层。我之前用Flask写过类似接口，遇到并发请求时性能差距还是挺明显的。
MCP（Model Context Protocol）解决的是工具接入标准化的问题。在MCP出现之前，代理要接一个数据库查询工具、接一个文件读取工具，每个工具都要手工写一套调用约定，工具多了以后维护成本很高。MCP定义了一套统一的协议：MCP Server暴露工具的元信息和执行入口，MCP Client按标准格式发起请求，代理只需要跟Client打交道。现在社区里已经有很多现成的MCP Server，比如连数据库的、连Figma设计的、连本地文件系统的，搭好就能直接用，这对加速开发很有帮助。
Docker就是最后的保障环节。Python项目最头疼的就是环境依赖，今天在这台机器上跑得好好的，换一台机器就各种报错。容器化之后，Python版本、系统库、模型文件路径这些都固化在镜像里，不再有"我本地是好的"这种问题。而且配合docker-compose，整个代理服务加MCP Server可以一键起停，部署成本降了一个量级。
1.2 整体架构拆解
这个项目的架构可以分成四层：入口层是FastAPI应用，负责接收HTTP请求，做鉴权、参数校验、请求转发；编排层是LangGraph代理，维护对话状态和任务状态，决定调用哪些工具、如何组合结果；工具层是MCP Server集群，提供标准化的工具能力，代理通过MCP Client调用它们；基础设施层是Docker容器，承载以上所有组件，通过docker-compose统一编排。
用一张简单的调用链路来说明：HTTP请求进来，FastAPI创建任务，把请求交给LangGraph代理，代理在图中流转，到工具节点时通过MCP Client调用对应工具，工具执行完毕返回结果，代理汇总后生成最终响应，FastAPI再把结果返回给调用方。
在实际落地时，我建议把代理、API服务、MCP Server拆成三个独立的容器。这样做的理由很实际：三个组件的资源消耗不同，独立容器可以分别设置CPU和内存上限；任何一个组件升级或宕机，不会拖垮整个系统；日志和监控也能按组件分开处理，排查问题的时候不用在一堆混合日志里翻找。如果你的项目规模不大，也可以先把MCP Server合并进代理容器，减少部署复杂度，等工具多了再拆开。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础工具链
2.1 Python环境搭建与依赖管理
我这次用的是uv包管理器。之前用pip加venv管理依赖，项目一多就乱了，虚拟环境路径记不住，依赖版本经常冲突。uv的特点是速度快，而且pyproject.toml加uv.lock锁依赖，在容器里复现环境比requirements.txt要可靠得多。第一步先装uv，macOS或Linux用官方脚本，Windows直接pip安装。
bash复制# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
pip install uv
然后是初始化项目并创建虚拟环境：
bash复制uv init langgraph-fastapi-mcp-demo
cd langgraph-fastapi-mcp-demo
uv venv
接下来添加核心依赖。我习惯把运行依赖和开发依赖分开，这样Docker镜像只装运行依赖，镜像能小不少。
bash复制uv add langgraph langchain-openai fastapi uvicorn mcp httpx
uv add --dev pytest
这里要提醒一句：langgraph和langchain的版本迭代很快，API变动频繁，建议锁定主版本。我写这篇文章时用的是langgraph 0.2.x，如果你下载的时候已经出现更新的主版本，先看官方迁移文档再动手，否则照着老代码写可能直接报模块不存在。另外，mcp这个库的Python实现还比较年轻，接口也有调整过，踩坑概率比LangGraph还高，建议安装时记下具体版本号。
2.2 Docker环境准备与常见启动问题
Docker这块，Windows用户最容易踩的坑就是Docker Desktop启动时报"Virtualization support not detected"或者"WSL 2 installation is incomplete"。这通常意味着BIOS里的虚拟化没有开启，或者WSL2内核没有更新。我按下面的顺序排查过几次，基本能解决：
- 进BIOS检查Intel VT-x或AMD-V是否启用，不同品牌电脑入口不一样，一般是开机按Del或F2。
- 执行
wsl --update更新WSL内核，确保WSL2可用。 - 在"启用或关闭Windows功能"里勾选"虚拟机平台"和"适用于Linux的Windows子系统"。
- 重启Docker Desktop。
装好后先验证一下：
bash复制doc