74 lines
2.5 KiB
Markdown
74 lines
2.5 KiB
Markdown
# agent-harness
|
|
|
|
Companion code for the [ruxu.dev](https://www.ruxu.dev) blog post series on building a simple AI agent harness from scratch.
|
|
|
|
## Blog Post Series
|
|
|
|
1. [Build a Basic AI Agent](https://www.ruxu.dev/articles/ai/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](https://www.ruxu.dev/articles/ai/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.
|
|
3. `agent-memory/`: Adds durable agent and user memory plus searchable, resumable sessions to the sandboxed agent.
|
|
4. `agent-sessions/`: Adds context compaction, session lifecycle controls, branching, exports, and crash recovery. See [usage](agent-sessions/README.md).
|
|
|
|
## 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
|
|
agent-memory/ # Persistent memory and session continuation
|
|
agent.py
|
|
memory.py # File-backed notes and conversation sessions
|
|
agent-sessions/ # Session management built on agent-memory
|
|
agent.py
|
|
sessions.py # Lifecycle, locking, recovery and lossless compaction
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3.12+
|
|
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
You can also change the current Ollama agent running gemma4 for any model of your choice.
|
|
|
|
### simple-agent
|
|
|
|
|
|
```bash
|
|
uv run simple-agent/agent.py
|
|
```
|
|
|
|
### agent-with-tools
|
|
|
|
```bash
|
|
uv run agent-with-tools/agent.py
|
|
```
|
|
|
|
Type `\exit` to quit either agent.
|
|
|
|
### agent-memory
|
|
|
|
```bash
|
|
uv run agent-memory/agent.py
|
|
```
|
|
|
|
Memory is stored outside the repository by default in `~/.agent-harness/memory`:
|
|
|
|
- The agent reads and appends durable `personal` notes (lessons and environment facts) and `user` notes (preferences) through host-side memory tools.
|
|
- Each conversation is saved as a transcript and should receive an LLM-written summary; a fallback summary is generated on exit if needed.
|
|
- Type `\sessions` during a conversation, or run `uv run agent-memory/agent.py --list-sessions`, to list saved sessions.
|
|
- Resume a conversation with `uv run agent-memory/agent.py --resume SESSION_ID`.
|
|
- Change the storage location with `--memory-dir PATH`.
|