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