Metadata-Version: 2.5
Name: agentpath-kit
Version: 1.0.6
Summary: Learn how AI agents actually work by building a real one, from a single LLM call to a full agent harness.
Project-URL: Homepage, https://github.com/Patchanon04/agentpath
Project-URL: Changelog, https://github.com/Patchanon04/agentpath/blob/main/CHANGELOG.md
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

[อ่านภาษาไทย](README.th.md)

# 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
this course.

## 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

| Part | What it adds | Status |
|------|--------------|--------|
| 1 Foundations | An agent that streams, calls tools, loops until the work is done, and can switch model providers | Available now |
| 2 Real Tools | File reading and editing, running shell commands, searching code, and a small coding agent that works | Available now |
| 3 The Harness | Permissions, saved sessions, context management, token economy, retrieval, error recovery | Available now |
| 4 Advanced | An MCP client, subagents, multi agent patterns, evaluation and model choice | Available now |

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

## Quickstart

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

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

On Windows use PowerShell instead.

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

Then clone the repository and open the first chapter.

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

Now read [lessons/00-setup/README.md](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 the whole course uses.

## The lessons

| Lesson | What you build |
|--------|----------------|
| [00 setup](lessons/00-setup/) | A working environment and a model you can reach |
| [01 first LLM call](lessons/01-first-llm-call/) | One HTTP request to a model, with nothing hiding the wire |
| [02 conversation loop](lessons/02-conversation-loop/) | A chat that remembers, and the discovery that models remember nothing |
| [03 tool calling](lessons/03-tool-calling/) | The model asks for a function and you decide whether to run it |
| [04 agent loop](lessons/04-agent-loop/) | Your first real agent, looping until the work is done |
| [05 streaming](lessons/05-streaming/) | Answers that appear as they are written, including the hard part where tool arguments arrive in fragments |
| [06 provider abstraction](lessons/06-provider-abstraction/) | One agent loop that works with two completely different APIs |
| [07 file tools](lessons/07-file-tools/) | Reading and editing real files, with one gate deciding what may be touched |
| [08 shell tool](lessons/08-shell-tool/) | Running commands, and asking a person first |
| [09 search tools](lessons/09-search-tools/) | Finding files and text, and why this beats a vector database for code |
| [10 anatomy of a prompt](lessons/10-anatomy-of-a-prompt/) | The three places your words reach the model, including the one everyone forgets |
| [11 mini coding agent](lessons/11-mini-coding-agent/) | Everything wired together into an agent that fixes a real bug |
| [12 permissions](lessons/12-permissions/) | A gate that remembers your answer, so it does not train you to stop reading it |
| [13 sessions](lessons/13-sessions/) | The conversation on disk, which is also the best debugging tool you have |
| [14 context management](lessons/14-context-management/) | Trimming a conversation without stranding a tool result, which is the trap everyone hits |
| [15 token economy](lessons/15-token-economy/) | Why the same conversation costs more every turn, and what actually reduces it |
| [16 retrieval](lessons/16-retrieval/) | Four questions that tell you whether you need RAG at all, and usually you do not |
| [17 errors and retries](lessons/17-errors-and-retries/) | Surviving rate limits, stuck models, and a person who changes their mind |
| [18 the harness](lessons/18-the-harness/) | Everything wired together into a tool you could actually use |
| [19 MCP client](lessons/19-mcp-client/) | Using tools somebody else wrote, and what they cost you on every request |
| [20 subagents](lessons/20-subagents/) | Delegating a job to another agent, and the stale view that comes with it |
| [21 multi agent](lessons/21-multi-agent/) | Running several agents at once without their output turning to noise |
| [22 evals](lessons/22-evals/) | Measuring whether a change helped, and choosing a model by evidence |
| [23 ship it](lessons/23-ship-it/) | Packaging it, publishing it, and what to build next |

## 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.

```bash
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.

```bash
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.

```python
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.

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/](book/) has eleven chapters in two parts. The first seven are the
theory behind the course. The last four are 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.

## 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.

`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 and the prose style check.
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.

```bash
uv pip install -e ".[dev]"
python ci/run_lessons.py
```

This is the same script 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](docs/v2-ideas.md), not in a new chapter. If you want to add a
chapter you have to argue for removing one.

Prose has a house style. No em dash, no emoji, and no colon in ordinary
sentences. A check in continuous integration enforces the first two.

## License

MIT. See [LICENSE](LICENSE).
