从零开始构建 Agent (智能体)

本仓库是一份从零开始构建 Agent (智能体) 的指南。它最终构建出一个 "ambient"(环境感知/背景式) Agent，能够通过连接 Gmail API 来管理你的电子邮件。它分为 4 个部分，每个部分都有一个 Notebook (交互式笔记本) 以及 src/email_assistant 目录中的配套代码。这些部分从 Agent 基础开始，逐步深入到 Agent 评估、人机协同 (Human-in-the-loop)，最后是记忆 (Memory)。所有这些部分共同构成了一个可部署的 Agent，其原则可应用于广泛任务中的其他 Agent。

环境设置

Python 版本

• 确保你使用的是 Python 3.11 或更高版本。
• 此版本是与 LangGraph 获得最佳兼容性所必需的。

python3 --version

API 密钥

• 如果没有 OpenAI API 密钥，可以 在此处 注册。
• 在此处 注册 LangSmith。
• 生成一个 LangSmith API 密钥。

设置环境变量

• 在根目录创建一个 .env 文件：

# Copy the .env.example file to .env
cp .env.example .env

• 按以下内容编辑 .env 文件：

LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=your_openai_api_key

• 你也可以在终端中设置环境变量：

export LANGSMITH_API_KEY=your_langsmith_api_key
export LANGSMITH_TRACING=true
export OPENAI_API_KEY=your_openai_api_key

安装包

推荐：使用 uv（更快更可靠）

# Install uv if you haven't already
pip install uv

# Install the package with development dependencies
uv sync --extra dev

# Activate the virtual environment
source .venv/bin/activate

备选：使用 pip

$ python3 -m venv .venv
$ source .venv/bin/activate
# Ensure you have a recent version of pip (required for editable installs with pyproject.toml)
$ python3 -m pip install --upgrade pip
# Install the package in editable mode
$ pip install -e .

⚠️ 重要：不要跳过包安装步骤！为了使 Notebook 正常工作，此可编辑安装是必需的。包安装为 interrupt_workshop，导入名称为 email_assistant，允许你从任何地方通过 from email_assistant import ... 进行导入。

结构

本仓库分为 4 个部分，每个部分都有一个 Notebook 以及 src/email_assistant 目录中的配套代码。

前言：LangGraph 101

关于 LangGraph 及本仓库中使用的一些概念的简要介绍，请参阅 LangGraph 101 Notebook。该 Notebook 解释了聊天模型 (Chat Models)、工具调用 (Tool Calling)、Agent 与工作流 (Workflow) 的区别、LangGraph 节点/边/记忆以及 LangGraph Studio 的基础知识。

构建 Agent

• Notebook (交互式笔记本): notebooks/agent.ipynb
• 代码：src/email_assistant/email_assistant.py

本 Notebook 展示了如何构建电子邮件助手，结合了一个 电子邮件分类 (Triage) 步骤 和一个处理电子邮件回复的 Agent。你可以在 src/email_assistant/email_assistant.py 中查看链接代码以获取完整实现。

评估

• Notebook (交互式笔记本): notebooks/evaluation.ipynb

本 Notebook 介绍了使用 eval/email_dataset.py 中的电子邮件数据集进行评估。它展示了如何使用 Pytest 和 LangSmith evaluate API 运行评估。它使用 LLM-as-a-judge (大模型即裁判) 运行电子邮件回复评估，以及工具调用和分类决策的评估。

人机协同 (Human-in-the-loop)

• Notebook (交互式笔记本): notebooks/hitl.ipynb
• 代码：src/email_assistant/email_assistant_hitl.py

本 Notebook 展示了如何添加人机协同 (Human-in-the-loop, HITL)，允许用户审查特定的工具调用（例如，发送邮件、安排会议）。为此，我们使用 Agent Inbox 作为人机协同的界面。你可以在 src/email_assistant/email_assistant_hitl.py 中查看链接代码以获取完整实现。

记忆 (Memory)

