langchain-ai/agents-from-scratch: An Email Agent Tutorial That Ends in Gmail
Build an email assistant with human-in-the-loop and memory
At a glance
- What is it?
- The repository is a four-notebook LangGraph course that builds an email assistant from a basic agent to human-in-the-loop review and long-term memory, with a Gmail deployment path at the end. It is teaching material, not a library, and the editable install is the step most people will skip.
- Who is it for?
- Adopt it if you want a worked LangGraph reference for an email agent and are willing to read notebooks rather than import a library. Skip it if you need a supported package with releases, or if you want a framework-independent agent.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 35 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What agents-from-scratch actually is, and who it is written for
This repository is a guide, and the README says so in its first line. It builds up to what the project calls an "ambient" agent that manages email through the Gmail API. The material is split into four sections, each with a notebook and matching code under `src/email_assistant`: a basic agent, evaluation, human-in-the-loop, and memory. The preface notebook, `notebooks/langgraph_101.ipynb`, covers chat models, tool calling, agents versus workflows, LangGraph nodes, edges and memory, and LangGraph Studio.
The audience is therefore narrower than the name suggests. If you have never written a LangGraph graph, the 101 notebook is the entry point. If you already run agents in production, the value is in the middle sections: how to wire an interrupt around tool calls, and how to persist preferences in the LangGraph Store. What you will not find is a packaged library. The project name in `pyproject.toml` is `agents_from_scratch`, but the installable package is `interrupt_workshop` and the import name is `email_assistant`. That mismatch is deliberate, according to the README, but it is the first thing that will confuse a newcomer copying commands.
The four-stage build: triage, evaluation, interrupts, memory
The architecture is a progression rather than a single design. The agent notebook combines an email triage step with an agent that handles the response, and the full implementation lives in `src/email_assistant/email_assistant.py`. Triage and response are separate concerns here, which is the standard LangGraph workflow pattern the README links to.
Evaluation comes next. `eval/email_dataset.py` holds an email dataset, and the notebook runs evaluations through Pytest and the LangSmith `evaluate` API. The README names three kinds of check: LLM-as-a-judge for response quality, tool calls, and triage decisions. That is the most reusable part of the repository, because the harness does not care that the subject is email.
Human-in-the-loop adds review of specific tool calls such as sending email or scheduling a meeting. The interface is Agent Inbox, a separate repository, and the implementation is `src/email_assistant/email_assistant_hitl.py`. The memory stage persists what the assistant learns from user feedback in the LangGraph Store, in `src/email_assistant/email_assistant_hitl_memory.py`. Each stage has its own file rather than a feature flag, so you can diff two versions to see exactly what the new capability costs in code.
Installing agents-from-scratch and running the first notebook
The README requires Python 3.11 or later, and `pyproject.toml` narrows that to `>=3.11,<3.14`. Check the interpreter before anything else, because LangGraph compatibility is the stated reason for the floor.
python3 --versionYou need two API keys: one from OpenAI, one from LangSmith. The README points to signup pages for both. Copy the example environment file and fill it in. Note that the example project name is `interrupt-workshop`, and the README reuses that same string in its terminal export example.
cp .env.example .envLANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=your_openai_api_keyThe recommended install is uv. The README calls this the faster and more reliable path, and the dev extra pulls in mypy and ruff.
pip install uv
uv sync --extra dev
source .venv/bin/activateA pip fallback exists, but the README marks the editable install as required for the notebooks to work, because the package must be importable as `email_assistant` from anywhere. After activation, open the agent notebook and run the cells; the README shows the graph rendering in LangGraph Studio. For the automated suite, the single entry point is `python tests/run_all_tests.py`, and results land in LangSmith under whatever `LANGSMITH_PROJECT` you set. Notebook-level checks run with `pytest tests/test_notebooks.py -v`.
Where the tutorial stops being a tutorial: the Gmail path
Everything up to the memory notebook uses mock email and calendar tools. Gmail is a separate step. The README directs you to `src/email_assistant/tools/gmail/README.md` for Google API credentials and for deploying the graph to LangGraph Platform, and the full integration is `src/email_assistant/email_assistant_hitl_memory_gmail.py`.
That is a real boundary. The mock path is what the evaluation dataset exercises, so the numbers you see in LangSmith describe behaviour against fixtures, not against your inbox. Moving to Gmail means OAuth credentials, the `google-api-python-client`, `google-auth-oauthlib` and `google-auth-httplib2` dependencies that are already listed, and a deployment target. The top-level `langgraph.json` is the deployment descriptor, and the Gmail README is the only place the project documents the credential flow. The main README does not repeat those steps, so read both files before assuming the switch is a config change.
The limitations you should weigh before adopting it
The most concrete limitation is that this is course material. There are no releases, so there is no version to pin and no changelog to read when something breaks. The last push was on 2026-08-11, which is recent, but a repository without releases still gives you no compatibility contract. If you build on `email_assistant_hitl_memory.py`, you are copying code, not depending on a package.
The dependency floor is aggressive. `langchain`, `langchain-core`, `langchain-openai` and `langgraph` are all pinned at `>=1.0.0`, so the project assumes the 1.x line of the LangChain stack. Anyone still on 0.x will have to upgrade before the notebooks run at all.
The evaluation story also depends on a hosted service. Tests log to LangSmith, and the LLM-as-a-judge checks call OpenAI. There is no documented offline mode, and the README does not describe what happens when either key is missing or rate-limited. For a project whose selling point is teaching evaluation, that coupling is worth noting: you cannot run the harness in an air-gapped CI job as documented.
Finally, the human-in-the-loop section is not self-contained. It uses Agent Inbox as the review interface, so the workflow spans two repositories, and the README does not document rollback or what happens to an interrupted thread if the inbox is unavailable.
How it compares to a framework you install
The obvious alternative is to skip the tutorial and use LangGraph directly, since the repository is built on it and links to its documentation throughout. The difference in approach is the direction of the dependency: LangGraph is a library you import and version, while agents-from-scratch is a set of notebooks you read and copy. LangGraph gives you an API surface with release notes; this repository gives you four worked implementations of the same agent at increasing capability, which is useful precisely because you can compare `email_assistant.py` against `email_assistant_hitl_memory.py` and see what memory adds.
A second alternative is the LangGraph 101 notebook's own framing of agents versus workflows. If your task is a fixed pipeline, the triage-then-respond split here is a workflow with an agent inside it, and the README links to that distinction rather than hiding it. Choosing a full agent framework when a deterministic workflow would do is the mistake this material is best positioned to prevent.
Licence, maintenance and upgrade cost
The repository is MIT licensed, which permits commercial use and modification, but the licence covers the code in this repository only. The dependencies carry their own terms, and the Gmail integration brings in Google's client libraries and API terms. Nothing here is legal advice; check the terms of the services you connect to, particularly if you point the agent at a real mailbox.
Upgrade cost is dominated by the `>=1.0.0` floors on the LangChain packages. Because there are no releases, you cannot pin the tutorial itself, only its dependencies. The practical approach is to pin in your own `pyproject.toml` whatever versions `uv.lock` resolves to at the time you copy the code, and to treat the notebooks as a snapshot. The lockfile is committed, which helps, but it will only match the state of the repository on its last push, 2026-08-11.
Editorial conclusion
Adopt it if you want a worked LangGraph reference for an email agent and are willing to read notebooks rather than import a library. Skip it if you need a supported package with releases, or if you want a framework-independent agent. Verify first that your Python is 3.11 or later, that the editable install succeeded so `from email_assistant import ...` resolves, and that you have both an OpenAI key and a LangSmith key, because the evaluation notebooks log to LangSmith.
Frequently asked questions
What Python version does agents-from-scratch require?
The README asks for Python 3.11 or later, citing LangGraph compatibility, and pyproject.toml constrains it to >=3.11,<3.14. Check with python3 --version before installing.
Why does agents-from-scratch install a package called interrupt_workshop?
The README states the editable install is required for the notebooks and that the package is installed as interrupt_workshop with import name email_assistant. That is what allows `from email_assistant import ...` to work from anywhere.
Do I need an OpenAI key and a LangSmith key to run agents-from-scratch?
Yes. The README instructs you to sign up for both and to set OPENAI_API_KEY, LANGSMITH_API_KEY and LANGSMITH_TRACING in a .env file. Test results are logged to LangSmith under the LANGSMITH_PROJECT name.
Community notes