How to Actually Build an Agent from Scratch — Not Just Calling APIs

I’ve dug through a lot of material, either too abstract or just handing you a finished product to tweak parameters. The “why it’s designed this way” part is basically missing.

This LangChain official “Agents From Scratch” tutorial is one of the most solid introductory materials I’ve seen. On the surface, it teaches you to build an email assistant with human-in-the-loop and memory, progressing step-by-step through four main parts: Agent basics, evaluation, human-in-the-loop (HITL), and long-term memory.

Each part comes with a notebook and complete code, and the principles are fully transferable to other agent scenarios. I ran the basic setup notebook locally, and the most direct impression was how clearly it explained LangGraph’s nodes, edges, and state management.

Starting from the simplest tool calls, it gradually introduces evaluation, approval gates, and memory persistence, letting you see changes in agent behavior at each step. The final Gmail integration requires API credentials, but the entire deployment path works end-to-end.

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

This repository is a guide to building agents from scratch. It culminates in an “ambient” (https://blog.langchain.dev/introducing-ambient-agents/) agent that can manage your email with a connection to the Gmail API. It’s structured into four sections, each with a notebook and accompanying code in the src/email_assistant directory. These sections build from the basics of agents, to agent evaluation, to human-in-the-loop, and finally to memory. They all come together in a deployable agent, 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 (https://openai.com/index/openai-api/).
• Sign up for LangSmith here (https://smith.langchain.com/).
• 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 the import name email_assistant, allowing you to import it from anywhere with from email_assistant import ....

Structure

The repository is organized into the four 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 repository, 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 (https://langchain-ai.github.io/langgraph/tutorials/workflows/) with an agent that handles email responses. You can see the full implementation in the linked code at src/email_assistant/email_assistant.py.

Evaluation

• Notebook: notebooks/evaluation.ipynb

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

Human-in-the-Loop (HITL)

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

This notebook shows how to add human-in-the-loop (HITL), allowing users to review specific tool calls (e.g., send email, schedule meeting). For this, we use Agent Inbox (https://github.com/langchain-ai/agent-inbox) as the interface. You can see the full implementation in the linked code at 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 (https://langchain-ai.github.io/langgraph/concepts/memory/#long-term-memory) to persist memories. You can see the full implementation in the linked code at src/email_assistant/email_assistant_hitl_memory.py.

Connecting to APIs

The notebooks above use mock email and calendar tools.

Gmail Integration and Deployment

Set up Google API credentials following the instructions in the 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 (https://langchain-ai.github.io/langmem/) to manage memories:

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