Open Source · MIT License · v0.3.3

Build Multi-Agent Systems
That Actually Work

A Python framework to design, configure, and deploy intelligent multi-agent systems with JSON configuration, provider independence, and zero-config bootstrapping.

Quick Start View on GitHub
$ pip install --upgrade git+https://github.com/mneuronico/multi-agent-system-library
0 Component Types
0 LLM Providers
0 Lines to Deploy
0 Built-in Tools
Scroll to explore
The Basics

How It Works

Three steps. That's all it takes to go from zero to a working multi-agent system.

1. Configure

Define your agents, tools, and workflows in a simple JSON file — or describe them in plain English.

{
  "components": [{
    "type": "agent",
    "name": "assistant",
    "system": "You help users."
  }]
}

2. Run

Initialize the manager and send a message. MAS handles the LLM calls, history, and data flow.

from mas import AgentSystemManager

manager = AgentSystemManager(
    config="config.json"
)
output = manager.run("Hello!")

3. Deploy

Launch as a Telegram/WhatsApp bot with one method call, or deploy to AWS Lambda with MAWS.

# Telegram bot — one line!
manager.start_telegram_bot()

# Or deploy to AWS Lambda
# $ maws start
# $ maws update
Deep Dive

The 4 Building Blocks

Every MAS system is composed of four types of components that work together seamlessly.

Agent

LLM-powered reasoning nodes. They process conversation history, follow system prompts, and produce structured JSON outputs.

Input Filtered message history
Output Structured JSON dict

Tool

Execute real-world actions — API calls, database queries, file operations. Agents decide what to call; Tools make it happen.

Input Dict of keyword args
Output Dict of results

Process

Data transformation and loading. Processes access full message history for context-aware data manipulation.

Input Full messages + manager
Output Dict

Automation

Orchestrate components into complex workflows with branching, loops, and switch logic — like programming but in JSON.

Input Passed to first component
Output Output of last component

Constrained Workflow Simulation

The router makes a decision, but only inside fixed paths you define. Agents operate within strict guardrails.

User Input
Router Agent
Pick Path
Weather Path
First Responder
Weather API
Cache Process
Formatter Agent
Final Responder
News Path
First Responder
News API
Summarize Process
Editor Agent
Final Responder
Orders Path
First Responder
Orders API
DB Process
Compliance Agent
Final Responder
Live Message Trace
Auto-playing
Key idea: The router only selects among predefined paths. Agents cannot invent new steps — they execute the workflow you designed.
Under the Hood

The Block System

All data flows through a universal block format — text, images, and audio are first-class citizens.

User Input

"What's the weather like?"
photo.jpg
voice_note.ogg
_to_blocks()

Universal Block

{
  "type": "text",
  "content": "What's the weather like?"
}
SQLite DB

Per-User History

user What's the weather?
agent Let me check...
tool {"temp": "22°C"}
agent It's 22°C and sunny!
Power Feature

Control Flow in JSON

Build sophisticated workflows with branching, loops, and switches — all defined declaratively.

Input
Classifier
needs_tool?
true
Tool Agent
Execute
false
Direct
Output
Input
Selector
action?
weather
Weather
news
News
default
Fallback
Output
Input
Initializer
while: !done
Worker
Process
Evaluator
Output
config.json 
{
  "type": "automation",
  "sequence": [
    "classifier_agent",
    {
      "control_flow_type": "branch",
    "condition": "needs_tool",
      "if_true": [
        "tool_agent",
        "execute_tool"
      ],
      "if_false": [
        "direct_response"
      ]
    },
    "format_output"
  ]
}
{
  "type": "automation",
  "sequence": [
    "selector",
    {
      "control_flow_type": "switch",
      "value": "action",
      "cases": [
        {"case": "weather",
         "body": ["weather_tool"]},
        {"case": "news",
         "body": ["news_tool"]},
        {"case": "default",
         "body": ["fallback"]}
      ]
    }
  ]
}
{
  "type": "automation",
  "sequence": [
    "initializer",
    {
      "control_flow_type": "while",
      "start_condition": "done == false",
      "body": [
        "worker",
        "process_step",
        "evaluator"
      ],
      "end_condition": "done == true"
    }
  ]
}
Flexibility

