Local Autonomous Multi-Agent AI System

Overview

A lightweight, completely local, and air-gapped multi-agent orchestration framework. This project utilizes Python and the Ollama API to run an autonomous "Baton Pass" loop between two AI agents: a Backend Developer and a DevSecOps Security Expert.

By utilizing a shared file-based state architecture rather than complex, memory-heavy frameworks, this system is optimized to run smaller language models (e.g., qwen2.5-coder:1.5b) efficiently on low-resource hardware over a local network bridge.

The system features a Retrieval-Augmented Generation (RAG) pipeline, grounding the Security Agent in strict OWASP security guidelines to prevent infinite loops and ensure production-grade code auditing.

Architecture

The system avoids the overhead of traditional orchestration frameworks by utilizing a file-based shared memory and turn-taking protocol:

• Shared State (message_board.txt): Acts as the central context window. Agents read the history, append their generated code or critique, and step back.
• The Baton Pass (turn.txt): A synchronization mechanism. Agents run in continuous background loops, sleeping until their specific role (e.g., DEVELOPER or SECURITY) is written to this file.
• RAG Knowledge Base (security_rules.txt): The Security Agent is augmented with a local textbook of strict security policies (like the OWASP Top 10). It utilizes Chain-of-Thought (CoT) prompting to physically evaluate the Developer's code against every rule before passing or failing the build.
• Auto-Halt Mechanism: The loop runs autonomously until the code perfectly passes all security checks, at which point the system outputs an APPROVED signal and safely halts the process.
• Network Bridge: The Python scripts run on a host machine, querying an Ollama server running on a secondary machine via local IPv4, allowing distributed processing.

Prerequisites

To run this project, you will need:

• Python 3.8+ installed on the host machine.
• Ollama installed on the processing machine.
• A local language model pulled via Ollama (default: qwen2.5-coder:1.5b).

Installation and Setup

1. Clone the Repository

git clone [https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git](https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git)
cd YOUR_REPO_NAME

2. Install Dependencies

The project relies on the official OpenAI Python client (compatible with Ollama) and python-dotenv for secure environment variable management.

pip install openai python-dotenv

3. Configure the Environment

Create a .env file in the root directory. Add the local IPv4 address of the machine running the Ollama server.

LAPTOP_IP=192.168.1.xxx

4. Configure the Ollama Server

By default, Ollama only listens to localhost. To allow the host machine to send requests over the local network, you must expose the Ollama server. On the machine running Ollama, open a command prompt and run:

set OLLAMA_HOST=0.0.0.0
ollama serve

(Note: Ensure your firewall allows inbound TCP connections on port 11434).

Usage

Starting a Task

1. Open message_board.txt and clear any previous content.
2. Write your initial prompt at the top of the file (e.g., "Write a Python script that logs a user into a database using an email and password.").
3. Save and close the file.

Starting the Engine

1. Open turn.txt.
2. Clear the file, type the word DEVELOPER, and save it.
3. Double-click the Start_Agents.bat file.

This batch script will automatically spawn two isolated terminal instances. The Developer agent will read the prompt, generate the code, write it to the message board, and pass the baton to the Security agent, initiating the autonomous loop. The loop will end automatically when the code is fully secure.

Project Structure

├── knowledge_base/
│   └── security_rules.txt  # RAG ruleset (OWASP Top 10) for the Security Agent
├── .env                    # Local IP configuration (ignored in Git)
├── .gitignore              # Git ignore rules
├── Start_Agents.bat        # Master execution script for Windows
├── agent_dev.py            # Script for the Developer Agent logic
├── agent_sec.py            # Script for the Security Expert Agent logic
├── message_board.txt       # Shared memory and output interface
├── turn.txt                # Execution state management
└── README.md               # Project documentation

Troubleshooting: Windows Terminal Emoji Encoding

The Security Agent outputs a ✅ emoji upon successfully approving the code. If your Python scripts crash with a 'charmap' codec can't encode character error on Windows, ensure your Python scripts are opening files with UTF-8 encoding:

open(filepath, 'w', encoding='utf-8')

You may also need to force your Windows terminal to use UTF-8 by running chcp 65001 before executing the batch file.

Security Notice

This project is intended for local network deployment. Do not expose your Ollama server port (11434) to the public internet without implementing proper reverse proxy authentication.

License

Distributed under the MIT License.