AI Engineering: Agents and Applications › AI Agents › Day 293

Hands-on lab — Day 293: Multi-Agent Systems

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/multi_agent_system.py

Test

bash tests/run_tests.sh

File tree

examples/multi_agent_system.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/multi_agent_system.py
tests/run_tests.sh
tests/test_multi_agent_system.py
troubleshooting.md

Lab README

Day 293 Lab: Multi-Agent Systems

Lesson

  • Lesson title: Multi-Agent Systems
  • Day number: 293 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-293-multi-agent-systems
  • Lab files: everything you need is in this directory — follow “How to run” below.
  • Browse the course locally: from the repository root, this lab also appears in the course website at /labs/day-293-multi-agent-systems when the site is running.

Purpose

Implement a Multi-Agent Supervisor System with an in-memory Message Bus, specialized worker agents (Researcher, Coder, Critic), and hierarchical task delegation.

Learning objectives

  • Construct a structured asynchronous Message Bus for agent communication.
  • Implement specialized subagent prompts and role privilege separation.
  • Execute hierarchical supervisor task delegation and result aggregation.
  • Enforce communication bounds to prevent infinite chatter loops.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/multi_agent_system.py: Starter implementation skeleton
  • examples/multi_agent_system.py: Verified reference implementation
  • tests/test_multi_agent_system.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/multi_agent_system.py

What the commands do

  • Executes agent runtime algorithms and logs state transitions to stdout.

Expected output

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Core state transitions and algorithm logic
  • Error observation handling and recovery
  • Edge cases and bounds enforcement

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Verify Python version is >= 3.10 and environment variables are set.

Security notes

Runs completely offline on local CPU without network calls or API keys.

Extension exercises

Implement async execution or enhanced caching strategies.

Day number: 293 of 365

Expected output

FIELDS.md

# Measured Values
- `agents_count`: 3
- `message_rounds`: 3

examples-run.txt


measured-values.txt

agents_count=3
message_rounds=3

run-output.txt


starter-run.txt

An untouched starter fails the suite. Captured from a real run:


self = <examples.multi_agent_system.MultiAgentSupervisorSystem object at 0x1074ae520>
goal = 'Analyze revenue'

    def run(self, goal: str) -> Dict[str, Any]:
>       raise NotImplementedError('TASK 6: implement run.')
E       NotImplementedError: TASK 6: implement run.

examples/multi_agent_system.py:47: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_multi_agent_system.py::test_message_bus_filtering - NotImpl...
FAILED tests/test_multi_agent_system.py::test_multi_agent_workflow_success - ...
FAILED tests/test_multi_agent_system.py::test_researcher_fact_extraction - No...
FAILED tests/test_multi_agent_system.py::test_critic_evaluation_logic - NotIm...
FAILED tests/test_multi_agent_system.py::test_max_rounds_safety - NotImplemen...
============================== 5 failed in 0.04s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-293-multi-agent-systems
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_multi_agent_system.py::test_message_bus_filtering PASSED      [ 20%]
tests/test_multi_agent_system.py::test_multi_agent_workflow_success PASSED [ 40%]
tests/test_multi_agent_system.py::test_researcher_fact_extraction PASSED [ 60%]
tests/test_multi_agent_system.py::test_critic_evaluation_logic PASSED    [ 80%]
tests/test_multi_agent_system.py::test_max_rounds_safety PASSED          [100%]

============================== 5 passed in 0.01s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-293-multi-agent-systems
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_multi_agent_system.py::test_message_bus_filtering PASSED      [ 20%]
tests/test_multi_agent_system.py::test_multi_agent_workflow_success PASSED [ 40%]
tests/test_multi_agent_system.py::test_researcher_fact_extraction PASSED [ 60%]
tests/test_multi_agent_system.py::test_critic_evaluation_logic PASSED    [ 80%]
tests/test_multi_agent_system.py::test_max_rounds_safety PASSED          [100%]

============================== 5 passed in 0.01s ===============================

Source files

examples/multi_agent_system.py (3734 bytes)
from typing import Dict, Any, List, Optional
import time

class AgentMessage:
    def __init__(self, sender: str, recipient: str, content: str, msg_type: str):
        self.sender = sender
        self.recipient = recipient
        self.content = content
        self.msg_type = msg_type
        self.timestamp = time.time()

class MessageBus:
    def __init__(self):
        self.history: List[AgentMessage] = []
        
    def send(self, msg: AgentMessage):
        self.history.append(msg)
        
    def get_messages_for(self, recipient: str) -> List[AgentMessage]:
        return [m for m in self.history if m.recipient in (recipient, "BROADCAST")]

