Agent Craft: a 15-module Python course that builds an AI agent from LLM calls to MCP

What Agent Craft actually solves, and for whom

The README states the target reader directly: people who are stuck at "understanding the concepts but unable to build" or who can call an API but do not understand the mechanism underneath. That is a narrow and honest audience. Agent Craft is not a framework you import into production code. It is a numbered curriculum, currently 15 modules, where each module lives in its own top-level directory (m01_agent_introduction through m13_streamlit) and can be run on its own.

The progression is deliberate. Modules 01 and 02 cover environment setup and plain LLM calls. Module 03 introduces Function Calling so the model can reach outside itself. Modules 04 and 05 move into LangChain, first the six core pieces (LLM, Prompt, Chain, Memory) and then Agents, the @tool decorator, the ReAct loop and streaming. Modules 06 and 07 cover RAG twice: first with FAISS and an LCEL chain, then with Chroma persistence, a reranker, and RAG packaged as a tool. Modules 08 and 09 handle LangGraph, starting with its three core elements and LangSmith tracing, then Human-in-the-Loop, Graph-as-a-Tool, and multi-agent orchestration. Modules 10 and 11 are MCP, server side then client side. Module 12 covers the Agents SDK and the Swarm pattern with handoffs. Module 13 is Streamlit, building a chat interface with async event streaming and session persistence.

The repository also ships config.py and embeddings.py at the top level, which the setup.py declares as py_modules alongside the package. That layout tells you the intent: those two files are shared helpers the module directories import, not a published library surface.

How the modules are wired together

The mechanism is directory-per-lesson plus a shared root. There is no package namespace like agent_craft.llm; setup.py registers the name agent-craft at version 0.1, finds packages, and lists config and embeddings as loose modules. If you pip install from this repository you get those two helpers and whatever find_packages picks up, which is not the point of the project. The point is that you clone it, open a module directory, and run the script there.

State and configuration flow through the environment. The .env.example file names four variables: OPENAI_API_KEY for the model, LANGCHAIN_API_KEY for LangSmith tracing of LangGraph flows, AMAP_MAPS_API_KEY for the AMap (Gaode) map service used when debugging the MCP modules, and an optional CHATGPT_API_KEY described as being for connecting the Agents SDK to Smith tracing. The comments in that file are explicit that you do not need the LangSmith key until you reach the LangGraph modules and do not need the AMap key until you reach MCP.

That dependency order is the architecture. Each layer assumes the previous one. Module 07's stated goal is to integrate the LangChain six modules covered in modules 04 through 07. Module 09 combines Human-in-the-Loop, Graph-as-a-Tool and multi-agent orchestration into one complex agent. Module 13's Streamlit app is described as a customer-service cockpit, which only makes sense once you have an agent to put behind it. The README also links every module to a CSDN blog post explaining the design reasoning, so the code and the explanation are separate artifacts that are meant to be read together.

Installing Agent Craft and running your first module

The README does not give a single install command, so the practical route is to clone the repository, create a virtual environment, and install requirements.txt. The pinned set is large: langchain 1.2.0, langgraph 1.0.5, mcp 1.25.0, langchain_mcp_adapters 0.2.1, openai 2.14.0, streamlit 1.52.2, faiss-cpu, sentence-transformers, and more. Pin conflicts are the most likely reason a first attempt fails, so install into a clean environment rather than a shared one.

git clone https://github.com/Annyfee/agent-craft.git
cd agent-craft
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Next, copy the example environment file and fill in the key for the module you are starting with. For module 01 and 02 that means OPENAI_API_KEY only. The other three variables can stay as placeholders until you reach the LangGraph and MCP sections.

cp .env.example .env

# .env
OPENAI_API_KEY=your_openai_api_key

After that, change into the first module directory and run its script. The README describes module 01 as environment dependencies, API key configuration, and a minimal runnable agent, so the entry point is inside m01_agent_introduction rather than at the repository root. The README does not name the exact filename, so list the directory before running anything.

cd m01_agent_introduction
ls
python <the script shown in the listing>

