Day 24 Theory — Multi-Agent Systems: Only When One Agent Is Not Enough

Lesson Overview

This is the applied companion for Day 24. Read DAY_24_THEORY.md first for the beginner-first teaching of Multi-Agent Systems: Only When One Agent Is Not Enough. Then use the real service-desk-day-24/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 24 adds Multi-Agent Systems: Only When One Agent Is Not Enough to the running Service Desk. Start with shared_state.py, tools.py, benchmark.py, supervisor.py, mock_model.py, specialists.py, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why Multi-Agent Systems: Only When One Agent Is Not Enough is needed. Here the goal is evidence: identify where the capability is implemented, what observable behavior changes, and how the repository proves both success and failure behavior.

System Architecture

This is a repository surface map, not a claim that modules call each other in the displayed order. The modules are ranked by relevance to today's theory.

graph LR
    T[Day 24: Multi-Agent Systems - Only When One Agent Is Not Enough]
    T --> M1[shared_state.py]
    T --> M2[tools.py]
    T --> M3[benchmark.py]
    T --> M4[supervisor.py]
    T --> M5[mock_model.py]
    T --> M6[specialists.py]
    T --> M7[single_agent.py]
    T --> M8[models.py]

Follow imports and tests to discover the actual runtime flow.

Repository Implementation Map

Use the real Day 24 repository, not a fabricated sample, to connect theory to implementation.

Theory concepts to locate:

• What “multi-agent” should mean
• Why multiple agents can help
• The coordination cost
• Handoffs versus delegation

Most relevant implementation modules first:

• service_desk/shared_state.py
• service_desk/tools.py
• service_desk/benchmark.py
• service_desk/supervisor.py
• service_desk/mock_model.py
• service_desk/specialists.py
• service_desk/single_agent.py
• service_desk/models.py

Follow imports/calls from the relevant module and confirm behavior in tests. Record input → mechanism → observable output/state → failure evidence.

Code Walkthrough & Mechanics

Read shared_state.py, tools.py, benchmark.py, supervisor.py, mock_model.py, specialists.py, single_agent.py, models.py with these theory sections beside you:

• What “multi-agent” should mean — locate its implementation and evidence.
• Why multiple agents can help — locate its implementation and evidence.
• The coordination cost — locate its implementation and evidence.
• Handoffs versus delegation — locate its implementation and evidence.
• Shared context is not automatically safe — locate its implementation and evidence.

For each concept identify the real function/class/protocol boundary, its input/state, its observable result, and the assertion in tests/test_multi_agent.py that proves the behavior. If a concept has no implementation or evidence, record that as a gap rather than inventing one.

Common Mistakes & Debugging Guidance

Use the theory—not generic timeout or .env advice—to decide what can fail today.

Failure lens: revisit Handoffs versus delegation, Shared context is not automatically safe.

• Reproduce the smallest case that violates one of those expectations.
• Trace the real Day 24 modules until you find the first incorrect state/output/decision.
• Use tests/test_multi_agent.py as executable evidence.
• Add a regression test if the failure is not already represented.
• Fix the smallest responsible boundary and rerun the relevant test before the full suite.

Your debugging explanation must name the topic-specific invariant that failed, not merely say “an exception occurred.”

Practical Lab Instructions

1. Summarize these theory ideas before opening the implementation:
   • What “multi-agent” should mean
   • Why multiple agents can help
   • The coordination cost
   • Handoffs versus delegation
2. Inspect the most relevant real Day 24 modules first:
   • service_desk/shared_state.py
   • service_desk/tools.py
   • service_desk/benchmark.py
   • service_desk/supervisor.py
   • service_desk/mock_model.py
   • service_desk/specialists.py
   • service_desk/single_agent.py
   • service_desk/models.py
3. Inspect the automated evidence:
   • tests/test_multi_agent.py
4. Establish the baseline:

   cd service-desk-day-24
   PYTHONPATH=. pytest tests/test_multi_agent.py -q
   

5. Trace one theory concept through the actual nested modules and tests.
6. Run one success case and record input → mechanism → observable result.
7. Exercise one topic-specific failure/boundary case and name the invariant that protects the system.
8. Re-run the relevant tests and explain theory → implementation → evidence.

Done when: another student can reproduce your trace without relying on an invented sample.

Key Takeaways

1. Be able to explain What “multi-agent” should mean and point to its implementation/evidence in Day 24.
2. Be able to explain Why multiple agents can help and point to its implementation/evidence in Day 24.
3. Be able to explain The coordination cost and point to its implementation/evidence in Day 24.

Knowledge Check & Scenario Questions

1. Concept: Using What “multi-agent” should mean, explain the engineering problem Day 24 is solving without naming a framework as the answer.
2. Mechanism: How does Why multiple agents can help appear in the real project? Start from service_desk/shared_state.py and name the observable state/output/event that changes.
3. Failure: For The coordination cost, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_multi_agent.py.
4. Design review: Which assumption in today's design would you verify before reusing this implementation in a different production system?

Official References

• LangGraph Multi-Agent Workflows: https://langchain-ai.github.io/langgraph/concepts/multi_agent/
• Building Effective Agents (Anthropic): https://www.anthropic.com/research/building-effective-agents