{"id":30668202,"url":"https://github.com/langchain-ai/agents-from-scratch","last_synced_at":"2025-08-31T23:34:11.124Z","repository":{"id":292054692,"uuid":"958189434","full_name":"langchain-ai/agents-from-scratch","owner":"langchain-ai","description":"Build an email assistant with human-in-the-loop and memory","archived":false,"fork":false,"pushed_at":"2025-07-27T15:28:12.000Z","size":24087,"stargazers_count":1049,"open_issues_count":6,"forks_count":193,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-07-27T17:37:48.743Z","etag":null,"topics":["agents","memory"],"latest_commit_sha":null,"homepage":"https://academy.langchain.com/courses/ambient-agents","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/langchain-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-31T19:40:08.000Z","updated_at":"2025-07-27T17:16:19.000Z","dependencies_parsed_at":"2025-06-27T15:39:06.852Z","dependency_job_id":null,"html_url":"https://github.com/langchain-ai/agents-from-scratch","commit_stats":null,"previous_names":["langchain-ai/agents-from-scratch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/langchain-ai/agents-from-scratch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langchain-ai%2Fagents-from-scratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langchain-ai%2Fagents-from-scratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langchain-ai%2Fagents-from-scratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langchain-ai%2Fagents-from-scratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/langchain-ai","download_url":"https://codeload.github.com/langchain-ai/agents-from-scratch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langchain-ai%2Fagents-from-scratch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273053187,"owners_count":25037359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","memory"],"created_at":"2025-08-31T23:34:10.687Z","updated_at":"2025-08-31T23:34:11.112Z","avatar_url":"https://github.com/langchain-ai.png","language":"Jupyter Notebook","funding_links":[],"categories":["Tooling \u0026 Services"],"sub_categories":["Specialized Tools"],"readme":"# Agents From Scratch \n\nThe repo is a guide to building agents from scratch. It builds up to an [\"ambient\"](https://blog.langchain.dev/introducing-ambient-agents/) 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. \n\n![overview](notebooks/img/overview.png)\n\n## Environment Setup \n\n### Python Version\n\n* Ensure you're using Python 3.11 or later. \n* This version is required for optimal compatibility with LangGraph. \n\n```shell\npython3 --version\n```\n\n### API Keys\n\n* If you don't have an OpenAI API key, you can sign up [here](https://openai.com/index/openai-api/).\n* Sign up for LangSmith [here](https://smith.langchain.com/).\n* Generate a LangSmith API key.\n\n### Set Environment Variables\n\n* Create a `.env` file in the root directory:\n```shell\n# Copy the .env.example file to .env\ncp .env.example .env\n```\n\n* Edit the `.env` file with the following:\n```shell\nLANGSMITH_API_KEY=your_langsmith_api_key\nLANGSMITH_TRACING=true\nLANGSMITH_PROJECT=\"interrupt-workshop\"\nOPENAI_API_KEY=your_openai_api_key\n```\n\n* You can also set the environment variables in your terminal:\n```shell\nexport LANGSMITH_API_KEY=your_langsmith_api_key\nexport LANGSMITH_TRACING=true\nexport OPENAI_API_KEY=your_openai_api_key\n```\n\n### Package Installation\n\n**Recommended: Using uv (faster and more reliable)**\n\n```shell\n# Install uv if you haven't already\npip install uv\n\n# Install the package with development dependencies\nuv sync --extra dev\n\n# Activate the virtual environment\nsource .venv/bin/activate\n```\n\n**Alternative: Using pip**\n\n```shell\n$ python3 -m venv .venv\n$ source .venv/bin/activate\n# Ensure you have a recent version of pip (required for editable installs with pyproject.toml)\n$ python3 -m pip install --upgrade pip\n# Install the package in editable mode\n$ pip install -e .\n```\n\n\u003e **⚠️ 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 ...`\n\n## Structure \n\nThe repo is organized into the 4 sections, with a notebook for each and accompanying code in the `src/email_assistant` directory.\n\n### Preface: LangGraph 101\nFor a brief introduction to LangGraph and some of the concepts used in this repo, see the [LangGraph 101 notebook](notebooks/langgraph_101.ipynb). This notebook explains the basics of chat models, tool calling, agents vs workflows, LangGraph nodes / edges / memory, and LangGraph Studio.\n\n### Building an agent \n* Notebook: [notebooks/agent.ipynb](/notebooks/agent.ipynb)\n* Code: [src/email_assistant/email_assistant.py](/src/email_assistant/email_assistant.py)\n\n![overview-agent](notebooks/img/overview_agent.png)\n\nThis 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 the email response. You can see the linked code for the full implementation in `src/email_assistant/email_assistant.py`.\n\n![Screenshot 2025-04-04 at 4 06 18 PM](notebooks/img/studio.png)\n\n### Evaluation \n* Notebook: [notebooks/evaluation.ipynb](/notebooks/evaluation.ipynb)\n\n![overview-eval](notebooks/img/overview_eval.png)\n\nThis notebook introduces evaluation with an email dataset in [eval/email_dataset.py](/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.\n\n![Screenshot 2025-04-08 at 8 07 48 PM](notebooks/img/eval.png)\n\n### Human-in-the-loop \n* Notebook: [notebooks/hitl.ipynb](/notebooks/hitl.ipynb)\n* Code: [src/email_assistant/email_assistant_hitl.py](/src/email_assistant/email_assistant_hitl.py)\n\n![overview-hitl](notebooks/img/overview_hitl.png)\n\nThis 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](https://github.com/langchain-ai/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](/src/email_assistant/email_assistant_hitl.py).\n\n![Agent Inbox showing email threads](notebooks/img/agent-inbox.png)\n\n### Memory  \n* Notebook: [notebooks/memory.ipynb](/notebooks/memory.ipynb)\n* Code: [src/email_assistant/email_assistant_hitl_memory.py](/src/email_assistant/email_assistant_hitl_memory.py)\n\n![overview-memory](notebooks/img/overview_memory.png)  \n\nThis 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](/src/email_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 linked code for the full implementation in [src/email_assistant/email_assistant_hitl_memory.py](/src/email_assistant/email_assistant_hitl_memory.py).\n\n## Connecting to APIs  \n\nThe above notebooks using mock email and calendar tools. \n\n### Gmail Integration and Deployment\n\nSet up Google API credentials following the instructions in [Gmail Tools README](src/email_assistant/tools/gmail/README.md).\n\nThe README also explains how to deploy the graph to LangGraph Platform.\n\nThe full implementation of the Gmail integration is in [src/email_assistant/email_assistant_hitl_memory_gmail.py](/src/email_assistant/email_assistant_hitl_memory_gmail.py).\n\n## Running Tests\n\nThe repository includes an automated test suite to evaluate the email assistant. \n\nTests verify correct tool usage and response quality using LangSmith for tracking.\n\n### Running Tests with [run_all_tests.py](/tests/run_all_tests.py)\n\n```shell\npython tests/run_all_tests.py\n```\n\n### Test Results\n\nTest results are logged to LangSmith under the project name specified in your `.env` file (`LANGSMITH_PROJECT`). This provides:\n- Visual inspection of agent traces\n- Detailed evaluation metrics\n- Comparison of different agent implementations\n\n### Available Test Implementations\n\nThe available implementations for testing are:\n- `email_assistant` - Basic email assistant\n\n### Testing Notebooks\n\nYou can also run tests to verify all notebooks execute without errors:\n\n```shell\n# Run all notebook tests\npython tests/test_notebooks.py\n\n# Or run via pytest\npytest tests/test_notebooks.py -v\n```\n\n## Future Extensions\n\nAdd [LangMem](https://langchain-ai.github.io/langmem/) to manage memories:\n* Manage a collection of background memories. \n* Add memory tools that can look up facts in the background memories. \n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangchain-ai%2Fagents-from-scratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flangchain-ai%2Fagents-from-scratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangchain-ai%2Fagents-from-scratch/lists"}