LangChain CLI 是构建 AI 智能体应用时绕不开的脚手架工具。它解决的核心问题是：当你想快速开始一个 LangChain 项目时，不必手动创建目录、配置环境变量、选择模型接口，只需一条命令即可生成完整的项目骨架。然而，仅仅掌握 pip install langchain-cli 并不足以应对实际开发中的各种场景，安装后的项目初始化、模板选择、模块管理与后续扩展都需要系统的理解。本文将围绕 LangChain CLI 的安装与项目初始化展开，结合具体命令和实际输出，逐步带你搭建第一个可运行的智能体项目。
安装 LangChain CLI 前的环境准备
在运行任何安装命令之前，先确认本机的 Python 环境。LangChain CLI 基于 Python 3.8 及以上版本开发，推荐使用 3.10 或 3.11，因为这两个版本在依赖兼容性上表现得最为稳定。如果你的系统同时存在多个 Python 版本，建议使用 python3 --version 命令查看当前默认版本，如果低于 3.8，需要先升级 Python 环境。
为了避免全局 Python 环境中出现包冲突，强烈建议为 LangChain 项目创建独立的虚拟环境。在 Linux 或 macOS 下，可以使用 python3 -m venv .venv 创建虚拟环境，然后通过 source .venv/bin/activate 激活。在 Windows 下，命令略有不同：python -m venv .venv 创建环境后，激活脚本位于 .venv\Scripts\activate。注意这里必须使用反斜杠，路径写法是 .venv\Scripts\activate，不要写成正斜杠，否则 Windows 命令解释器无法识别。
创建虚拟环境是一个好习惯，尤其在多个项目需要不同依赖版本时。如果不使用虚拟环境，直接执行 pip 安装，可能会污染系统级 Python，导致其他项目无法运行。下面是一组完整的准备命令：
# 检查 Python 版本 python3 --version # 创建虚拟环境（Linux/macOS） python3 -m venv .venv source .venv/bin/activate # 创建虚拟环境（Windows） python -m venv .venv .venv\Scripts\activate
完成上述操作后，命令行提示符前会出现 (.venv) 标记，表示当前已经在虚拟环境中。此时可以开始安装 LangChain CLI。
使用 pip 安装 LangChain CLI 的核心步骤
在激活的虚拟环境中执行 pip install langchain-cli，pip 会自动解析依赖并下载对应包。最新版本的 LangChain CLI 会在安装时同时引入 langchain-core 等基础库，因此无需手动安装这些依赖。如果你需要安装特定版本，可以执行 pip install langchain-cli==0.0.15，其中版本号可以根据官方发布记录替换。
安装过程可能需要几十秒，这取决于网络状况。安装完成后，建议执行 langchain --version 来验证 CLI 是否正常工作。如果命令能正确输出版本号，说明安装成功。如果提示 command not found，原因通常是虚拟环境未激活，或者 Python 的 Scripts 目录没有加入 PATH。在 Unix 系统中，可以检查 .venv/bin 目录下是否存在 langchain 可执行文件；在 Windows 中则检查 .venv\Scripts 目录。
一个常见的安装陷阱是 pip 版本过旧。如果遇到 ModuleNotFoundError 或依赖解析错误，建议先升级 pip：pip install --upgrade pip，然后重新安装 langchain-cli。此外，在苹果 M 系列芯片上，某些依赖可能需要通过 conda 安装编译好的二进制包，单纯使用 pip 可能会遇到 Failed to build 错误。这时可以尝试使用 arch -arm64 pip install langchain-cli 指定架构。
# 安装 LangChain CLI pip install langchain-cli # 验证安装版本 langchain --version # 如果 pip 版本过旧，先升级 pip install --upgrade pip
安装成功后，就可以使用 langchain 命令进行项目初始化了。
初始化 AI 智能体项目：命令与模板选择
LangChain CLI 提供了多个子命令，其中 langchain app new 用于创建新的智能体应用项目。要初始化一个名为 my-agent 的项目，可以执行 langchain app new my-agent。执行后，CLI 会询问你希望使用哪种模板。默认模板是 simple，它提供了一个最基础的可运行示例；如果选择 chat，则会生成带聊天界面和消息历史的完整项目。此外，还有 react 模板，内置了 ReAct 推理循环，适合开发需要工具调用的智能体。
模板选择的本质差异在于项目的复杂度与默认依赖。simple 模板只包含一个 API 路由和最简单的 prompt，适合学习或做最小验证；chat 模板引入了数据库存储、会话管理，适合构建真正可交互的智能体应用；react 模板则集成了工具调用逻辑，方便开发者快速接入外部 API。对于初学者，建议先选择 simple 模板跑通流程，再逐步迁移到更复杂的模板。
初始化命令执行后，会在当前目录下生成一个以项目名命名的文件夹。下面是执行 langchain app new my-agent 并选择 simple 模板后生成的核心文件列表：
my-agent/ |-- app/ | |-- __init__.py | |-- main.py | `-- server.py |-- packages/ | `-- my-agent/ | |-- __init__.py | `-- agent.py |-- .env |-- pyproject.toml `-- langchain.json
其中 langchain.json 是项目配置文件，CLI 根据它识别项目结构和启动方式。.env 文件存放环境变量，例如模型 API 密钥。app/server.py 是 FastAPI 入口文件，负责启动本地开发服务器。packages 目录则用来存放智能体逻辑代码，后续添加新的 agent 模块也需要放在这个目录中。
如果你在初始化时没有指定模板，之后可以通过修改 langchain.json 来调整，但这需要手动处理依赖，比较繁琐。因此初始化时选对模板能节省大量时间。
项目初始化的后续配置与运行检查
项目初始化完成后，首先要做的是配置环境变量。打开生成的 .env 文件，填入你的模型提供商 API 密钥。例如使用 OpenAI 时，需要设置 OPENAI_API_KEY=sk-xxx。LangChain CLI 会根据 .env 文件自动加载变量，无需手动设置系统环境变量。如果你使用本地模型或自托管模型服务，还需要在 .env 中指定 OPENAI_API_BASE 等自定义地址。
接下来安装项目依赖。进入项目目录，执行 pip install -e ".[all]"，这个命令会将项目本身以及所有额外依赖安装到当前虚拟环境。注意 -e 表示可编辑安装，这样你对项目代码的修改会即时生效，适合开发阶段。
依赖安装完成后，执行 langchain serve 启动开发服务器。默认情况下，服务会运行在 http://127.0.0.1:8000。打开浏览器访问该地址，可以看到 FastAPI 自动生成的交互式 API 文档。如果端口被占用，可以使用 --port 8080 参数指定其他端口。启动过程中如果出现 AttributeError，通常是依赖版本不匹配，建议按照上一节的方法升级 pip 或重新安装依赖。
# 进入项目目录 cd my-agent # 安装项目依赖 pip install -e ".[all]" # 启动开发服务器 langchain serve # 指定端口启动 langchain serve --port 8080
启动后，你的 AI 智能体项目就已经可以接收请求了。你可以使用 curl 或者 API 文档页面测试智能体的响应。整个安装和初始化流程并不复杂，但理解每一步背后的原理，能帮助你在面对各种异常时更快定位问题。
LangChain CLIAI智能体项目初始化修改时间：2026-08-27 01:30:37