Agents From Scratch - AI智能体从零构建指南

项目概述

这个仓库是一个从零开始构建智能体（agents）的指南。它逐步构建一个"环境感知"智能体，能够通过Gmail API管理您的邮件。项目由LangChain AI团队开发，是学习和实践AI智能体开发的优秀资源。

项目结构

核心组成部分

项目分为4个主要部分，每个部分都包含一个Jupyter notebook和相应的代码实现：

智能体基础 - 构建基本的智能体功能
智能体评估 - 实现智能体性能评估机制
人机协作 - 集成人工干预和审核流程
记忆系统 - 添加长期记忆和学习能力

目录结构

notebooks/ - 包含教学用的Jupyter notebooks
src/email_assistant/ - 邮件助手的核心实现代码
eval/ - 评估相关的数据集和工具
tests/ - 自动化测试套件

技术要求

环境要求

Python版本: 3.11或更高版本（为了与LangGraph的最佳兼容性）
主要依赖: LangGraph, OpenAI API, LangSmith

API密钥配置

需要配置以下API密钥：

OpenAI API密钥（用于语言模型调用）
LangSmith API密钥（用于追踪和评估）

环境设置

# 检查Python版本
python3 --version

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

# 升级pip
python3 -m pip install --upgrade pip

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

环境变量配置

# 复制环境变量模板
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

详细功能模块

1. LangGraph基础入门

文件: notebooks/langgraph_101.ipynb
内容: 介绍LangGraph的基本概念，包括聊天模型、工具调用、智能体与工作流的区别、LangGraph节点/边/记忆系统，以及LangGraph Studio的使用

2. 邮件助手构建

Notebook: notebooks/agent.ipynb
代码: src/email_assistant/email_assistant.py
功能:
- 结合邮件分类步骤与智能体响应处理
- 实现完整的邮件处理工作流
- 提供邮件自动回复功能

3. 智能体评估系统

Notebook: notebooks/evaluation.ipynb
数据集: eval/email_dataset.py
功能:
- 使用Pytest和LangSmith evaluate API进行评估
- 实现LLM作为评判者的评估机制
- 评估工具调用和分类决策的准确性

4. 人机协作（HITL）

Notebook: notebooks/hitl.ipynb
代码: src/email_assistant/email_assistant_hitl.py
功能:
- 集成人工审核机制
- 支持特定工具调用的人工确认（如发送邮件、安排会议）
- 使用Agent Inbox作为人机交互界面

5. 记忆系统

代码: src/email_assistant/email_assistant_hitl_memory.py
功能:
- 从用户反馈中学习和适应
- 使用LangGraph Store持久化记忆
- 支持个性化偏好设置

6. Gmail集成

代码: src/email_assistant/email_assistant_hitl_memory_gmail.py
功能:
- 真实Gmail API连接
- 完整的邮件管理功能
- 支持部署到LangGraph Platform

测试系统

自动化测试套件

项目包含完整的自动化测试系统，用于验证邮件助手实现的正确性：

# 运行默认实现测试
python tests/run_all_tests.py

# 运行特定实现测试
python tests/run_all_tests.py --implementation email_assistant_hitl

# 运行所有实现的测试
python tests/run_all_tests.py --all

# 指定实验名称进行LangSmith追踪
python tests/run_all_tests.py --experiment-name "Custom Test Run"

可测试的实现版本

email_assistant - 基础邮件助手
email_assistant_hitl - 人机协作版本
email_assistant_hitl_memory - 带记忆功能的HITL版本
email_assistant_hitl_memory_gmail - Gmail集成版本

评估指标

智能体追踪的可视化检查
详细的评估指标
不同智能体实现的对比分析

部署说明

LangGraph Platform部署

项目支持部署到LangGraph Platform，实现生产环境的智能体服务。

Gmail工具设置

需要按照 src/email_assistant/tools/gmail/README.md 中的说明设置Google API凭证。

学习路径建议

初学者: 从LangGraph 101 notebook开始，了解基础概念
实践者: 按顺序完成四个主要notebook，逐步构建完整功能
开发者: 研究src目录下的实现代码，理解工程实践
部署者: 配置Gmail API并部署到生产环境

技术特色

渐进式学习: 从基础到高级，循序渐进
实际应用: 真实的邮件处理场景
完整工程: 包含测试、评估、部署的完整解决方案
可扩展性: 原理可应用于其他智能体任务

agents-from-scratch