One Config. Any Provider.

Switch between LLM providers without changing a single line of code. MAS auto-formats messages for each.

config.json 
"default_models": [
    { "provider": "openai", "model": "gpt-4o" },
    { "provider": "google", "model": "gemini-2.0-flash" },
    { "provider": "groq", "model": "llama-3.3-70b" }
]
Automatic fallback: If a provider fails, MAS seamlessly tries the next one in the chain. No error handling code needed.
OpenAI
Google
Groq
Anthropic
DeepSeek
Local
Capabilities

Everything You Need

Built-in features that save you weeks of development time.

Multimodal by Default

Text, images, and audio are handled natively through the block system. Send a photo to an agent just like text.

Native Bots

Deploy to Telegram or WhatsApp with a single method call. STT, commands, and admin tools included.

Smart History

Per-user SQLite databases with automatic message management, export/import, and context-aware filtering.

Standard Library

7 ready-to-use tools for common integrations.

Google Places
YouTube
Calendar
Weather
MercadoPago
MD→PDF
Google Docs

Long-term Memory

Vector database support for persistent context and knowledge across sessions.

Non-Blocking

Run heavy tasks in the background with on_update / on_complete callbacks.

Cost Tracking

Per-call USD cost calculation, usage logs, and get_cost_report() for full observability.

Role-Playing

Define distinct personas for each agent with system prompts and specialized behaviors.

Magic

Zero-Config Bootstrap

Describe what you want in plain English. MAS generates the entire system for you.

You type:
|
MAS auto-generates
config.json Auto-generated
main.py 
from mas import AgentSystemManager as ASM

# That's it. One line.
ASM("I want a system that summarizes YouTube videos").run(
    "www.youtube.com/watch?v=dQw4w9WgXcQ"
)
Get Started

Up and Running in Minutes

From installation to a working multi-agent system in 4 simple steps.

1

Install

One pip command

2

Configure

Define your agents

3

Run

Execute your system

4

Deploy

Launch as a bot

terminal 
# Install the library
$ pip install --upgrade git+https://github.com/mneuronico/multi-agent-system-library

# Set up your API key (choose your provider)
$ echo OPENAI_API_KEY=sk-... > .env
# or GOOGLE_API_KEY, GROQ_API_KEY, ANTHROPIC_API_KEY, etc.
{
  "general_parameters": {
    "general_system_description": "A helpful assistant."
  },
  "components": [
    {
      "type": "agent",
      "name": "router",
      "system": "Classify user intent.",
      "required_outputs": {
        "action": "'search' or 'chat'"
      },
            "default_models": [
                {"provider": "openai", "model": "gpt-4o-mini"}
            ]
    },
    {
      "type": "agent",
      "name": "responder",
      "system": "You are a helpful assistant.",
      "required_outputs": {
        "response": "Response to the user."
      }
    }
  ]
}
from mas import AgentSystemManager

# Initialize with your config
manager = AgentSystemManager(config="config.json")

# Run the system
output = manager.run(
    input="What is quantum computing?",
    verbose=True
)
print(output)
# {'response': 'Quantum computing uses...'}
from mas import AgentSystemManager

manager = AgentSystemManager(config="config.json")

# Option A: Telegram bot (one line!)
manager.start_telegram_bot()

# Option B: WhatsApp bot
manager.start_whatsapp_bot()

# Option C: Deploy to AWS with MAWS
# $ pip install maws
# $ maws start && maws update
Deployment

MAWS — MAS on AWS

Deploy your multi-agent systems to AWS Lambda with three commands.

Install

pip install maws

Initialize

maws start

Deploy

maws update
Telegram
WhatsApp
API Gateway
Lambda + MAS
DynamoDB
S3
SSM
Self-invocation to avoid API Gateway timeouts
Per-user DynamoDB locking for safe concurrency
S3-based history sync per webhook call
SSM Parameter Store for secure secrets
Real World

Built with MAS

Real applications running in production, powered by MAS.

Ready to build your own
Multi-Agent System?

Start building in minutes. Open source, MIT licensed, and actively maintained.

Get Started on GitHub Read the Docs