• Notebook (交互式笔记本): notebooks/memory.ipynb
• 代码：src/email_assistant/email_assistant_hitl_memory.py

本 Notebook 展示了如何为电子邮件助手添加记忆，使其能够从用户反馈中学习并随时间适应偏好。启用记忆的助手 (email_assistant_hitl_memory.py) 使用 LangGraph Store 来持久化记忆。你可以在 src/email_assistant/email_assistant_hitl_memory.py 中查看链接代码以获取完整实现。

连接 API

上述 Notebook 使用模拟的电子邮件和日历工具。

Gmail 集成与部署

按照 Gmail Tools README 中的说明设置 Google API 凭证。

该 README 还解释了如何将图 (Graph) 部署到 LangGraph Platform。

Gmail 集成的完整实现位于 src/email_assistant/email_assistant_hitl_memory_gmail.py。

运行测试

本仓库包含一个自动化测试套件，用于评估电子邮件助手。

测试使用 LangSmith 进行跟踪，以验证工具使用的正确性和响应质量。

使用 run_all_tests.py 运行测试

python tests/run_all_tests.py

测试结果

测试结果记录到 LangSmith 中，项目名称在你的 .env 文件 (LANGSMITH_PROJECT) 中指定。这提供了：

• Agent (智能体) 轨迹的可视化检查
• 详细的评估指标
• 不同 Agent 实现的比较

可用的测试实现

可用于测试的实现有：

• email_assistant - 基础电子邮件助手

测试 Notebook

你也可以运行测试以验证所有 Notebook 执行无误：

# Run all notebook tests
python tests/test_notebooks.py

# Or run via pytest
pytest tests/test_notebooks.py -v

未来扩展

添加 LangMem 以管理记忆：

• 管理一组背景记忆。
• 添加记忆工具，以便在背景记忆中查找事实。

agents-from-scratch 快速上手指南

本项目是一个从零构建 AI Agent 的实战指南，最终实现一个可管理邮件的“环境型”Agent。课程分为 Agent 构建、评估、人机协作（HITL）及记忆模块四个部分，包含配套 Notebook 和源代码。

环境准备

系统要求

• Python 版本: 3.11 或更高版本（LangGraph 兼容性要求）。
• API Keys:
  • OpenAI API Key
  • LangSmith API Key

环境变量配置

在项目根目录创建 .env 文件并配置密钥：

# 复制示例文件
cp .env.example .env

编辑 .env 文件，填入以下内容：

LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=your_openai_api_key

安装步骤

推荐方式：使用 uv (更快更可靠)

# 安装 uv
pip install uv

# 安装包及开发依赖
uv sync --extra dev

# 激活虚拟环境
source .venv/bin/activate

备选方式：使用 pip

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -e .

⚠️ 重要: 必须执行可编辑安装（-e . 或 uv sync）。包将被安装为 interrupt_workshop，导入名为 email_assistant，确保 Notebook 能正确导入模块。

基本使用

本项目主要通过 Jupyter Notebook 进行实践，核心代码位于 src/email_assistant 目录。

1. 运行基础 Agent

打开并运行以下 Notebook 以构建基础邮件助手：

• Notebook: notebooks/agent.ipynb
• 核心代码: src/email_assistant/email_assistant.py

2. 运行测试

验证环境安装及 Agent 功能是否正常，测试结果将同步至 LangSmith：

python tests/run_all_tests.py

3. 进阶学习

完成基础构建后，可依次学习以下模块：

• 评估: notebooks/evaluation.ipynb
• 人机协作: notebooks/hitl.ipynb (使用 Agent Inbox 接口)
• 记忆模块: notebooks/memory.ipynb (使用 LangGraph Store)

4. Gmail 集成（可选）

如需连接真实 Gmail API，请参考 src/email_assistant/tools/gmail/README.md 配置凭证，并使用 src/email_assistant/email_assistant_hitl_memory_gmail.py 实现完整部署。