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

项目概述

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

项目结构

核心组成部分

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

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

目录结构

• 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凭证。

学习路径建议

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

技术特色

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