メールアシスタント、人間とAIの協調、記憶機能、Gmail連携を含む、AIエージェントをゼロから構築するための完全なチュートリアル

Agents From Scratch - AIエージェントをゼロから構築するガイド

プロジェクト概要

このリポジトリは、AIエージェントをゼロから構築するためのガイドです。Gmail APIを通じてメールを管理できる「環境認識」エージェントを段階的に構築します。LangChain AIチームによって開発され、AIエージェント開発を学習し実践するための優れたリソースです。

プロジェクト構成

主要な構成要素

プロジェクトは4つの主要な部分に分かれており、各部分にはJupyter notebookと対応するコード実装が含まれています。

1. エージェントの基礎 - 基本的なエージェント機能を構築
2. エージェントの評価 - エージェントのパフォーマンス評価メカニズムを実装
3. 人間と機械の協調 - 人工的な介入とレビュープロセスを統合
4. 記憶システム - 長期記憶と学習能力を追加

ディレクトリ構造

• notebooks/ - 教育用のJupyter notebookが含まれています
• 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 Studioの使用など、LangGraphの基本概念を紹介

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. 実践者: 4つの主要なnotebookを順番に完了し、完全な機能を段階的に構築する
3. 開発者: srcディレクトリの実装コードを調査し、エンジニアリングの実践を理解する
4. デプロイヤー: Gmail APIを設定し、本番環境にデプロイする

技術的な特徴

• 漸進的な学習: 基礎から高度まで、段階的に学習
• 実際の応用: 実際のメール処理シナリオ
• 完全なエンジニアリング: テスト、評価、デプロイを含む完全なソリューション
• 拡張性: 原理は他のエージェントタスクにも適用可能