Add observability, checkpointing, and tool approval features

Major Features:
- OpenTelemetry integration following Gen-AI semantic conventions
- Workflow checkpoint system with file and memory storage backends
- Tool approval system with @tool decorator and ApprovalMode support
- Enhanced middleware pipeline with approval flow hooks
- Context management improvements and agent context support
- Memory tools and comprehensive examples

Infrastructure:
- Add poethepoet for task automation (poe test, poe check, etc.)
- Add OpenTelemetry optional dependencies group
- Enhanced Web UI with tool approval banners and example tasks display
- Improved debug panel with detailed execution traces

Examples:
- Memory management examples (examples/memory/)
- OpenTelemetry instrumentation examples (examples/otel/)
- Tool approval workflow examples (examples/tools/)
- Workflow checkpointing examples (examples/workflows/)

Testing:
- Add tests for memory tool functionality
- Add tests for OpenTelemetry integration
- Add tests for tool approval system
- Reorganize workflow tests to tests/workflow/

Cleanup:
- Remove deprecated planning tools module
- Clean up old workflow test files from src
- Update frontend build artifacts

Author: victordibia

.gitignore

@@ -6,18 +6,28 @@ __pycache__/
 *$py.class
 CLAUDE.md
 *.DS_Store
-
+checkpoints/*
 */work_dir
 .chainlit
-.files 
+.files
 chainlit.md
 *.env
 /data*
-.run_samples.sh 
+.run_samples.sh
 tests/test_fresh_install.sh
 
 
 test_fresh_install.sh
+
+# Agent example artifacts - created when running agent examples
+agent_workspace/
+agent_memory/
+*_workspace/
+*_memory/
+*.json
+!pyproject.toml
+!package.json
+!tsconfig.json
 # C extensions
 *.so
 

README.md

@@ -6,7 +6,7 @@ Official code repository for [Designing Multi-Agent Systems: Principles, Pattern
 
 ![Designing Multi-Agent Systems](./docs/images/bookcover.png)
 
-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 so you can understand exactly how production systems are built.
+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](https://buy.multiagentbook.com) | [🛒 Buy Print - Coming Soon]()
 
@@ -39,7 +39,7 @@ The book is organized across 4 parts, taking you from theory to production:
 
 | Chapter  | Title                                 | Code                                                                                                                                                                                                                                                                                                                                                                                                                                    | Learning Outcome                                                                          |
 | -------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| **Ch 4** | Building Your First Agent             | [`agents/_agent.py`](picoagents/src/picoagents/agents/_agent.py), [`basic-agent.py`](examples/agents/basic-agent.py), [`memory.py`](examples/agents/memory.py), [`middleware.py`](examples/agents/middleware.py) <br> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/victordibia/designing-multiagent-systems/blob/main/examples/notebooks/01_basic_agent.ipynb) | Create production agents with tools, memory, streaming, and middleware                    |
+| **Ch 4** | Building Your First Agent             | [`agents/_agent.py`](picoagents/src/picoagents/agents/_agent.py), [`basic-agent.py`](examples/agents/basic-agent.py), [`memory.py`](examples/agents/memory.py), [`middleware.py`](examples/agents/middleware.py) <br> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/victordibia/designing-multiagent-systems/blob/main/examples/notebooks/01_basic_agent.ipynb) | Build agents with tools, memory, streaming, and middleware                    |
 | **Ch 5** | Computer Use Agents                   | [`agents/_computer_use/`](picoagents/src/picoagents/agents/_computer_use/), [`computer_use.py`](examples/agents/computer_use.py)                                                                                                                                                                                                                                                                                                        | Build browser automation agents with multimodal reasoning                                 |
 | **Ch 5** | Building Multi-Agent Workflows        | [`workflow/`](picoagents/src/picoagents/workflow/), [`data_visualization/`](examples/workflows/data_visualization/)                                                                                                                                                                                                                                                                                                                     | Build type-safe workflows with streaming observability                                    |
 | **Ch 6** | Autonomous Multi-Agent Orchestration  | [`orchestration/`](picoagents/src/picoagents/orchestration/), [`round-robin.py`](examples/orchestration/round-robin.py), [`ai-driven.py`](examples/orchestration/ai-driven.py), [`plan-based.py`](examples/orchestration/plan-based.py)                                                                                                                                                                                                 | Implement GroupChat, LLM-driven, and plan-based orchestration (Magentic One patterns)     |
