agentpath-kit

อ่านภาษาไทย

agentpath

Learn how AI agents actually work by building a real one, from a single LLM call to a full agent harness.

Who this is for

You can program a little. You have never built anything with a language model, or you have used one through a framework and never understood what it was doing underneath. You do not need to know any machine learning. There is no maths in the 24 lessons. The two optional tracks either side of them are where the numbers live, and both can be skipped.

Why this exists

There are many tutorials that show you an agent loop. Almost all of them stop there. The tools people actually use every day, such as Claude Code and OpenHands, are not agent loops. They are harnesses, which means an agent loop surrounded by permission checks, saved sessions, context management, error recovery and a plugin protocol. Almost nobody teaches you to build that part.

This course goes all the way. You start by sending one HTTP request to a model and you finish with a harness you could actually use.

Every chapter also has a Thai version, which is rare for material at this depth.

What you will build

All four parts are finished, so the course is complete at 24 chapters.

If you do not yet know what a token is, there is a foundations track that comes before lesson 01. Seven short chapters, from text as bytes to the chat template, each with code you can run without an API key. It lives in foundations/ and in part 0 of the book.

And after lesson 23 there is a training track, part 4 of the book, for the reader who wants to fine tune and serve a model of their own. Five chapters, dataset engineering, LoRA, quantization, preference tuning with DPO, and the arithmetic of serving. Three of the five, LoRA, quantization and DPO, have a numpy demo on the foundations grid that runs anywhere and a real script with transformers, peft and trl that needs a GPU. The dataset and serving chapters are plain Python at both layers. It lives in training/.

Quickstart

Install uv, which is the Python installer and environment manager this course uses.

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows use PowerShell instead.

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then clone the repository and open the first chapter.

git clone https://github.com/Patchanon04/agentpath.git
cd agentpath

Now read lessons/00-setup/README.md. It walks you through choosing where your model runs, which can be free and local if you want, and setting the three environment variables every lesson uses to reach a model.

The lessons

Using the finished framework

Everything the course builds also ships as a package, so you can install the finished version and read it as a reference.

pip install agentpath-kit

The distribution is called agentpath-kit and the package it installs is called agentpath, so you install one name and import the other. That is not a typo. PyPI refused the bare name because an abandoned package called agent_path is close enough to it to be confusing, and splitting the two names is the ordinary answer, the same one that has you install scikit-learn and import sklearn. Installing plain agentpath gets you somebody else's empty template, so the hyphen matters.

export AGENTPATH_BASE_URL=http://localhost:11434/v1
export AGENTPATH_MODEL=qwen3
agentpath chat

The command now has four subcommands. chat is an interactive session, run does one task and exits, resume carries on from a session you saved earlier, and eval runs a file of tasks and reports which ones passed. An MCP server can be connected with --mcp, so the agent can use tools you did not write.

Using it as a library

The command line is one caller among several. run is a generator that yields events as they happen, so the loop below is the whole integration.

import os

from agentpath import Agent, OpenAICompatProvider, TextDelta, TurnDone, file_tools
from agentpath.tools.base import ToolRegistry

agent = Agent(
    provider=OpenAICompatProvider(),
    tools=ToolRegistry(file_tools(os.getcwd())),
)

for event in agent.run("Summarise what this project does, in two sentences."):
    if isinstance(event, TextDelta):
        print(event.text, end="", flush=True)
    elif isinstance(event, TurnDone):
        print()

agent.run yields four kinds of event. TextDelta is a piece of the reply as it arrives, ToolCallRequest says a tool is about to run, ToolResult carries what it returned, and TurnDone means the turn is over. Ignoring an event you do not care about is the normal thing to do, which is why the loop above only names two of them.

An Agent built with no permissions approves every tool call, and file_tools includes write_file and edit_file. Point the example at a folder you do not mind changing, or pass Permissions(ask=ask_in_terminal) to be asked first.

Everything above is also importable from the module it lives in, and the deeper path is the better one to read. from agentpath.tools.base import ToolRegistry tells you where a thing is, and the chapters build the layout in that order for a reason.

The book

The chapters teach you to build it. There is also a book that explains why it is built that way, and how to think when you want to design your own. It is written in Thai, with the technical terms kept in English.

book/ has twenty eight chapters in five parts, numbered 0 to 4. Part 0 is the seven foundations chapters, from text as bytes to the chat template, each with a folder of code in foundations/. Part 1 is seven chapters of the theory behind the course. Part 2 is four chapters about taking an idea and working out what to build, with a long worked example of a LINE health assistant and three shorter ones that reach different answers. Part 3 is five chapters that walk through the finished code in src/agentpath/ piece by piece. Part 4 is five chapters on fine tuning and serving a model of your own, each with a folder of code in training/.

How this repository is laid out

lessons/ holds one folder per chapter. Each folder is self contained, so you can open any chapter and run its code without having done the others. The code is duplicated between chapters on purpose, because a course where chapter four silently depends on an edit you made in chapter two is a course people abandon.

foundations/ holds seven folders of code for the reader who does not yet know what a token is. They come before lesson 01 and need no API key. Text to bytes, a tokenizer from nothing, a language model that counts, one that learns, word vectors, attention on four tokens, and the chat template. Each folder has a short README in both languages and the full chapter is in the book, in Thai. This and the training track are the two places in the course that use numpy.

training/ holds five folders for part 4 of the book, fine tuning and serving. Each has a check that CI runs. LoRA, quantization and DPO also have a numpy demo on the same grid the foundations trained, and a real script that needs a GPU and the training extra, which CI does not run. Data cleaning and the arithmetic that says what a card can serve are plain Python with no GPU at either layer.

src/agentpath/ holds the finished framework, which is the same ideas written once and properly, with tests.

ci/ holds the script that runs every chapter check, the prose style check, a check that a technical term is not explained two different ways in the book and in a lesson, and a check for Thai that has run on without the space that marks where one thought ends. The fake model server it runs against lives in src/agentpath/testing/.

docs/ holds the design document, the implementation plans and the topic ideas kept back for a second version.

Running the checks yourself

Every chapter has a check.py that proves the code you wrote actually works. You can run all of them at once against a fake model server, which costs nothing and needs no API key.

uv pip install -e ".[dev,foundations]"
python ci/run_lessons.py

The foundations extra is numpy, which the foundations and training checks import. The 24 lesson checks need only httpx. This is the same script and the same install line the project runs in continuous integration, so if it passes for you it passes for everyone.

Contributing

Issues and pull requests are welcome. Two rules matter more than the rest.

The course is frozen at 24 chapters. New topic ideas belong in docs/v2-ideas.md, not in a new chapter. If you want to add a chapter you have to argue for removing one. The two tracks either side of the course are frozen by the same rule, the foundations at seven chapters because they sit before lesson 01, and the training track at five because it sits after lesson 23 and teaches a different thing, the model rather than the harness.

Prose has a house style. No em dash, no emoji, and no colon in ordinary sentences. A check in continuous integration enforces all three, and relaxes only the colon rule for the working notes in docs/plans/ and docs/specs/.

License

MIT. See LICENSE.