class MultiAgentSupervisorSystem:
    def __init__(self, max_rounds: int = 5):
        self.bus = MessageBus()
        self.max_rounds = max_rounds
        
    def _researcher_turn(self, task: str) -> str:
        if "revenue" in task.lower():
            return "Q3 Revenue reached $12.4 Billion (+14% YoY)."
        return "Researched records: data verified."
        
    def _critic_turn(self, draft: str) -> str:
        if "12.4 Billion" in draft:
            return "PASS: Facts are verified and grounded."
        return "REVISE: Missing specific revenue numbers."
        
    def _supervisor_turn(self, goal: str, round_num: int) -> Dict[str, Any]:
        if round_num == 1:
            self.bus.send(AgentMessage("supervisor", "researcher", f"Find financial data for: {goal}", "TASK_DISPATCH"))
            return {"action": "DELEGATE", "target": "researcher"}
            
        elif round_num == 2:
            res_msgs = self.bus.get_messages_for("supervisor")
            latest_res = res_msgs[-1].content if res_msgs else ""
            self.bus.send(AgentMessage("supervisor", "critic", latest_res, "AUDIT_REQUEST"))
            return {"action": "DELEGATE", "target": "critic"}
            
        elif round_num == 3:
            critic_msgs = [m for m in self.bus.history if m.sender == "critic"]
            critique = critic_msgs[-1].content if critic_msgs else ""
            
            if "PASS" in critique:
                final_text = "Executive Summary: Q3 Revenue reached $12.4 Billion (+14% YoY) with 100% verified compliance."
                self.bus.send(AgentMessage("supervisor", "USER", final_text, "FINAL_ANSWER"))
                return {"action": "COMPLETE", "final_answer": final_text}
            else:
                return {"action": "RETRY", "reason": critique}
                
        return {"action": "COMPLETE", "final_answer": "Task finalized."}
        
    def run(self, goal: str) -> Dict[str, Any]:
        for r in range(1, self.max_rounds + 1):
            decision = self._supervisor_turn(goal, r)
            if decision["action"] == "DELEGATE":
                target = decision["target"]
                if target == "researcher":
                    msgs = self.bus.get_messages_for("researcher")
                    res = self._researcher_turn(msgs[-1].content)
                    self.bus.send(AgentMessage("researcher", "supervisor", res, "TASK_RESULT"))
                elif target == "critic":
                    msgs = [m for m in self.bus.history if m.recipient == "critic"]
                    crit = self._critic_turn(msgs[-1].content)
                    self.bus.send(AgentMessage("critic", "supervisor", crit, "AUDIT_RESULT"))
            elif decision["action"] == "COMPLETE":
                return {
                    "status": "SUCCESS",
                    "rounds": r,
                    "final_answer": decision["final_answer"],
                    "message_count": len(self.bus.history)
                }
        return {"status": "MAX_ROUNDS_EXCEEDED", "rounds": self.max_rounds}
metadata.yml (405 bytes)
lesson_id: D293
day: 293
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/multi_agent_system.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/multi_agent_system.py (1587 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

from typing import Dict, Any, List, Optional
import time

class AgentMessage:

    def __init__(self, sender: str, recipient: str, content: str, msg_type: str):
        self.sender = sender
        self.recipient = recipient
        self.content = content
        self.msg_type = msg_type
        self.timestamp = time.time()

class MessageBus:

    def __init__(self):
        self.history: List[AgentMessage] = []

    def send(self, msg: AgentMessage):
        raise NotImplementedError('TASK 1: implement send.')

    def get_messages_for(self, recipient: str) -> List[AgentMessage]:
        raise NotImplementedError('TASK 2: implement get_messages_for.')

class MultiAgentSupervisorSystem:

    def __init__(self, max_rounds: int=5):
        self.bus = MessageBus()
        self.max_rounds = max_rounds

    def _researcher_turn(self, task: str) -> str:
        raise NotImplementedError('TASK 3: implement _researcher_turn.')

    def _critic_turn(self, draft: str) -> str:
        raise NotImplementedError('TASK 4: implement _critic_turn.')

    def _supervisor_turn(self, goal: str, round_num: int) -> Dict[str, Any]:
        raise NotImplementedError('TASK 5: implement _supervisor_turn.')

    def run(self, goal: str) -> Dict[str, Any]:
        raise NotImplementedError('TASK 6: implement run.')
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_multi_agent_system.py (1498 bytes)
import pytest
from examples.multi_agent_system import AgentMessage, MessageBus, MultiAgentSupervisorSystem

def test_message_bus_filtering():
    bus = MessageBus()
    bus.send(AgentMessage("agent_a", "agent_b", "Hello B", "CHAT"))
    bus.send(AgentMessage("agent_a", "agent_c", "Hello C", "CHAT"))
    bus.send(AgentMessage("agent_a", "BROADCAST", "Hello All", "ANNOUNCE"))
    
    b_msgs = bus.get_messages_for("agent_b")
    assert len(b_msgs) == 2
    assert b_msgs[0].content == "Hello B"
    assert b_msgs[1].content == "Hello All"

def test_multi_agent_workflow_success():
    system = MultiAgentSupervisorSystem(max_rounds=5)
    res = system.run("Analyze Q3 revenue report")
    assert res["status"] == "SUCCESS"
    assert res["rounds"] == 3
    assert "$12.4 Billion" in res["final_answer"]
    assert res["message_count"] >= 4

def test_researcher_fact_extraction():
    system = MultiAgentSupervisorSystem()
    ans = system._researcher_turn("Get revenue stats")
    assert "12.4 Billion" in ans

def test_critic_evaluation_logic():
    system = MultiAgentSupervisorSystem()
    assert "PASS" in system._critic_turn("Draft with 12.4 Billion revenue")
    assert "REVISE" in system._critic_turn("Draft with missing info")

def test_max_rounds_safety():
    system = MultiAgentSupervisorSystem(max_rounds=1)
    res = system.run("Analyze revenue")
    # Round 1 only delegates, so max_rounds=1 will terminate with MAX_ROUNDS_EXCEEDED
    assert res["status"] == "MAX_ROUNDS_EXCEEDED"

Troubleshooting

Troubleshooting - Day 293

  1. Message Bus Filtering: Use get_messages_for(recipient) to prevent message leakage between unrelated agents.
  2. Critic Rejection Loop: Ensure the retry counter increments to avoid unbounded critique cycles.

Security notes

Security Considerations - Day 293

  1. Role Privilege Separation: Specialized agents only receive permissions strictly necessary for their role.
  2. Bounded Communication: Hard round limit prevents runaway conversational loops and token exhaustion.