@@ -62,7 +62,7 @@ The book is organized across 4 parts, taking you from theory to production:
 
 ### Option 1: Interactive Notebooks
 
-Click Colab badges in the chapter tables below to run examples in your browser. No installation required.
+Click Colab badges in the chapter tables above to run examples in your browser. No installation required.
 
 ### Option 2: GitHub Codespaces
 
@@ -204,12 +204,14 @@ examples/
 
 ## Key Features
 
-🎯 **Production Patterns**
+🎯 **Production-Ready Patterns**
 
-- Two-stage filtering: Reduce LLM costs by 90% (YC Analysis case study)
-- Structured outputs: Eliminate hallucination with Pydantic models
-- Checkpointing: Resumable workflows with state persistence
-- Think tool: Structured reasoning for 54% performance improvement
+Illustrated through real-world case studies (see [YC Analysis workflow](examples/workflows/yc_analysis/)):
+
+- Cost optimization: Two-stage filtering for 90% LLM cost reduction
+- Type safety: Structured outputs with Pydantic validation
+- Reliability: Checkpointing and resumable workflows
+- Advanced reasoning: Think tool for improved problem-solving (54% performance gain)
 
 🖥️ **Computer Use Agents**
 
@@ -237,8 +239,8 @@ examples/
 
 This repository implements every concept from the book. The book provides the theory, design trade-offs, and production considerations you need to build effective multi-agent systems.
 
-- Digital Edition - [Link](https://buy.multiagentbook.com)
-- Buy Print Edition on [Amazon - Coming Soon]()
+- [Buy Digital Edition](https://buy.multiagentbook.com)
+- Buy Print Edition on Amazon - Coming Soon
 
 ## Questions and Feedback
 

examples/agents/agent_as_tool.py

@@ -62,6 +62,9 @@ def tool_agents():
     instructions="You solve tasks by delegating to the relevant agents or tools",
     model_client=model_client,
     tools=[weather_agent.as_tool(), analysis_agent.as_tool()],
+    example_tasks=[
+        "Get the current weather in New York and analyze recent sales data.",
+        "Provide a brief report on the weather in San Francisco and its impact on outdoor events.",]
 )
 
 

examples/agents/basic-agent.py

@@ -33,6 +33,12 @@ def calculate(expression: str) -> str:
     instructions="You are a helpful assistant with access to weather and calculation tools. Use them when appropriate.",
     model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
     tools=[get_weather, calculate],
+    example_tasks=[
+        "What's the weather in San Francisco?",
+        "Calculate 125 * 48",
+        "What's the weather in Tokyo and what's 15% of 240?",
+        "Is it sunny in London?",
+    ],
 )
 
 

examples/agents/middleware_custom.py

@@ -357,7 +357,7 @@ def get_metrics(self) -> Dict:
 
         return metrics
 
-    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+    async def process_request(self, context: MiddlewareContext):
         """Start operation tracking."""
         context.metadata["start_time"] = datetime.now()
 
@@ -369,21 +369,21 @@ async def process_request(self, context: MiddlewareContext) -> MiddlewareContext
             if context.operation == "model_call" and isinstance(context.data, list):
                 logger.info(f"   Context size: {len(context.data)} messages")
 
-        return context
+        yield context
 
-    async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
+    async def process_response(self, context: MiddlewareContext, result: Any):
         """Record successful operation."""
         duration = (datetime.now() - context.metadata["start_time"]).total_seconds()
         self._record_metric(context.operation, duration, success=True)
 
         if self.enable_detailed_logging:
             logger.info(f"✅ Completed {context.operation} in {duration:.3f}s")
 
-        return result
+        yield result
 
     async def process_error(
         self, context: MiddlewareContext, error: Exception
-    ) -> Optional[Any]:
+    ):
         """Record failed operation."""
         duration = (datetime.now() - context.metadata["start_time"]).total_seconds()
         self._record_metric(context.operation, duration, success=False)
@@ -392,6 +392,7 @@ async def process_error(
         logger.error(f"❌ Failed {context.operation} after {duration:.3f}s: {error_msg}")
 
         raise error
+        yield  # pragma: no cover
 
 
 # =============================================================================