AI Engineering: Agents and Applications › AI Agents › Day 293
Hands-on lab — Day 293: Multi-Agent Systems
- ← Back to the Day 293 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/ai-engineering/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-systemswhen 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 skeletonexamples/multi_agent_system.py: Verified reference implementationtests/test_multi_agent_system.py: Test suiteexpected-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.
Navigation
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
- Message Bus Filtering: Use
get_messages_for(recipient)to prevent message leakage between unrelated agents. - Critic Rejection Loop: Ensure the retry counter increments to avoid unbounded critique cycles.
Security notes
Security Considerations - Day 293
- Role Privilege Separation: Specialized agents only receive permissions strictly necessary for their role.
- Bounded Communication: Hard round limit prevents runaway conversational loops and token exhaustion.