agent-harness

Companion code for the ruxu.dev blog post series on building a simple AI agent harness from scratch.

Blog Post Series

1. Build a Basic AI Agent: A minimal conversational agent with a message loop, powered by a local model via Ollama.
2. Build an AI Agent with Tools: Extends the agent with a tool registry so the LLM can read/write files, search the filesystem, run shell commands, and fetch web pages.

Structure

simple-agent/          # Part 1: bare-bones agent loop
  agent.py

agent-with-tools/      # Part 2: agent with tool-calling support
  agent.py
  tools/
    filesystem.py      # read, write, search files
    shell.py           # run shell commands
    web.py             # fetch web pages
    registry.py        # tool registry & schemas

Requirements

• Python 3.12+
• uv (recommended) or pip

Setup

uv sync

You can also change the current Ollama agent running gemma4 for any model of your choice.

simple-agent

uv run simple-agent/agent.py

agent-with-tools

uv run agent-with-tools/agent.py

Type \exit to quit either agent.