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並部署到生產環境

技術特色

• 漸進式學習: 從基礎到高級，循序漸進
• 實際應用: 真實的郵件處理場景
• 完整工程: 包含測試、評估、部署的完整解決方案
• 可擴展性: 原理可應用於其他智慧代理任務