rulyone/simple-react-agent

This project is a small, deliberately hand-written example of a ReAct agent that runs entirely on your own computer. A ReAct agent is a pattern where a language model alternates between thinking out loud, taking an action (like calling a tool), and reading the result, until it reaches a final answer. The author wrote it as a teaching exercise: four short Python files, no third-party agent framework hiding the loop. Every action is parsed out of the model's text reply and dispatched by hand. It runs on Ollama, which is a local program that hosts language models on your machine, paired with Llama 3.2 3B, a small open model that takes about 2 GB of disk space. There is no API key, no paid subscription, and no cloud calls for the model itself. You install Ollama, pull the model once, set up a Python virtual environment, install two dependencies (httpx and ddgs), and run a command-line REPL that lets you chat with the agent. The code is split across four files. llm.py is a thin wrapper that sends chat messages to Ollama and returns text. tools.py defines the two available tools: a calculator that safely evaluates math expressions, and a web search backed by DuckDuckGo, plus a dispatch helper. react.py contains the system prompt, the parser that pulls actions out of the model's reply, and the inner loop that runs one user turn through several thought-action-observation steps. repl.py is the outer multi-turn loop with simple slash commands like /clear and /history. The README explains the ideas the project is meant to teach: chat message roles (system, user, assistant), using stop sequences to make sure the model writes one action at a time, the fact that the language model is stateless so the full conversation history is resent every turn, the difference between the outer conversation loop and the inner reasoning loop, and how new tools can be added by putting one entry in a Python dictionary. There is a sample session showing the agent searching for the year of the last Chilean presidential election and then doing arithmetic on the answer. The README also covers tweaks like swapping in a smaller or larger Ollama model, raising the maximum number of reasoning steps, and common troubleshooting cases such as Ollama not being started or smaller models drifting away from the expected reply format.