想搞明白Agent到底怎么从零搭起来，不是光会调API那种——我翻过不少资料，要么讲得太抽象，要么直接甩给你一个成品让你改改参数就完事，中间“为什么这样设计”的部分基本是空白。

LangChain官方的这个Agents From Scratch教程，是我目前见过最扎实的入门材料之一。它表面上是教你搭一个带人机协作和记忆的邮件助手，四大部分循序渐进：Agent基础搭建、评估体系、人机协作（HITL）、长期记忆。

每部分都有配套Notebook和完整代码，原理完全可以迁移到其他Agent场景。我在本地跑过一遍基础构建的Notebook，最直接的感受是它把LangGraph的节点、边、状态管理讲得很清楚。

从最简单的工具调用开始，逐步引入评估、审批门控、记忆持久化，每一步都能看到Agent行为的变化。最后的Gmail集成虽然需要申请API凭证，但整个部署路径是通的。

https://github.com/langchain-ai/agents-from-scratch…

langchain-ai/agents-from-scratch

Source: https://github.com/langchain-ai/agents-from-scratch

Agents From Scratch

The repo is a guide to building agents from scratch. It builds up to an “ambient” agent that can manage your email with connection to the Gmail API. It’s grouped into 4 sections, each with a notebook and accompanying code in the src/email_assistant directory. These section build from the basics of agents, to agent evaluation, to human-in-the-loop, and finally to memory. These all come together in an agent that you can deploy, and the principles can be applied to other agents across a wide range of tasks.

Environment Setup

Python Version

• Ensure you’re using Python 3.11 or later.
• This version is required for optimal compatibility with LangGraph.

python3 --version

API Keys

• If you don’t have an OpenAI API key, you can sign up here.
• Sign up for LangSmith here.
• Generate a LangSmith API key.

Set Environment Variables

• Create a .env file in the root directory:

# Copy the .env.example file to .env
cp .env.example .env

• Edit the .env file with the following:

LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=your_openai_api_key

• You can also set the environment variables in your terminal:

export LANGSMITH_API_KEY=your_langsmith_api_key
export LANGSMITH_TRACING=true
export OPENAI_API_KEY=your_openai_api_key

Package Installation

Recommended: Using uv (faster and more reliable)

# Install uv if you haven't already
pip install uv

# Install the package with development dependencies
uv sync --extra dev

# Activate the virtual environment
source .venv/bin/activate

Alternative: Using pip

$ python3 -m venv .venv
$ source .venv/bin/activate
# Ensure you have a recent version of pip (required for editable installs with pyproject.toml)
$ python3 -m pip install --upgrade pip
# Install the package in editable mode
$ pip install -e .

⚠️ IMPORTANT: Do not skip the package installation step! This editable install is required for the notebooks to work correctly. The package is installed as interrupt_workshop with import name email_assistant, allowing you to import from anywhere with from email_assistant import ...

Structure

The repo is organized into the 4 sections, with a notebook for each and accompanying code in the src/email_assistant directory.

Preface: LangGraph 101

For a brief introduction to LangGraph and some of the concepts used in this repo, see the LangGraph 101 notebook. This notebook explains the basics of chat models, tool calling, agents vs workflows, LangGraph nodes / edges / memory, and LangGraph Studio.

Building an agent

• Notebook: notebooks/agent.ipynb
• Code: src/email_assistant/email_assistant.py

This notebook shows how to build the email assistant, combining an email triage step with an agent that handles the email response. You can see the linked code for the full implementation in src/email_assistant/email_assistant.py.

Evaluation

• Notebook: notebooks/evaluation.ipynb

This notebook introduces evaluation with an email dataset in eval/email_dataset.py. It shows how to run evaluations using Pytest and the LangSmith evaluate API. It runs evaluation for emails responses using LLM-as-a-judge as well as evaluations for tools calls and triage decisions.

Human-in-the-loop

• Notebook: notebooks/hitl.ipynb
• Code: src/email_assistant/email_assistant_hitl.py

This notebooks shows how to add human-in-the-loop (HITL), allowing the user to review specific tool calls (e.g., send email, schedule meeting). For this, we use Agent Inbox as an interface for human in the loop. You can see the linked code for the full implementation in src/email_assistant/email_assistant_hitl.py.

Memory

• Notebook: notebooks/memory.ipynb
• Code: src/email_assistant/email_assistant_hitl_memory.py

This notebook shows how to add memory to the email assistant, allowing it to learn from user feedback and adapt to preferences over time. The memory-enabled assistant (email_assistant_hitl_memory.py) uses the LangGraph Store to persist memories. You can see the linked code for the full implementation in src/email_assistant/email_assistant_hitl_memory.py.

Connecting to APIs

The above notebooks using mock email and calendar tools.

Gmail Integration and Deployment

Set up Google API credentials following the instructions in Gmail Tools README.

The README also explains how to deploy the graph to LangGraph Platform.

The full implementation of the Gmail integration is in src/email_assistant/email_assistant_hitl_memory_gmail.py.

Running Tests

The repository includes an automated test suite to evaluate the email assistant.

Tests verify correct tool usage and response quality using LangSmith for tracking.

Running Tests with run_all_tests.py

python tests/run_all_tests.py

Test Results

Test results are logged to LangSmith under the project name specified in your .env file (LANGSMITH_PROJECT). This provides:

• Visual inspection of agent traces
• Detailed evaluation metrics
• Comparison of different agent implementations

Available Test Implementations

The available implementations for testing are:

• email_assistant - Basic email assistant

Testing Notebooks

You can also run tests to verify all notebooks execute without errors:

# Run all notebook tests
python tests/test_notebooks.py

# Or run via pytest
pytest tests/test_notebooks.py -v

Future Extensions

Add LangMem to manage memories:

• Manage a collection of background memories.
• Add memory tools that can look up facts in the background memories.