To truly master the Multi-Agent architecture, the best approach is to build it from scratch. I recommend Victor Dibia’s open-source project designing-multiagent-systems (companion code repository for the book). The project includes a pedagogical framework built from the ground up called PicoAgents. It avoids black-box frameworks and deconstructs the underlying logic of multi-agent systems with extreme clarity:

Basics & Advanced: From Agent Loop and Tool Calling to Memory, Streaming, Middleware, and Human-in-the-Loop (HITL) collaboration paradigms.
Collaboration Paradigms: Covers DAG workflows, GroupChat polling, LLM-driven decision-making, and Magentic-One planning patterns.
Production Essentials: Includes Playwright browser automation (Computer Use), LLM-as-Judge evaluation, and a FastAPI+React visual Web UI.
Cross-Framework Comparison: Provides corresponding implementations for comparison in LangGraph, Microsoft Agent Framework, and Google ADK.
Portal: https://github.com/victordibia/designing-multiagent-systems…
#AI #MultiAgent #LLM #OpenSource #SoftwareEngineering

victordibia/designing-multiagent-systems

Source: https://github.com/victordibia/designing-multiagent-systems

Designing Multi-Agent Systems

Official code repository for Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents (https://buy.multiagentbook.com/?utm_source=github&utm_medium=readme) by Victor Dibia (https://victordibia.com).

Designing Multi-Agent Systems (https://buy.multiagentbook.com/?utm_source=github&utm_medium=readme)

Learn to build effective multi-agent systems from first principles through complete, tested implementations. This repository includes PicoAgents—a full-featured multi-agent framework built entirely from scratch for the sole purpose of teaching you how multi-agent systems work. Every component, from agent reasoning loops to orchestration patterns, is implemented with clarity and transparency.

Buy Digital Edition | Paperback on Amazon | Hardcover on Amazon

Why This Book & Code Repository?

As the AI agent space evolves rapidly, clear patterns are emerging for building effective multi-agent systems. This book focuses on identifying these patterns and providing practical guidance for applying them effectively.

What makes this approach unique:

• Fundamentals-first: Build from scratch to understand every component and design decision
• Complete implementations: Every theoretical concept backed by working, tested code
• Framework-agnostic: Core patterns that transcend any specific framework (avoids the lock-in or outdated API issue common with books that focus on a single framework)
• Production considerations: Evaluation, optimization, and deployment guidance from real-world experience

What You’ll Learn & Build

The book is organized across 4 parts, taking you from theory to production:

Part I: Foundations of Multi-Agent Systems

Part II: Building Multi-Agent Systems from Scratch

Chapter	Title	Code	Learning Outcome
Ch 4	Building Your First Agent	agents/_agent.py, basic-agent.py, memory.py, middleware.py, structured-output.py, agent_as_tool.py, otel/, memory/, tools/approval_example.py	Build agents with tools, memory, streaming, middleware, observability, and human-in-the-loop
Ch 5	Computer Use Agents	agents/_computer_use/, computer_use.py	Build browser automation agents with multimodal reasoning
Ch 6	Building Multi-Agent Workflows	workflow/, workflows/	Build type-safe workflows with streaming observability
Ch 7	Autonomous Multi-Agent Orchestration	orchestration/, round-robin.py, ai-driven.py, plan-based.py	Implement GroupChat, LLM-driven, and plan-based orchestration (Magentic One patterns)
Ch 8	Building Modern Agent UX Applications	app/ (minimal FastAPI+SSE example), webui/ (production React UI)	Build interactive agent applications with web UI, auto-discovery, and real-time streaming
Ch 9	Multi-Agent Frameworks	frameworks/ (Microsoft Agent Framework, Google ADK, LangGraph comparisons)	Evaluate and choose the right multi-agent framework

Part III: Evaluating and Optimizing Multi-Agent Systems

Part IV: Real-World Applications

Getting Started

Option 1: Interactive Notebooks

Click Colab badges in the chapter tables above to run examples in your browser. No installation required.

Option 2: GitHub Codespaces

Pre-configured development environment in your browser.

Once open:

1. Add your API key: export OPENAI_API_KEY='your-key'
2. Run examples: python examples/agents/basic-agent.py
3. Launch Web UI: picoagents ui

Free tier: 60 hours/month

Option 3: Local Installation

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

# Navigate to the PicoAgents framework directory
cd picoagents

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Basic installation
pip install -e .

# Or install with optional features
pip install -e ".[web]"          # Web UI and API server
pip install -e ".[mcp]"          # MCP client and playground (mcp>=2.0.0)
pip install -e ".[persist]"      # Run/eval persistence behind the History page
pip install -e ".[computer-use]" # Browser automation
pip install -e ".[examples]"     # Run example scripts
pip install -e ".[all]"          # Most extras (not persist, otel, dev, frameworks)

# Set up your API key
export OPENAI_API_KEY="your-api-key-here"

Quick Start: Your First Agent

In this book, we will cover the fundamentals of building multi-agent systems, and incrementally build up the Agents abstractions shown below:

from picoagents import Agent, OpenAIChatCompletionClient

def get_weather(location: str) -> str:
    """Get current weather for a given location."""
    return f"The weather in {location} is sunny, 75°F"

# Create an agent
agent = Agent(
    name="assistant",
    instructions="You are helpful. Use tools when appropriate.",
    model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
    tools=[get_weather]
)

# Use the agent
response = await agent.run("What's the weather in Paris?")
print(response.messages[-1].content)

Want a simpler starting point? The code_along/ directory builds a minimal agent from zero in four progressive steps: core agent loop → tool calling → memory → streaming. PicoAgents is an expanded, production-ready version of the same ideas.

Model Client Setup

PicoAgents supports multiple LLM providers through a unified interface. Each provider requires minimal setup—just API credentials and switching the client class. Chapter 4 covers building custom model clients for any provider.

Quick Examples:

# OpenAI (default)
from picoagents import OpenAIChatCompletionClient
client = OpenAIChatCompletionClient(model="gpt-4.1-mini")

# Anthropic
from picoagents import AnthropicChatCompletionClient
client = AnthropicChatCompletionClient(model="claude-3-5-sonnet-20241022")

# GitHub Models (free tier)
client = OpenAIChatCompletionClient(
    model="openai/gpt-4.1-mini",
    api_key=os.getenv("GITHUB_TOKEN"),
    base_url="https://models.github.ai/inference"
)

# Local LLM (e.g., Ollama)
client = OpenAIChatCompletionClient(
    model="llama3.2",
    base_url="http://localhost:11434/v1"
)

Launch the Web UI

PicoAgents Web UI

# Auto-discover agents, orchestrators, and workflows in current directory
picoagents ui

# Or specify a directory
picoagents ui --dir ./examples

The Web UI discovers the agents, orchestrators, and workflows in your codebase and gives you a place to run them: streaming chat, a live debug rail, and recorded run history. It also includes an MCP Playground for connecting to MCP servers, invoking their tools, and reading the raw JSON-RPC traffic, plus an evaluation dashboard for datasets, targets, and batch runs. Five demo MCP servers ship with the package, covering tools, mid-call input, notifications, interactive UIs, and OAuth-protected access.

Run Examples

Examples are now at the root level for easy access:

# Basic agent with tools (Chapter 4)
python examples/agents/basic-agent.py

# Browser automation agent (Chapter 5)
python examples/agents/computer_use.py

# Autonomous orchestration (Chapter 7)
python examples/orchestration/round-robin.py
python examples/orchestration/ai-driven.py

# Production workflow (Chapter 14)
python examples/workflows/yc_analysis/workflow.py

PicoAgents Framework

This repository is organized into two main components:

1. Framework Source (picoagents/)

Complete multi-agent framework built from scratch:

picoagents/
├── src/picoagents/
│   ├── agents/             # Core Agent implementation (Ch 4)
│   │   ├── _agent.py         # Complete agent with streaming, tools, memory
│   │   └── _computer_use/    # Browser automation agents (Ch 5)
│   ├── workflow/           # Type-safe workflow engine (Ch 5)
│   │   ├── core/             # DAG-based execution with streaming
│   │   └── steps/            # Reusable workflow steps
│   ├── orchestration/      # Autonomous coordination (Ch 7)
│   │   ├── _round_robin.py   # Sequential turn-taking
│   │   ├── _ai.py            # LLM-driven speaker selection
│   │   └── _plan.py          # Plan-based orchestration (Magentic One)
│   ├── tools/              # 15+ built-in tools (core, research, coding)
│   ├── eval/               # Evaluation framework (Ch 10)
│   │   ├── judges/           # LLM-as-judge, reference-based
│   │   └── _runner.py        # Test execution and metrics
│   ├── webui/              # Web UI, MCP playground (Ch 8, Ch 12)
│   ├── llm/                # OpenAI and Azure clients
│   ├── memory/             # Memory implementations
│   ├── termination/        # 9 termination conditions
│   └── middleware/         # Extensible middleware system
└── tests/                  # Comprehensive test suite

2. Examples (examples/)

50+ runnable examples organized by chapter:

examples/
├── agents/               # Ch 4-5: Basic agents, tools, computer use
├── memory/               # Ch 4: Long-term memory & RAG patterns
├── mcp/                  # Ch 4: Model Context Protocol agents
├── tools/                # Ch 4: Tool creation, approval loops & patterns
├── workflows/            # Ch 6: Sequential, parallel, production workflows
├── orchestration/        # Ch 7: Round-robin, AI-driven, plan-based
├── app/                  # Ch 8: Modern Agent UX (FastAPI + SSE)
├── webui/                # Ch 8: Web UI integration examples
├── frameworks/           # Ch 9: Comparisons (LangGraph, AutoGen, etc.)
├── evaluation/           # Ch 10: Agent evaluation patterns
├── notebooks/            # Interactive Jupyter notebooks
├── otel/                 # Production: OpenTelemetry & Observability
└── contextengineering/   # Production: Context management str...