<div align="center"> <h1 align="center">Control Plane For Your AI Agents </h1> </div>

mahilo is a multi-agent framework that allows you to create new agents or register agents from other frameworks in a team, where they can talk to each other and share information, all under human supervision.

mahilo

Install

pip install mahilo

For voice features, install with the voice extras as below. You also need to install PyAudio for your system. Learn how to do it for your OS, here.

pip install mahilo[voice]

Usage

from mahilo import BaseAgent, AgentManager, ServerManager
from mahilo.integrations.langgraph.agent import LangGraphAgent

# a mahilo agent
sales_agent = BaseAgent(
    type="sales_agent",
    description=sales_agent_prompt,
    tools=sales_tools,
)

# a langgraph agent
marketing_agent = LangGraphAgent(
    langgraph_agent=graph_builder,
    name="MarketingAgent",
    description=marketing_agent_prompt,
    can_contact=[],
)

# Create Agent Manager (think of it as a team)
manager = AgentManager()
manager.register_agent(sales_agent)
manager.register_agent(marketing_agent)

# activate any agents with runtime params (here server_id is the thread_id for the langgraph agent)
marketing_agent.activate(server_id="1")

# initialize the server manager
server = ServerManager(manager)
# Start WebSocket Server
server.run()

When the code above is run, it starts a websocket server on localhost (unless some other host is specified) that clients can connect to. In this case, clients can connect to three websocket endpoints corresponding to the three agents. For example, to do that for one agent, you can run the following command:

mahilo connect --url http://localhost:8000 --agent-name marketing_agent

This would then allow you to talk to the marketing agent. If you pass the --voice flag, you would be able to talk to the agent using voice.

Ideally, you would spin up more terminals for the other agents and can then observe how the conversation would unfold across the agents.

How does the transfer of context work?

Every BaseAgent comes with a function called chat_with_an_agent that takes in a question or a message and the agent it is being sent to. This function is used by the agents whenever they feel that they want info from the other agents.

The AgentManager class manages the context and makes the last N conversations available across agents, for added visibility. More on this is in the Detailed Features section below.

For a demo of agents sharing context with each other, check out the video below, in addition to the Realtime API video above:

Overview
Features
Getting Started
Project Structure
Detailed Features
Contributing

Overview

This project provides a flexible framework for defining and creating multi-agent systems that can each interact with humans while sharing relevant context internally. It allows developers to easily set up complex agent networks for various applications, from customer service to emergency response simulations.

Agents are aware of other agents in the system and can decide to talk to one or more agents based on the current conversation context, simultaneously. The system is designed to make humans more efficient by giving them an assistant that can handle context from multiple agents and help the human stay focused on their specific problem, while surfacing all relevant information on demand.

Features

Above is an architecture diagram that shows the different components of the system in the context of a health emergency scenario. You have three humans talking to their respective agents, which all share information internally.

TL;DR:

Realtime API support for talking to your agents via voice!
Easy-to-extend BaseAgent class to create your own agents
WebSocket-based real-time communication with multiple users simultaneously
Flexible communication patterns: peer-to-peer and hierarchical (or centralized)
Control hierarchy in communication via can_contact lists: limit what agents can talk to what other agents.
Session management for persistent conversations
CLI client for easy testing and interaction
Multiple users can connect to the same agent. In emergency situation scenarios, this means multiple police officers can connect to the same dispatcher and receive updates from the dispatcher.
Agents are only activated when they are needed.
Multi-provider LLM support through LiteLLM, allowing you to use models from OpenAI, Anthropic, Azure, and more with a simple environment variable.
Message validation policies to prevent harmful content, repetitive loops, and ensure high-quality agent communications.

Above is an image that shows a three-agent system where a medical advisor is talking about a public health emergency and the agent decides to call the logistics coordinator and the public communication director agents simultaneously to coordinate the response to the emergency.

More information on the features can be found in the Detailed Features section below.

Getting Started

🤘 Quickstart

Install the package:
```
pip install mahilo
```
Note that if you want to use the voice feature, you need to have pyaudio installed. Learn how to do it for your OS, here.
```
pip install mahilo[voice]
```
Export your OpenAI API key:
```
export OPENAI_API_KEY=<your_api_key>
```
Go to one of the example directories and run the server:
```
cd examples/your_example
python run_server.py
```
This starts the agent server locally at http://localhost:8000.
Connect to the server using the CLI: For each of the agents in the system, you can spin up a client to connect to the server.
```
mahilo connect --agent-name your_agent_name
```
Run this command in separate terminals for each of the agents and you can then start talking with them.

If you want to use the voice feature, you can run the same command with the --voice flag:
```
mahilo connect --agent-name your_agent_name --voice
```

[!TIP] You dont have to specify the URL if you want to connect to the default server.

🧑‍🍳 Building your own agents

Define your agents looking at examples in the templates directory.
Create a run script for your specific use case. See the examples in the examples directory.

Run your server:

python examples/your_example/run_server.py

Connect to your server using the CLI:
```
mahilo connect --agent-name your_agent_name
```
You can connect to the same server using multiple clients to test the system with multiple users. This is useful for testing the system in a real-world scenario where multiple agents need to coordinate their actions.

If you want to use the voice feature, you can run the same command with the --voice flag:
```
mahilo connect --agent-name your_agent_name --voice
```

[!TIP] You dont have to specify the URL if you want to connect to the default server.

Project Structure

agent_manager.py: Defines the AgentManager and BaseAgent classes
server.py: Implements the ServerManager for handling WebSocket connections
session.py: Manages conversation sessions for each agent
client.py: Provides a CLI client for interacting with the agents
templates/: Contains agent templates for different use cases
examples/: Includes example implementations of multi-agent systems

Detailed Features

Index

Human-in-the-Loop
Easy-to-use agent definition system
WebSocket-based real-time communication
Flexible communication patterns: peer-to-peer and hierarchical (or centralized)
Flexible agent manager for handling multiple agent types
Session management for persistent conversations
Multi-provider LLM support
Policy Validation for Inter-Agent Communication

Human-in-the-Loop

The human-in-the-loop is implemented by having the human client connect to each agent in the system.
The

Mahilo

Install / Use

README