从零手搓AI编程智能体：LangGraph与MCP环境搭建全流程

1. 为什么我要从零手搓一个AI编程智能体先说结论现成的AI编程工具我用过不少但真正让我决定自己动手从零搭一个智能体的原因只有一个——可控性。市面上的成品要么把关键链路封装成黑盒要么在工具调用、上下文管理、多轮状态保持上做了太多妥协遇到稍微复杂一点的真实项目就露怯。而自己基于 LangGraph 搭一套从状态机设计到 MCP 工具接入每一层都能按自己的需求改这才是长期能用的东西。这篇文章要聊的就是这套智能体的环境准备全流程。别小看环境准备这一步我见过太多人卡在 Python 版本冲突、依赖装不上、MCP 服务连不通这些破事上还没开始写核心逻辑就放弃了。所以我把从零到能跑通第一个 Agent 循环的完整环境搭建过程拆开讲包括 Python 环境怎么选、LangGraph 怎么装、MCP 是什么以及怎么接、目录结构怎么规划、常见坑怎么绕。适合谁看如果你有基本的 Python 基础想搞明白 AI 编程智能体到底是怎么搭起来的或者你已经会用一些现成工具但想深入定制这篇都能给你一条能直接抄作业的路径。我会把每一步的为什么讲清楚而不是甩一堆命令让你照敲。环境准备这件事理解原理比记住命令重要得多因为你的机器、你的系统、你的网络环境都跟我不一样只有懂了原理才能自己排错。整篇内容围绕一条主线从一台干净的机器到能跑通一个带 MCP 工具调用的 LangGraph 智能体。中间涉及 Python 安装、虚拟环境、依赖管理、LangGraph 核心概念、MCP 协议理解、工具接入、目录规划、联调验证。我会把踩过的坑和实测有效的方案都放进来尽量让你少走弯路。2. 环境准备的整体思路与选型考量2.1 为什么环境准备值得单独拿出来讲很多人觉得环境准备就是装个 Python 装个库五分钟的事。但实际做 AI 智能体开发环境问题能占掉你前期一半的时间。原因在于这类项目依赖链条特别长底层是 Python 解释器中间是 LangGraph、LangChain 这一套框架再往上是各种模型 SDK最外层还要接 MCP 工具服务。任何一层版本对不上报错信息都极其晦涩新手根本看不出是哪一层的问题。我自己的做法是分层隔离、逐层验证。先把 Python 解释器这一层搞干净再单独验证 LangGraph 能跑再单独验证 MCP 能连最后才把它们拼起来。这样出问题的时候你能快速定位是哪一层挂了而不是面对一个巨大的报错堆栈发呆。这个思路贯穿整篇文章你在操作的时候也要有这个意识。2.2 Python 版本怎么选别追新追稳Python 版本选择是第一个坑。网上教程有的让你装最新版有的让你用 3.8到底听谁的我的建议是优先选 3.11 或 3.12。原因有几个LangGraph 和它依赖的 LangChain 生态对 3.9 以下的支持越来越差很多新特性用不了而 3.13 又太新部分底层依赖尤其是一些需要编译的包还没跟上容易在 pip install 阶段就卡住。如果你机器上已经有 Python先确认版本python --version # 或者 python3 --version如果显示的是 3.8 甚至更低强烈建议单独装一个 3.11。注意不要直接覆盖系统自带的 Python尤其在 Linux 和 macOS 上系统很多工具依赖它覆盖了会出大问题。正确做法是装一个独立的版本然后用虚拟环境隔离。Windows 用户相对简单去 Python 官网下载 3.11 的安装包安装时务必勾选 Add Python to PATH这一步漏了后面全是麻烦。macOS 用户我推荐用 Homebrew 装brew install python3.11Linux 用户可以用 deadsnakes 源或者 pyenvpyenv 更干净能同时管理多个版本curl https://pyenv.run | bash pyenv install 3.11.9 pyenv global 3.11.92.3 虚拟环境不是可选项是必选项我见过太多人所有项目共用一个全局 Python 环境装到后面依赖互相打架一个项目能跑另一个就崩。虚拟环境就是给每个项目一个独立的依赖空间互不干扰。Python 自带 venv 就够了不需要额外装 virtualenv。创建和激活# 创建 python -m venv .venv # 激活Windows .venv\Scripts\activate # 激活macOS / Linux source .venv/bin/activate激活后你的命令行前面会出现(.venv)标识这时候 pip 装的所有东西都只在这个环境里。每次开发前第一件事就是激活虚拟环境忘了激活然后装依赖装到全局去了后面又是一堆玄学问题。2.4 依赖管理requirements 还是 pyproject小项目用requirements.txt就够了简单直接。但 AI 智能体项目依赖多、迭代快我更推荐用pyproject.toml配合 uv 或 poetry 这类现代工具。不过考虑到上手成本这篇先用最朴素的requirements.txt把核心跑通再说工具链的升级可以后面再做。一个关键经验装依赖时锁定版本。不要写langgraph这种不指定版本的要写langgraph0.2.x这种。因为 AI 框架迭代极快今天能跑的代码下周可能就因为框架升级跑不了了。锁定版本能保证你的环境可复现。3. LangGraph 与 MCP 核心概念拆解3.1 LangGraph 到底解决什么问题一句话解释LangGraph 是帮你把 AI 智能体的执行流程画成一张图的框架。传统的链式调用比如 LangChain 的 Chain是线性的A 完了到 BB 完了到 C。但真实的智能体不是线性的它需要根据情况决定下一步干什么——要不要调用工具、调用哪个工具、结果不满意要不要重试、多轮对话状态怎么保持。这些用线性链很难优雅表达用图就很自然。LangGraph 里几个核心概念你得先建立起来State状态整个图共享的一份数据所有节点都能读写。比如对话历史、当前任务、工具调用结果都放这里。Node节点图里的一个执行单元本质就是一个函数接收 State 返回 State 的更新。Edge边节点之间的连接决定执行流向。普通边是固定的条件边conditional edge可以根据 State 动态决定走哪条路。Graph图把节点和边组装起来编译后就是一个可执行的智能体。理解了这四个概念你就理解了 LangGraph 的全部骨架。剩下的都是细节。3.2 MCP 是什么为什么智能体需要它MCP 全称 Model Context Protocol翻译过来叫模型上下文协议。你可以把它理解成AI 模型和外部工具之间的一个标准接口。在没有 MCP 之前你想让 AI 调用一个工具比如读文件、查数据库、调 API得针对每个工具写一套适配代码工具一多就乱套。MCP 做的事情就是把这个适配过程标准化只要工具实现了 MCP 协议任何支持 MCP 的智能体都能直接调用它不用改代码。打个比方MCP 就像 USB 接口。以前每个设备有自己的充电口乱七八糟有了 USB 标准之后一根线走天下。MCP 就是 AI 工具界的 USB。MCP 里有几个角色要分清MCP Server提供工具的一方比如一个文件操作服务、一个数据库查询服务。MCP Client调用工具的一方在你的智能体里就是那个负责跟 Server 通信的客户端。Tools / Resources / PromptsServer 暴露出来的能力工具是最常用的。对 AI 编程智能体来说MCP 的价值在于你可以把代码读写、终端执行、文件搜索这些能力都封装成 MCP Server智能体通过统一的协议去调用扩展性极强。想加新能力加个 Server 就行智能体主体代码不用动。3.3 为什么选 LangGraph MCP 这个组合市面上搭智能体的方案不少为什么我选这个组合LangGraph 负责流程编排和状态管理MCP 负责工具接入和能力扩展两者职责清晰、互不耦合。LangGraph 不关心你的工具是怎么实现的MCP 也不关心你的流程怎么走这种解耦让整个系统特别好维护。另一个原因是生态。LangGraph 背后是 LangChain 团队文档和社区都相对成熟MCP 是近一年快速崛起的标准主流工具都在往这个方向靠。选这两个等于站在了当前最主流的技术路线上遇到问题好搜、好问。4. 从零搭建环境的完整实操4.1 第一步确认并安装 Python先检查现有环境python3 --version pip3 --version如果版本低于 3.10按 2.2 节的方法装一个 3.11。装完之后验证python3.11 --version # 输出应为 Python 3.11.xWindows 用户如果装了多个版本可以用py -3.11 --version来指定。这一步的目标是确保你有一个干净的、版本正确的解释器可用后面所有操作都基于它。4.2 第二步创建项目目录和虚拟环境我习惯的目录结构是这样的你可以参考ai-agent/ ├── .venv/ # 虚拟环境 ├── src/ # 源码 │ ├── agent/ # 智能体核心逻辑 │ ├── tools/ # MCP 工具相关 │ └── config/ # 配置 ├── tests/ # 测试 ├── requirements.txt # 依赖 └── README.md创建并进入mkdir ai-agent cd ai-agent python3.11 -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate激活后升级一下 pip老版本 pip 装某些包会出问题python -m pip install --upgrade pip4.3 第三步安装 LangGraph 及核心依赖先写requirements.txt锁定版本langgraph0.2.60 langchain-core0.3.25 langchain-openai0.2.14 mcp1.1.0 python-dotenv1.0.1然后安装pip install -r requirements.txt这里有个实测经验如果安装过程中卡在某个包编译上常见于没有预编译 wheel 的包先确认你的 Python 版本是不是太新。3.13 上很多包还没出 wheelpip 会尝试从源码编译慢且容易失败。换回 3.11 基本就顺了。装完验证 LangGraph 能正常导入python -c import langgraph; print(langgraph.__version__)能打印出版本号就说明这一层通了。4.4 第四步配置模型访问凭证智能体要调用大模型得配置 API Key。千万不要把 Key 硬编码在代码里用.env文件管理# .env OPENAI_API_KEYyour_key_here OPENAI_BASE_URLhttps://api.openai.com/v1然后在代码里用python-dotenv加载from dotenv import load_dotenv import os load_dotenv() api_key os.getenv(OPENAI_API_KEY)记得把.env加进.gitignore别把 Key 提交到仓库里这是血泪教训。4.5 第五步跑通第一个最小 LangGraph 示例环境装好了先别急着接 MCP跑一个最小的图验证 LangGraph 本身没问题from typing import TypedDict from langgraph.graph import StateGraph, START, END class State(TypedDict): message: str def node_a(state: State) - State: return {message: state[message] - A} def node_b(state: State) - State: return {message: state[message] - B} builder StateGraph(State) builder.add_node(a, node_a) builder.add_node(b, node_b) builder.add_edge(START, a) builder.add_edge(a, b) builder.add_edge(b, END) graph builder.compile() result graph.invoke({message: start}) print(result) # 预期输出: {message: start - A - B}这段代码虽然简单但把 LangGraph 的核心全用上了State 定义、节点函数、边连接、编译执行。能跑通这个说明你的 LangGraph 环境完全 OK可以进入下一步。4.6 第六步搭建并验证 MCP 连接MCP 的接入分两块一是有一个 MCP Server 可用二是你的智能体里有一个 MCP Client 去连它。先用官方提供的一个简单 Server 做验证。安装 MCP 后可以写一个最小的 Server# tools/simple_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-server) mcp.tool() def add(a: int, b: int) - int: 两数相加 return a b if __name__ __main__: mcp.run()然后写一个 Client 去调用它验证链路通不通# tools/test_client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params StdioServerParameters( commandpython, args[tools/simple_server.py], ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools.tools]) result await session.call_tool(add, {a: 3, b: 5}) print(调用结果:, result) asyncio.run(main())跑通后你会看到工具列表里有add调用返回 8。这一步是整个环境准备里最关键的一环因为它验证了 MCP 的 Server 和 Client 能正常通信。很多人卡在这里通常是路径问题或者 Python 解释器不对。4.7 第七步把 MCP 工具接进 LangGraph最后一步把 MCP 工具包装成 LangGraph 能调用的节点。核心思路是在节点函数里通过 MCP Client 调用工具把结果写回 State。async def tool_node(state: State) - State: params StdioServerParameters( commandpython, args[tools/simple_server.py], ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result await session.call_tool(add, {a: 1, b: 2}) return {message: f工具返回: {result}}把这个节点加进图里连上边编译执行。能跑通你的 AI 编程智能体环境就彻底搭好了后面就是往里面填业务逻辑的事。5. 常见问题与排查技巧实录5.1 依赖安装类问题现象可能原因解决思路pip install 卡在编译Python 版本太新无预编译包换 3.11或装对应编译工具链报 ModuleNotFoundError虚拟环境没激活确认命令行有 (.venv) 标识版本冲突多个包依赖同一库的不同版本用 pip check 查冲突逐个锁定装完导入报错装到了全局环境重新激活 venv 再装5.2 MCP 连接类问题MCP 连接失败最常见的原因是路径和解释器。StdioServerParameters里的command如果写python它用的是系统 PATH 里的 Python可能不是你虚拟环境里的那个。稳妥做法是写绝对路径import sys params StdioServerParameters( commandsys.executable, # 用当前解释器 args[tools/simple_server.py], )另一个坑是 Server 脚本里的相对路径。Server 启动后工作目录可能跟你预期不一样涉及文件读写的地方一律用绝对路径别用相对路径。5.3 我踩过的几个真实坑坑一忘了激活虚拟环境就装依赖。装完发现代码里 import 不到查半天才发现装全局去了。现在我的习惯是每次开终端先which python确认一下。坑二LangGraph 版本和 LangChain 版本不匹配。这俩是配套的单独升级一个经常出问题。锁定版本的时候要一起锁别只锁一个。坑三MCP Server 启动慢导致超时。有些 Server 初始化要加载模型或连数据库启动慢。Client 那边如果超时设置太短会直接失败。适当调大超时时间。坑四异步代码里混用同步调用。LangGraph 支持异步节点MCP Client 也是异步的但如果你在异步函数里调了同步的阻塞代码整个事件循环会卡住。要么全异步要么用run_in_executor包一下。提示环境问题排查的黄金法则是分层验证。Python 层、LangGraph 层、MCP 层一层一层单独测别混在一起测。哪层挂了修哪层效率高十倍。5.4 环境可复现的几条经验第一所有依赖锁版本requirements.txt 里写死。第二把环境搭建步骤写成脚本比如一个setup.sh换机器的时候一键跑。第三记录 Python 版本在 README 里写清楚用哪个版本验证过。第四MCP Server 的启动命令统一管理别散落在各处集中到一个配置文件里改起来方便。这几条看着简单但真到了团队协作或者换机器的时候能省你大量时间。我自己就因为没锁版本隔了一个月重装环境代码直接跑不起来排查了半天才发现是某个依赖偷偷升级了。6. 环境搭好之后的第一步该做什么环境跑通只是起点。我的建议是别急着写复杂的业务逻辑先做一个能完成单一任务的端到端智能体比如一个能读文件、能执行简单命令、能根据用户输入决定调用哪个工具的智能体。这个最小闭环跑通了你再往上加多轮对话、加记忆、加更复杂的工具心里就有底了。具体来说你可以先实现这样一个流程用户输入一个任务 - 智能体判断需要哪个工具 - 通过 MCP 调用工具 - 拿到结果 - 生成回复。这个流程用 LangGraph 的条件边就能实现节点不多但把智能体的核心循环走了一遍。我在实际搭这套东西的时候最大的体会是环境准备不是体力活是理解系统架构的过程。你在配 Python、装依赖、连 MCP 的每一步其实都在建立对整个系统分层的认知。这个认知建立起来了后面写代码就是水到渠成的事。反过来如果环境是稀里糊涂装上的后面遇到问题你根本不知道该从哪查。最后分享一个小技巧把每次环境搭建遇到的问题和解决方案记到一个TROUBLESHOOTING.md里日积月累就是你自己的知识库。我这份文档现在有几十条记录每次换机器或者带新人直接甩过去比任何教程都好使。环境这件事踩过的坑才是真正属于你的经验。