LangChain Agents From Scratch 项目部署教程

本教程将指导你从零开始，完整部署 langchain-ai/agents-from-scratch 项目。该项目是一个循序渐进的指南，最终能构建一个可连接 Gmail API 的“环境式”邮件助手，涵盖基础代理构建、评估、人机协同和记忆功能。

📋 准备工作

1. 环境要求

Python版本：确保使用 Python 3.11 或更高版本（LangGraph 的最佳兼容版本）。
包管理器（推荐）：uv，一个更快速可靠的 Python 包管理器。
Git：用于克隆仓库。

检查Python版本：

1	python3 --version

2. 获取API密钥

你需要注册并获取以下服务的API密钥：

OpenAI API Key：用于驱动代理的LLM。如果还没有，可以在OpenAI平台注册并生成。
LangSmith API Key：用于追踪、调试和评估代理。在LangSmith注册并生成API密钥。

🛠️ 安装与配置

1. 克隆仓库

使用Git将项目克隆到本地：

1 2	git clone https://github.com/langchain-ai/agents-from-scratch.git cd agents-from-scratch

2. 设置环境变量

项目使用.env文件管理环境变量。

复制示例文件：
1
cp .env.example .env

编辑.env文件，填入你的API密钥：

LANGSMITH_API_KEY=你的LangSmith_API密钥
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"  # LangSmith中的项目名称
OPENAI_API_KEY=你的OpenAI_API密钥

3. 安装项目依赖

项目提供了两种安装方式，强烈推荐使用 uv，因为它能更好地管理依赖和虚拟环境。

方式一：使用 uv（推荐）

# 安装uv（如果尚未安装）
pip install uv

# 同步安装项目依赖（包括开发依赖）
uv sync --extra dev

# 激活虚拟环境（Linux/macOS）
source .venv/bin/activate
# Windows系统激活命令: .venv\Scripts\activate

方式二：使用 pip

# 创建虚拟环境
python3 -m venv .venv
# 激活虚拟环境
source .venv/bin/activate

# 确保pip是最新版本
python3 -m pip install --upgrade pip

# 以可编辑模式安装项目
pip install -e .

⚠️ 关键步骤：此处的包安装步骤不可跳过。它会将项目安装为名为 interrupt_workshop 的包（导入名为 email_assistant），这是后续所有Jupyter Notebook能够正确运行的先决条件。

🚀 运行与探索

项目包含4个核心部分，每个部分都在notebooks目录下有对应的Jupyter Notebook，并配有在src/email_assistant目录下的源代码。

1. 启动Jupyter Notebook

在项目根目录下，运行以下命令启动Notebook：

1	jupyter notebook

或者，如果你使用uv：

1	uv run jupyter notebook

2. 按顺序学习Notebook

在浏览器中打开的Jupyter界面，按以下顺序打开并运行Notebook：

notebooks/LangGraph 101.ipynb（前置课程）：快速了解LangGraph的基础概念，包括聊天模型、工具调用、代理与工作流的区别、图结构、节点、边、记忆以及LangGraph Studio 。建议先运行此Notebook。
notebooks/agent.ipynb（构建代理）：此Notebook展示了如何构建核心的邮件助手，结合了邮件分类和代理响应的功能。对应的核心代码在 src/email_assistant/email_assistant.py。
notebooks/evaluation.ipynb（评估）：学习如何使用LangSmith的evaluate API和Pytest来评估代理性能，包括使用LLM作为评判者评估回复质量，以及评估工具调用和分类决策。
notebooks/hitl.ipynb（人机协同）：演示如何为关键操作（如发送邮件、安排会议）添加人工审核环节，使用Agent Inbox作为交互界面。相关代码在 src/email_assistant/email_assistant_hitl.py。
notebooks/memory.ipynb（记忆）：展示如何为代理添加记忆功能，使其能从用户反馈中学习并适应偏好。此实现使用了LangGraph Store来持久化记忆。相关代码在 src/email_assistant/email_assistant_hitl_memory.py。

3. 运行测试（可选）

项目包含了自动化测试套件，用于验证代理功能：

# 运行所有测试
python tests/run_all_tests.py

# 测试Notebooks是否能无错误执行
pytest tests/test_notebooks.py -v

测试结果会记录在你LangSmith账户的指定项目中。

🔌 连接真实API（Gmail）

上述Notebook默认使用模拟的邮件和日历工具。要连接真实的Gmail API，需要进行额外配置。

设置Google API凭证：按照项目内 Gmail Tools README 的指引，在Google Cloud Console创建OAuth 2.0客户端ID和密钥，并下载为 secrets.json 文件，放置在项目的 .secrets/ 目录下。
运行认证脚本：执行 setup_gmail.py 脚本以完成OAuth认证并生成 token.json 文件。
使用Gmail集成的代理：所有功能（含Gmail集成和记忆）的完整实现在 src/email_assistant/email_assistant_hitl_memory_gmail.py 中。

☁️ 部署到生产环境（LangGraph平台）

该项目可以部署到LangGraph平台。

配置 langgraph.json：这是LangGraph项目的配置文件，声明了依赖、图和环境变量。项目根目录已包含此文件。
使用LangGraph CLI部署：
- 确保已安装 langgraph-cli。
- 使用 langgraph deploy 命令进行一键部署。此命令会构建Docker镜像并推送到LangSmith Deployment 。
1
2
3
4
5
# 基本部署命令（使用.env中的API密钥）
langgraph deploy

# 指定部署名称
LANGSMITH_DEPLOYMENT_NAME=my-email-agent langgraph deploy
部署完成后，你可以通过LangSmith平台管理和监控你的代理。

💡 常见问题与故障排除

ModuleNotFoundError: No module named 'email_assistant'：这是因为没有执行关键的包安装步骤。请确保在虚拟环境激活后，运行了 pip install -e . 或 uv sync 。
API密钥无效或未找到：检查.env文件是否在项目根目录，且变量名（如 OPENAI_API_KEY）是否正确。对于Gmail，确保已正确完成OAuth流程并生成了 token.json 。
Python版本不兼容：LangGraph要求Python 3.11或更高版本，使用 python3 --version 检查并切换环境。
端口占用：如果在本地运行LangGraph服务时遇到端口冲突（如默认的2024端口），可以尝试修改配置文件或先关闭占用该端口的进程。