# RowBoat Labs  
🌐 Visit [RowBoat Labs](https://www.rowboatlabs.com) to learn more!  

---

# 🤖 Agents

## 📝 Overview  
- ⚙️ RowBoat Agents is a multi-agent framework that powers conversations using agentic workflows.  
- 🚀 Built on top of [OpenAI Swarm](https://github.com/openai/swarm) with custom enhancements and improvements. Check the `NOTICE.md` for attribution and licensing details (MIT license).  

---

## 🕸️ Graph-based Framework  
- 🔄 Multi-agent systems are represented as graphs, where each agent is a node in the graph.  
- 📊 RowBoat Agents uses a stateless Directed Acyclic Graph (DAG).  
- 🗨️ At each conversation turn:  
  - The graph is traversed based on `messages`, `state`, and `workflow` (which defines agents, tools, and their connections).  
- 🛠️ Configure Workflows using the RowBoat Studio (UI) with the help of an AI copilot. Setup instructions can be found in the [main README](https://github.com/rowboatlabs/rowboat/tree/dev).  
- 💡 Each turn starts with a fresh graph, generating the next `messages` and `state`, which the upstream service displays to the user.  
  - If `messages` contain tool calls, the upstream service invokes the necessary tools and sends the result back to continue the interaction.

---

## 🗂️ Key Request and Response Fields

### 📤 Request  
- 📝 `messages`: List of user messages  
- 🔄 `state`: Active agent state and histories  
- 🛠️ `workflow`: Graph of agents, tools, and connections  

Example JSON: `tests/sample_requests/default_example.json`  

---

### 📥 Response  
- 📝 `messages`: List of response messages (may contain tool calls)  
- 🔄 `state`: Updated state to pass in the next request (since the framework is stateless)  

Example JSON: `tests/sample_responses/default_example.json`  

---

# 🛠️ Using the Framework

## ⚙️ Set Up Conda Environment  
- `conda create -n myenv python=3.12`  
- `conda activate myenv`  
  - ⚠️ Note: Python >= 3.10 required  

---

## 📦 Install Dependencies

### If using poetry
- `pip install poetry`
- `poetry install`

### If using pip
`pip install -r requirements.txt`

## 🔑 Set up .env file
Copy `.env.example` to `.env` and add your API keys

## 🧪 Run interactive test
`python -m tests.interactive --config default_config.json --sample_request default_example.json --load_messages`
- `--config`: Config json filename, under `configs` folder
- `--sample_request`: Path to the sample request file, under `tests/sample_requests` folder
- `--load_messages`: If set, it will additionally load the initial set of messages from the sample request file. Else, user input will be required starting from the first message.

## 🌐 Set up app server

- For local testing: `flask --app src.app.main run --port=4040`
- To set up the server on remote: `gunicorn -b 0.0.0.0:4040 src.app.main:app`

## 🖥️ Run test client
`python -m tests.app_client --sample_request default_example.json`
- `--sample_request`: Path to the sample request file, under `tests/sample_requests` folder

# 📖 More details

## 🔍 Specifics
- ⚙️ **Format**: Uses OpenAI's messages format when passing messages. 
- 🤖 **LLMs**: Currently, only OpenAI LLMs (e.g. gpt-4o, gpt-4o-mini) are supported. Easy to expand to other LLMs like Claude, Gemini or self-hosted models.
- 📤 **Responses**: Here are some examples of responses that the framework can return:
  - A list of one user-facing message
  - A list of one or more tool calls
  - A list of one user-facing message and one or more tool calls
- ⚠️ **Errors**: Errors are thrown as a tool call `raise_error` with the error message as the argument. Real-time error handling will be managed by the upstream service. 

## 🗂️ Important directories and files
- `src/`: Contains all source code for the agents app
  - `src/app/`: Contains Flask app which exposes the framework as a service
  - `src/graph/`: Contains logic to run every turn of the conversation
    - `src/graph/core.py`: Core graph implementation which parses the workflow config, creates agents from it and runs the turn of conversation (through the `run_turn` function)
  - `src/swarm/`: RowBoat's custom implementation of OpenAI Swarm, which is used by `src/graph/core.py`
- `tests/`: Contains sample requests, an interactive client and a test client which mocks an upstream service
- `configs/`: Contains graph configurations (changed infrequently)
- `tests/sample_requests/`: Contains sample request files for the agents app

## 🔄 High-level flow
- `app/main.py` receives the request JSON from an upstream service, parses it and sends it to `src/graph/core.py`
- `src/graph/core.py` creates the agent graph object from scratch and uses `src/swarm/core.py` to run the turn
- `src/swarm/core.py` runs the turn by performing actual LLM calls and internal tool invocations to transitiion between agents
- `src/graph/core.py` returns the response messages and the new state to `app/main.py`, which relays it back to the upstream service
- The upstream services appends any new user messages to the history of messages and sends the messages back along with the new state to `app/main.py` as part of the next request. The process repeats until the upstream service completes its conversation with the user.

## 🚫 Limitations
- Does not support streaming currently.
- Cannot respond with multiple user-facing messages in the same turn.