Simple Agent

Warning

Simple agent can run commands on your machine. Be aware of the potential for it to make modifications to your system.

Note

Simple Agent is still a work in progress! There will likely be bugs and missing features, if you encounter them, please leave an issue!

This is an attempt to make a bare-bones, very simple agent based on LLMs and other technologies. The goal is to have a simple agent for use in various purposes:

1. Experimentation and benchmarking
2. Understanding and learning myself
3. Idk but having three points sounds more solid

How it works

So put simply, the agent works on a constant loop, involving three main steps:

1. Perception
2. Inference
3. Action

The perception stage is characterized by a combination of 1. environmental analysis, 2. memory recall, and 3. agency or will towards a goal. The inference stage is the call to the API, where the model (right now only OpenAI models) is given the perception to reason about. The action stage is where the agent takes the output of the model, such as tool calls, and actually runs them.

Prerequisites

To make Simple Agent work well, you'll need to meet the following prerequisites:

• Python 3.11
• Access to an LLM (Anthropic or OpenAI only by default (for now))

How to use it

This repository is a fairly straightforward Python project. You will need to have Python installed, and I used Python 3.10 on MacOS, so I know that this version worked. If you use a different version, or use a platform other than MacOS and notice bugs, please let me know in an issue. You should be able to clone the repository, install dependencies (in a virtual environment if you choose), fill in the .env file, and run simple-agent.py to see it work.

1. Start by cloning the repository:

   git clone https://github.com/AidanTilgner/Simple-Agent.git

2. Then, navigate into the directory:

cd Simple-Agent

3a. (Optional) If you choose to use a virtual environment, you can instantiate it like so:

python -m venv venv

Then, activate the virtual environment:

source ./venv/bin/activate

3b. Install the dependencies:

pip install -r requirements.txt

4. Copy the .env.example file to .env and fill in the necessary information. You will need an OpenAI API key, which you can get from the OpenAI website.

(on MacOS or Linux):

cp .env.example .env

5. Run the program:

python simple-agent.py

6. To exit the program, you can use Ctrl+C, or type "exit".

That's it! You should see the agent start up, and you can ask it to do things using it's tools.

Advanced Usage

You might want to extend or enhance the functionality of the tool, and if you do I'd love to hear how it goes! Or even submit a PR if you think it should be a default.

Modifying Prompts You can modify prompts in the agent.py, agency.py, memory.py, and environment.py files. These files are where you'll find the actual programmatic generation logic for several aspects of the prompt. Things might change over time, so I'm not going to go into specifics here. But you might find that you can gain further behavior by modifying these files.

The system_prompt.md file is the source of the agent's system prompt, which can be modified as well.

Using Different Models You might find that using different models is more useful. In the future, there will be additional configuration options that will allow you to use models of your choice. For now, you can take a look at the openai.py and llm.py files for reference. Essentially, the agent can use any model through the LLM interface, so you can implement custom models that way. The main logic for instantiating these are in the main.py file, where the default is OpenAI's GPT-4o.

Adding Tools The tools/ directory is where you'll find tools. Each tool must fit the Tool class, in order to be used by the agent. Check out toolbox.py to see a current list of included tools, and how they are used. If you want to add a tool, you can use the write_file.py, read_file.py, and send_message_to_user.py tools as a reference. More tools will be included in the future. This is another area where PRs are welcome.

Roles

Roles are identities which can be adopted by the agent. They are are context-dependent, and each have their own set of tools which are provided to the agent. The agent can switch between roles at any time. INCLUDED_ROLES are defined in the roles/config.py file. You can learn more about roles in the roles tutorial.

I'm still working on the roles system, bare with me. But you can see the beginnings of it in the roles/ directory. Currently these roles are supported:

• Helpful Assistant: A helpful assistant ready to take your questions and provide answers.
• Developer: A dedicated developer with specialized tools for software development, testing, and debugging.
• Researcher: A dedicated researcher with specialized tools for web research, data analysis, and documentation.

Note

To switch between roles, just ask the agent to do it. For example, you can say "I'd like some help with research...", or more specifically "I'd like to switch to the researcher role." You'll see an "As a [ROLE]" message to confirm.

Adding Memory

Check out the tutorial to learn how to add memory to Simple Agent.

Roadmap

I'm looking to polish this project into a really solid framework for building agents. But it's going to need to stay as a core, rather than a full-fledged agent. To make a full-fledged agent, this should be forked.

Features

Existing Features

• Implement memory and learning through Simple Vector Store
• Allow selection of additional models
• Get better editing

Planned Features These are things that I currently plan on doing. If you have ideas for features or feadback, don't hesitate to open an issue so we can discuss it.

• "Modes" that the agent can switch into for specialized operations, with different tool layouts
• A more robust benchmarking system through Benchy

Possible Features

• A type of procedural memory
• A sort of plugin system