designing multiagent systems

The Problem

This repository is a portfolio of five self‑contained projects that teach how to build LLM‑enabled multi‑agent systems from scratch. The core framework PicoAgents (280 files, 250 code files) is the primary teaching artifact, but the code base also contains many examples, course materials, and research snippets. Because the projects are meant to illustrate patterns, the engineering practices that surround them are thin: there is no CI/CD pipeline, no lockfile, and only minimal tooling guardrails.

What This Does

PicoAgents (picoagents/) is a from‑scratch multi‑agent framework that implements agent reasoning loops, orchestration patterns, and utility components. Key modules and their import impact:

The import graph contains 374 internal modules and 471 import edges, with 22 modules residing in circular dependencies. The three hub modules above (types.py, messages.py, agents/__init__.py) are each imported by >30 other modules, giving them a high blast radius; a change there ripples across the whole framework.

Other notable projects:

• examples/ (112 files) – 78 code files, 7 data files; contains hello‑world demos for AutoGen, LangGraph, Semantic Kernel, and other frameworks.
• course/ (107 files) – 40 code files, 50 data files; sample book‑generator, deep‑research, and investment‑agent implementations.
• code_along/ (6 files) – step‑by‑step notebooks (ch04_v1‑v4) that walk through agent memory, tools, and streaming.
• research/ (31 files) – 4 code files, 17 data files; miscellaneous experiments.

How It Is Wired

Execution typically starts at one of the entry‑point scripts listed in the repo metadata, e.g.:

• course/samples/hello_world/autogen_core/app.py – runs a minimal AutoGen core demo.
• course/samples/hello_world/autogen_agentchat/app.py – launches an AutoGen agent‑chat example.
• course/samples/hello_world/agent_framework/app.py – a generic framework scaffold.

Each entry point imports from picoagents (e.g., from picoagents.src.picoagents.agents import …) and from the chosen LLM backend (OpenAI, Anthropic, etc.). The framework’s control flow goes: entry → agent loop (picoagents/src/picoagents/workflow/) → LLM call (picoagents/src/picoagents/llm/__init__) → tool execution (picoagents/src/picoagents/tools/_base.py) → result aggregation. Because of the import cycles, any modification to types.py or messages.py must consider the downstream dependents (53 and 39 importers respectively) and the circular path through agents/__init__.py.

The code‑health audit highlights two high‑severity issues:

• No lockfile beside picoagents/pyproject.toml – the manifest has no pinned dependencies, so installed transitive versions can drift between development and production.
• No CI configuration – 299 source files are never built or tested automatically, meaning a broken change can merge unseen.

Medium‑severity findings include the absence of Dependabot/Renovate, large JSON data blobs (>5 MB) in examples/workflows/yc_analysis/yc_data_test/companies.json, and an oversized middleware file (picoagents/src/picoagents/_middleware.py at 665 lines).

How To Use It

Setup (inferred from present files):

# Clone the repository
git clone https://github.com/moses-y/designing-multiagent-systems.git
cd designing-multiagent-systems

# Install the core framework and its dependencies
pip install -r course/requirements.txt   # pins the picoagents stack
# Optional: install extra demo deps
pip install -r course/samples/hello_world/autogen_core/requirements.txt

Configuration – environment variables for LLM keys are expected in a .env file at the repo root (the README mentions “set your OpenAI API key”). No dedicated config file exists beyond the requirements.txt manifests.

Running a demo – to launch the hello‑world AutoGen core example:

python course/samples/hello_world/autogen_core/app.py

The script creates a simple agent that replies to a user prompt, demonstrates the reasoning loop, and writes a results.json file.

Real‑World Use

The patterns illustrated here (workflow‑driven orchestration, explicit message passing, agent‑level cancellation) map directly onto production systems that need deterministic agent pipelines, e.g., a customer‑support triage bot that routes queries through a classifier → retriever → response generator. The book‑generator sample (course/samples/book_generator/autogen_core/app.py) shows how to chain multiple agents to produce a PDF‑ready manuscript, a pattern reusable for report‑generation or data‑synthesis services.

Code Health & Issues

• HIGH – Commit a lockfile beside the manifest (picoagents/pyproject.toml). Without it, installed transitive dependencies can differ between test and ship, allowing malicious patches to reach production unnoticed.
• HIGH – Add a CI workflow that builds and tests the repository on every push and pull request. Currently no .github/workflows exists.
• MEDIUM – Enable Dependabot or Renovate for the 15 manifests; without a bot, security advisories remain unpatched until a manual audit.
• MEDIUM – Move the large JSON blobs (companies.json 16.6 MB, yc_agents.json 6.8 MB) to Git LFS or external object storage; they inflate clone size and CI checkout time.
• LOW – Add project convention files (.editorconfig, .gitattributes with text=auto eol=lf, and a formatter config such as black/ruff for Python) to enforce consistent editor behavior across contributors.

(All findings are deterministic outputs of the static analysis pipeline; no opinion has been added.)

The Bottom Line

The repository is a well‑structured teaching collection: PicoAgents provides a transparent, from‑scratch multi‑agent framework, and the accompanying examples cover major LLM orchestration tools (AutoGen, LangGraph, Semantic Kernel). However, the engineering guardrails are minimal—no CI, no lockfile, and oversized data files increase operational overhead. It is best suited for learners, prototyping, or as a reference implementation where the user can accept the current lack of automated testing and dependency pinning. Teams looking for production‑ready, out‑of‑the‑box multi‑agent infrastructure will need to add the missing CI/CD, lockfile, and data‑management practices.