What you should see is a model response printed to the console. If you get an authentication error, the key in .env was not picked up; the project depends on python-dotenv 1.2.1, so the file needs to be in the location the module expects.

Where Agent Craft stops being the right tool

The most concrete limitation is that the curriculum is unfinished. The module table marks 14 (the comprehensive project combining LangGraph, RAG, MCP, Streamlit and Vercel) as being written, and 15 (deployment with Ollama, LM Studio and LangServe) as in progress. If your goal is to see a complete deployed agent, the repository does not currently take you there. It stops at module 13.

The second limitation is dependency weight. requirements.txt pins langchain 1.2.0 and langgraph 1.0.5 alongside openai 2.14.0 and mcp 1.25.0. Those are fast-moving projects. A tutorial repository that pins them exactly will, over time, produce install failures on newer Python versions even though the teaching code is still correct. There is no lockfile beyond the requirements file and no version matrix in the README.

The third is that this is teaching code, not an API. The README's own framing is that it does not reinvent wheels but does not stop at calling a framework either. That means the modules deliberately show you the internals of a ReAct loop rather than hiding it. If you want a supported agent runtime with a stability guarantee, this repository gives you neither a release history (no releases are listed) nor a changelog. The last push was on 2026-08-17, so the project is recent, but recency of commits is not the same as a maintenance commitment, and the README does not document a deprecation or upgrade policy.

Agent Craft versus LangChain's own tutorials

The obvious alternative is the official LangChain and LangGraph documentation, which also provides runnable examples and conceptual guides. The difference in approach is scope and ordering. LangChain's docs are organized around the library's own surface: this page for chains, that page for agents, another for retrievers. You assemble your own path, and you choose when to move on.

Agent Craft imposes a sequence and a difficulty rating. The module table assigns stars from one to five, and the order is fixed: you meet Function Calling in module 03 before you meet LangChain Agents in module 05, and you meet RAG with FAISS in module 06 before Chroma and reranking in module 07. That ordering is the product. It also means the repository carries content that the official docs do not, such as the MCP server and client modules built on FastMCP and langchain-mcp-adapters, and the Swarm handoff pattern in module 12.

The trade-off is freshness. Official documentation tracks library releases; a pinned tutorial repository tracks the author's writing schedule. The README's paired CSDN blog posts are where the reasoning lives, and they are in Chinese, so an English-speaking reader gets the code and the comments but not the full explanation unless they read the blog.

Licence, upgrade cost and what maintenance looks like

The repository is MIT licensed. For a teaching project that is the permissive choice: you can copy module code into your own work, including commercial work, provided you keep the copyright notice. Note that MIT covers the code in this repository, not the dependencies it pulls in. langchain, langgraph, mcp, streamlit and the rest carry their own licences, and nothing in the README addresses that distinction. This is a description of the licence file, not legal advice.

Upgrade cost is the real ongoing expense. Because requirements.txt pins exact versions for most packages, moving to a newer LangChain or LangGraph means editing those pins and then checking whether the module code still runs. The README does not document a migration path, a supported Python version, or a compatibility table. The GitHub Actions workflow referenced by the CI badge is the only automated signal the repository advertises, and the README does not describe what it runs.

For a learner, that is acceptable. You are reading the code, not depending on it. For anyone considering vendoring a module into a product, the missing pieces are a changelog, a release, and a stated support window. None of them appear in the repository.

Editorial conclusion

Adopt Agent Craft if you already write Python and want a guided sequence from a raw OpenAI call through Function Calling, RAG, LangGraph and MCP, with a blog post explaining each step. Skip it if you need a supported library, a stable API, or a finished capstone: module 14 and module 15 are still marked as being written. Before committing time, open m01_agent_introduction and m10_mcp_basics, check that requirements.txt resolves on your Python version, and confirm whether the MCP modules need the AMAP_MAPS_API_KEY that .env.example lists.

Frequently asked questions

Official sources

1. Annyfee/agent-craft on GitHub
2. Issues
3. License: MIT
4. Project website
5. README