How Do Agents Actually Work

A hands-on exploration of how AI coding agents actually work, built from scratch in Ruby.

This repo is inspired by Radan Skorić's Coding Agent in Ruby post and Amp's How to Build an Agent guide. We use these learnings and re-used Radan's code to build our own agent but added some additional capabilities, namely: memory, planning, and reflection.

How It Works

The agent is an interactive REPL that can read, edit, and create files, run shell commands, and reason about multi-step tasks. It is equipped with the following tools:

Tool	Description
ReadFile	Read the contents of a file
ListFiles	List files in a directory
EditFile	Edit or create a file
RunShellCommand	Execute a shell command
Remember	Save a piece of knowledge to persistent memory
Recall	Retrieve previously stored knowledge
MakePlan	Break a complex task into ordered steps
ViewPlan	View the current plan and step statuses
UpdateStep	Mark a plan step as complete or failed
Reflect	Evaluate whether an action succeeded or failed and decide what to do next

Installation

Clone the repo and install dependencies:

bundle install

Usage

This project uses OpenRouter for LLM calls. Create a .env file from the template and add your API key:

cp .env.example .env

LLM calls are made via the RubyLLM gem. The default model is qwen/qwen3-coder, configured in run.rb. You can swap it for any model supported by RubyLLM — see the full list here.

To start the agent:

ruby run.rb

You'll get an interactive prompt where you can chat with the agent. Type exit to close the session.

Contributing

Pull requests are always welcome.

License

MIT