PicoAgents: The Teaching Framework Inside designing-multiagent-systems
Building LLM-Enabled Multi Agent Applications from Scratch
At a glance
- What is it?
- The repository for Victor Dibia's multi-agent book ships PicoAgents, a from-scratch Python framework written to expose agent reasoning loops and orchestration instead of hiding them. It is a reading and teaching artifact first, a dependency second.
- Who is it for?
- Adopt PicoAgents if you are working through the book or need a readable reference implementation of agent loops, middleware and workflow orchestration that you can step through line by line. Do not adopt it as a production dependency for a system whose uptime matters more than your understanding of it.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 22 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the repository is actually for
This is the official code repository for Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents by Victor Dibia. The README frames the goal as learning to build multi-agent systems from first principles through complete, tested implementations, and the repository is organised to match the book's four parts rather than to serve as a general-purpose library. The table of contents maps chapters to directories: Chapter 1 points at examples/workflows/yc_analysis/, Chapter 4 at picoagents/src/picoagents/agents/_agent.py plus a set of example scripts covering memory, middleware, structured output and agent-as-tool, Chapter 5 at picoagents/src/picoagents/agents/_computer_use/, and Chapter 6 at picoagents/src/picoagents/workflow/. If you are not reading the book, you are using the repository out of its intended context, which is worth knowing before you file an issue about documentation gaps. The audience is engineers who want to see how an agent loop, a tool call, and a multi-agent handoff are implemented, not teams shopping for a runtime to put behind a product.
PicoAgents and the from-scratch constraint
The README describes PicoAgents as a full-featured multi-agent framework built entirely from scratch for the sole purpose of teaching how multi-agent systems work, with every component from agent reasoning loops to orchestration patterns implemented with clarity and transparency. That sentence carries the design constraint for the whole project. A framework written for transparency optimises for a reader being able to follow a call stack, which usually means fewer layers of indirection, fewer optional backends, and fewer abstractions that exist only to serve scale. The repository layout supports this: the agent implementation lives under picoagents/src/picoagents/agents/, computer use under a sibling _computer_use/ directory, and workflow orchestration under picoagents/src/picoagents/workflow/. The book's stated position is that core patterns transcend any specific framework, and the README argues this avoids the lock-in or outdated API problem common to books that focus on a single framework. That is a defensible editorial choice, and it also means the code is a reference implementation rather than a compatibility layer over an existing one.
Running the examples and the Codespaces path
The README offers a Codespaces badge pointing at codespaces.new/victordibia/designing-multiagent-systems?quickstart=1, which is the fastest documented route because it avoids local environment setup. For a local checkout the README does not spell out a pip install line for PicoAgents in the portion available here, so the reliable path is to read the packaging metadata under picoagents/ and the example scripts themselves. The examples are the real entry points: examples/agents/basic-agent.py, examples/agents/memory.py, examples/agents/middleware.py, examples/agents/structured-output.py, examples/agents/agent_as_tool.py, examples/tools/approval_example.py, examples/agents/computer_use.py, and the notebooks under examples/notebooks/ including 01_basic_agent.ipynb, which has a Colab badge. Observability examples sit in examples/otel/ and memory examples in examples/memory/. Because the material here does not include the install command or the required Python version, treat both as things to confirm from the repository before you start, rather than assuming a version from the book's prose.
Human-in-the-loop, middleware and the approval example
The Chapter 4 learning outcome lists tools, memory, streaming, middleware, observability and human-in-the-loop as the things you build. The presence of examples/tools/approval_example.py is the concrete signal that human approval is treated as a first-class step in the tool execution path rather than an afterthought bolted on at the UI layer. Middleware gets its own example at examples/agents/middleware.py, which suggests a request or response interception point you can extend without editing the agent class. Structured output is handled in examples/agents/structured-output.py, and agent_as_tool.py covers the pattern where one agent is exposed to another as a callable tool. Those four examples together describe the extension surface: you change behaviour by wrapping or composing, not by subclassing the core loop. That is the right shape for a teaching framework, because a reader can see exactly where a hook fires. The v0.4.0 release notes list hooks, compaction, context tools and benchmarks, so the interception surface has grown since the earlier releases.
Workflows, computer use, and where the abstraction stops
Chapter 6 points at picoagents/src/picoagents/workflow/ and the examples/workflows/ directory, and Chapter 2 frames the split as coordination strategies, workflows versus autonomous. That distinction is the most useful thing the repository teaches, because it forces a decision before code: a workflow has a graph you can draw and test, while an autonomous agent decides its own next step and is correspondingly harder to bound. Chapter 5 covers computer use agents under picoagents/src/picoagents/agents/_computer_use/ with an example at examples/agents/computer_use.py, described as browser automation with multimodal reasoning. Browser automation is the case where the abstraction stops being free. Screenshots, page state and model latency dominate the loop, and no amount of clean orchestration code fixes a slow or flaky page. If your task is deterministic browser scripting, a conventional automation library will be cheaper to run and easier to debug than a multimodal agent loop.
Limitations you should assume going in
The honest limitation is stated by the project itself: PicoAgents exists for teaching. A framework built for clarity and transparency is not built for throughput, and the README makes no performance claim, so you should not read one into it. The chapter-to-directory structure means the code is coupled to a book's progression; when the book's narrative and the library's convenience conflict, the book wins. Documentation outside the book is thin in the material available here, which is a real cost if you arrive without the text. The release history shows a project still moving: v0.3.1 in November 2025, v0.3.2 in December 2025 with a fix to AgentResponse print output, and v0.4.0 in February 2026 adding hooks, compaction, context tools and benchmarks. A print-output fix landing as a patch release tells you the surface is still settling, and settling surfaces mean API churn for anyone pinning to a version. The repository is not archived and was pushed recently, so it is maintained, but maintenance by a book author follows a book's cadence.
AutoGen as the alternative, and the actual difference
AutoGen is the obvious comparison, and it appears in this repository's own topic list alongside agents and generative-ai. The difference is not features, it is who owns the loop. AutoGen gives you a maintained framework with its own abstraction for conversable agents and group chat; you adopt its vocabulary and its release cycle, and you get the benefit of other people debugging the same runtime. PicoAgents gives you the loop itself in picoagents/src/picoagents/agents/_agent.py, which you can read end to end in one sitting. If you need to ship an agent feature next month and your team already knows AutoGen, the from-scratch framework is the wrong tool because you will spend time understanding code that was written to be understood rather than to be depended on. If you need to reason about why an agent chose a tool, or you are teaching a team how these systems work, reading the implementation beats reading another framework's documentation. The book's own argument is that patterns outlive frameworks, and that argument only holds if you have seen the pattern implemented at least once without a framework in the way.
Licence, upgrades and what to verify first
The repository is Apache-2.0. That permits commercial use and modification and includes an explicit patent grant, but it also carries notice and attribution obligations, and the identifier alone does not tell you what the LICENSE file actually says or whether any bundled example assets carry different terms. Read the file rather than the badge. On upgrade cost, the version history suggests small but real churn between minor releases, so pin a version and read the release notes before moving, particularly around v0.4.0 given that hooks and compaction touch the extension surface the examples rely on. Verify three things before you build anything on top: that the Codespaces quickstart still opens, that the Python version and dependency set in picoagents/ match your environment, and that the specific example closest to your use case (approval_example.py for human approval, computer_use.py for browser work) runs unmodified on your machine. If any of those three fails, the book is still worth reading and the code is not yet worth depending on.
Editorial conclusion
Adopt PicoAgents if you are working through the book or need a readable reference implementation of agent loops, middleware and workflow orchestration that you can step through line by line. Do not adopt it as a production dependency for a system whose uptime matters more than your understanding of it. Before committing, check whether the GitHub Codespaces quickstart still resolves, confirm the Python version and dependency set in the repository, and read the Apache-2.0 LICENSE file in full rather than relying on the identifier alone.
Community notes