An educational multi-agent framework built to teach you how multi-agent systems work from first principles.
Companion code for "Designing Multi-Agent Systems" by Victor Dibia. Every concept in the book is implemented here with clarity and best practices—so you can learn by reading the code and understanding exactly how it works.
Built for learning: This framework prioritizes code clarity and pedagogical value over performance optimization.
pip install picoagentsRequirements:
- Python 3.10+
- OpenAI API key (set
OPENAI_API_KEYenvironment variable)
Optional extras:
pip install "picoagents[web]" # Web UI, MCP playground, evaluation dashboard
pip install "picoagents[mcp]" # MCP client (requires mcp>=2.0.0, protocol 2026-07-28)
pip install "picoagents[persist]" # Run and eval persistence behind the History pagefrom 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)PicoAgents implements complete, working examples of:
- Agents - Reasoning loops, tool calling, memory, middleware, streaming
- Workflows - Type-safe DAG-based execution with parallel and conditional patterns
- Orchestration - Round-robin, AI-driven, and plan-based multi-agent coordination
- Tools - 15+ built-in tools (file ops, code execution, search, todos, skills)
- MCP - Client for the 2026-07-28 spec, plus a playground for testing servers with full wire visibility
- Evaluation - LLM-as-judge patterns, reference-based validation, datasets and batch runs
- Web UI - Auto-discovery, streaming chat, run history, MCP playground
picoagents/
├── src/picoagents/
│ ├── agents/ # Agent implementations (Ch 4-5)
│ ├── workflow/ # Workflow orchestration (Ch 5)
│ ├── orchestration/ # Autonomous coordination (Ch 6)
│ ├── tools/ # Tool system and built-in tools
│ ├── eval/ # Evaluation framework (Ch 8)
│ ├── webui/ # Web interface with auto-discovery
│ ├── llm/ # LLM clients (OpenAI, Azure)
│ ├── memory/ # Memory implementations
│ └── termination/ # Termination conditions
└── tests/ # Comprehensive test suite
Launch the web interface with auto-discovery of agents and workflows:
picoagents uiFeatures streaming responses, real-time debug events, and session management.
See the main repository for 50+ runnable examples organized by book chapter:
examples/agents/- Basic agents, tools, memory, computer use (Ch 4-5)examples/workflows/- Workflow patterns and case studies (Ch 5)examples/orchestration/- Multi-agent coordination (Ch 6)examples/evaluation/- Evaluation patterns (Ch 8)
Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents
This framework implements every concept from the book. The book provides:
- Why and when to use each pattern
- Trade-off analysis for design decisions
- Real-world case studies with complete implementations
- Evaluation strategies for measuring system performance
→ Buy Digital Edition | → GitHub Repository
# Clone repository
git clone https://github.com/victordibia/designing-multiagent-systems.git
cd designing-multiagent-systems/picoagents
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
python -m pytest tests/
# Type checking
python -m mypy src/
python -m pyright src/
# Code formatting
python -m black src/ tests/
python -m isort src/ tests/Victor Dibia - Website | LinkedIn | GitHub
@book{dibia2025multiagent,
title={Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents},
author={Dibia, Victor},
year={2025},
url={https://buy.multiagentbook.com}
}MIT License - see LICENSE file for details.
Learn more: Book Website | GitHub | Documentation