agentbyte 0.2.1__tar.gz → 0.2.4__tar.gz

{agentbyte-0.2.1 → agentbyte-0.2.4}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.2.3] - 2026-03-02
+
+### Changed
+- Unified `Conversation` and `Workspace` into a single `Session` model. Both were structurally identical; domain semantics now live in `Session.metadata` (e.g. `{"name": "Blog Post"}`).
+- `session.py` now contains `Session(Entity)`, `BaseSession(ABC)`, and `InMemorySession` — flat pattern mirroring `memory/base.py`.
+- `AgentContext.conversation_id` field removed. `session_id: Optional[str]` (already present) is the sole context-level session link.
+
+### Removed
+- `src/agentbyte/conversation/` module and all exports (`Conversation`, `BaseConversation`, `InMemoryConversation`).
+- `src/agentbyte/workspace/` module and all exports (`Workspace`, `BaseWorkspace`, `InMemoryWorkspace`).
+- `tests/test_conversation.py`, `tests/test_workspace.py`, `tests/agents/test_agent_conversation_integration.py`.
+
+### Added
+- `tests/test_session.py` — 19 tests covering `Session` identity/equality, `to_context()`/`from_context()`, `InMemorySession` CRUD, copy-safety, and ABC contract.
+
+### Reorganized
+- Notebooks moved from flat layout into `notebooks/agent/`, `notebooks/auth/`, and `notebooks/usecase/` subdirectories.
+
 ## [0.2.1] - 2026-02-27
 
 ### Changed

{agentbyte-0.2.1 → agentbyte-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.2.1
+Version: 0.2.4
 Summary: A toolkit for designing multiagent systems
 Project-URL: Homepage, https://gitlab.com/pyninja/aiengineering/agentbyte
 Project-URL: Repository, https://gitlab.com/pyninja/aiengineering/agentbyte
@@ -10,6 +10,7 @@ Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.12
+Requires-Dist: pydantic-settings>=2.13.0
 Requires-Dist: pydantic>=2.12.5
 Provides-Extra: all
 Requires-Dist: azure-identity>=1.25.1; extra == 'all'
@@ -28,6 +29,10 @@ Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+</p>
+
 # Agentbyte
 
 Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.

{agentbyte-0.2.1 → agentbyte-0.2.4}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+</p>
+
 # Agentbyte
 
 Agentbyte is a Python toolkit for building and studying multiagent systems with a learning-first, implementation-oriented workflow.

{agentbyte-0.2.1 → agentbyte-0.2.4}/docs/progress.md

@@ -268,3 +268,40 @@ Middleware parity with picoagents (Chapter 4.9), plus Agent integration.
   - `git push origin v0.2.0`
 5. Publish (if desired):
   - `uv publish`
+
+---
+
+## Update (2026-03-02, Session Unification — Conversation/Workspace Removed)
+
+### Design Decision
+
+`Conversation` and `Workspace` were structurally identical (`name` was the only difference and
+belongs in `metadata`). Introducing two separate types, two ABCs, two in-memory adapters,
+and a `conversation_id: Optional[UUID]` field on `AgentContext` was over-engineering.
+
+Consolidated into a single unified model:
+
+- `session.py` now contains `Session`, `BaseSession`, `InMemorySession` (flat, mirrors `memory/base.py`)
+- `AgentContext.conversation_id` removed — `session_id: str` (already present) is sufficient
+- Callers use `metadata` for domain semantics (e.g. `metadata={"name": "Blog Post"}` for workspace-like sessions)
+
+### Source Changes
+
+- `src/agentbyte/session.py` — rewritten: `Session(Entity)` + `BaseSession(ABC)` + `InMemorySession`
+- `src/agentbyte/conversation/` — **deleted**
+- `src/agentbyte/workspace/` — **deleted**
+- `src/agentbyte/context.py` — `conversation_id` field and `UUID` import removed
+- `src/agentbyte/__init__.py` — exports updated: `Session`, `BaseSession`, `InMemorySession`
+
+### Tests
+
+- `tests/test_conversation.py` — **deleted**
+- `tests/test_workspace.py` — **deleted**
+- `tests/agents/test_agent_conversation_integration.py` — **deleted**
+- `tests/test_package_api.py` — `test_conversation_import_paths` replaced with `test_session_import_paths`
+- `tests/test_session.py` — **new**: 15 tests covering `Session` model, `to_context()`/`from_context()`, `InMemorySession` CRUD, copy-safety, and ABC contract
+
+### Validation Run
+
+- Ruff: `All checks passed!`
+- Pytest: **253 passed** (`uv run pytest tests/ -q`)

{agentbyte-0.2.1 → agentbyte-0.2.4}/docs/study/topic_agents.md

@@ -12,6 +12,7 @@ This file now contains **agents-only** study material.
 - Memory content moved to [docs/study/topic_memory.md](../study/topic_memory.md)
 - Middleware content moved to [docs/study/topic_middleware.md](../study/topic_middleware.md)
 - Approval deep dive moved to [docs/study/topic_approval.md](../study/topic_approval.md)
+- Session persistence (unified) → `src/agentbyte/session.py` (`Session`, `BaseSession`, `InMemorySession`)
 - Study gaps are tracked at the end of this same document.
 
 ---
@@ -78,6 +79,32 @@ Common checkpoints:
 3. Before tool execution
 4. During long-running operations linked to futures/tasks
 
+### 4.12 Context Engineering
+
+> "If the LLM is the CPU, then the context window is RAM." — Andrej Karpathy
+
+As agents execute multi-step tasks, context grows with every tool call, memory retrieval, and conversation turn. Without management this causes two problems:
+
+- **Context rot** — performance degrades as token count approaches the model's attention limit (empirically around 32K tokens).
+- **Context explosion** — a long tool-heavy run can accumulate 20K+ tokens, pushing system instructions out of the attention window.
+
+**Four management strategies (Chapter 4.12.3):**
+
+| Strategy | Mechanism | Where in Agentbyte |
+|---|---|---|
+| Compaction | Summarise + trim old messages at model-call time | `ContextCompactionMiddleware` |
+| Active memory management | Agent explicitly writes/deletes knowledge via tool | `MemoryTool` (6-command CRUD) |
+| Context isolation | Specialist agents run in their own context bubble | `AgentAsTool` / `result_strategy` |
+| Tool result filtering | Truncate large tool outputs before appending to context | Future: agent `_execute_tool_call` hook |
+
+**Empirical token reduction (from the book):**
+
+- Baseline (no management): 21,633 tokens
+- Compaction middleware: 7,276 tokens (−66%)
+- Isolation via agents-as-tools: 5,892 tokens (−73%)
+
+Key takeaway: architectural prevention (isolation) outperforms reactive trimming (compaction).
+
 ---
 
 ## Part 2: Agentbyte Implementation Mapping
@@ -90,6 +117,10 @@ Common checkpoints:
 - `src/agentbyte/agents/types.py`
 - `src/agentbyte/context.py`
 - `src/agentbyte/cancellation_token.py`
+- `src/agentbyte/session.py` — `Session`, `BaseSession`, `InMemorySession` unified session persistence
+
+- `src/agentbyte/middleware/base.py` — `ContextCompactionMiddleware`, `OperationType`
+- `src/agentbyte/tools/memory_tool.py` — `MemoryBackend`, `MemoryTool` (6 commands)
 
 ### Current Behavior Highlights
 
@@ -100,6 +131,81 @@ Common checkpoints:
 - Middleware-integrated model/tool execution now uses event-aware `execute_stream(...)`
 - Middleware events can flow through `run_stream(...)` and pause execution via `ToolApprovalEvent`
 - Token-level streaming is auto-disabled when middleware is configured (picoagents-aligned fallback)
+- Agent operation strings are constants via `OperationType` enum (`MODEL_CALL`, `TOOL_CALL`, etc.)
+
+### ContextCompactionMiddleware — How It Works
+
+**File:** `src/agentbyte/middleware/base.py`
+
+The middleware hooks into the `process_request` phase of every `model_call` operation. It does nothing for `tool_call` or other operations.
+
+**Decision point:**
+
+```
+estimated_tokens = total_chars_of_all_message_content ÷ 4
+if estimated_tokens > max_tokens:
+    apply compaction
+```
+
+The `÷ 4` heuristic avoids a hard tiktoken dependency. It can be swapped for an exact tokeniser in production.
+
+**Compaction output structure:**
+
+```
+[messages[0], SystemMessage("[Previous context summarized...]"), *messages[-keep_last:]]
+```
+
+- `messages[0]` — the original system/first message is always preserved.
+- `SystemMessage(...)` — a placeholder that signals to the model that prior context was trimmed.
+- `messages[-keep_last:]` — the most recent `keep_last` messages (default 10) are retained verbatim.
+
+**Constructor:**
+
+```python
+ContextCompactionMiddleware(
+    max_tokens: int = 32_000,   # trigger threshold
+    keep_last: int = 10,        # messages to retain from tail
+)
+```
+
+**Metadata written on compaction:**
+
+```python
+context.metadata["compaction_applied"]        = True
+context.metadata["original_message_count"]    = len(messages)
+context.metadata["compacted_message_count"]   = len(compacted)
+```
+
+**Usage:**
+
+```python
+from agentbyte.middleware import ContextCompactionMiddleware
+
+agent = Agent(
+    name="researcher",
+    model_client=llm,
+    tools=[...],
+    middlewares=[ContextCompactionMiddleware(max_tokens=16_000, keep_last=8)],
+)
+```
+
+Combine with `AgentAsTool` for maximum reduction: the specialist compacts internally while the coordinator only ever sees the `result_strategy`-filtered summary.
+
+### OperationType Enum
+
+**File:** `src/agentbyte/middleware/base.py`
+
+`OperationType(str, Enum)` replaces bare string literals for the `operation` field on `MiddlewareContext`. Values remain plain strings so existing middleware that checks `context.operation == "model_call"` continues to work unchanged.
+
+```python
+class OperationType(str, Enum):
+    MODEL_CALL    = "model_call"
+    TOOL_CALL     = "tool_call"
+    MEMORY_ACCESS = "memory_access"
+    APPROVAL      = "approval"
+```
+
+The agent now passes `OperationType.MODEL_CALL` and `OperationType.TOOL_CALL` into `middleware_chain.execute_stream(...)`. Middleware can branch on either the enum or the string — both compare equal.
 
 ---
 
@@ -133,6 +239,14 @@ Common checkpoints:
 - [x] Resume after `approve_tool(...)`
 - [x] Handle denial after `deny_tool(...)`
 
+### ✅ Context Engineering (Chapter 4.12)
+
+- [x] `ContextCompactionMiddleware` — model-call intercept with token estimation and tail-keep strategy
+- [x] `OperationType` enum — canonical operation constants, backward-compatible with plain strings
+- [x] Context isolation via `AgentAsTool` + `result_strategy` (Chapter 4.11)
+- [x] Agent-managed memory via `MemoryTool` 6-command CRUD (Chapter 4.8)
+- [ ] Tool result filtering hook inside `_execute_tool_call` (optional, future)
+
 ---
 
 ## Summary
@@ -164,12 +278,13 @@ For memory and middleware deep dives, use the dedicated topic files listed at th
 - base memory abstractions and models
 - list/file memory implementations
 - tests and examples
+- `MemoryTool` / `MemoryBackend` with picoagents 6-command set (`view`, `create`, `str_replace`, `insert`, `delete`, `rename`)
+- path-traversal sandbox and security validation
 
 #### Remaining Gaps
 
 - [ ] component serialization parity for memory classes/configs
 - [ ] vector memory backend(s)
-- [ ] agent-managed memory tool (`MemoryTool`) and security-tested file operations
 
 ### Middleware
 
@@ -181,12 +296,14 @@ For memory and middleware deep dives, use the dedicated topic files listed at th
 - middleware `execute_stream(...)` parity baseline
 - middleware event propagation in agent streaming path
 - middleware pause handling (`ToolApprovalEvent`) in agent loop
+- `OperationType(str, Enum)` — canonical operation constants with backward compat
+- `ContextCompactionMiddleware` — model-call token budget trimming (Chapter 4.12.3)
 
 #### Remaining Gaps
 
 - [ ] approval middleware (optional centralization)
 - [ ] caching middleware (optional)
-- [ ] operation-level observability conventions for middleware events
+- [ ] tool result filtering hook inside agent execution loop (Chapter 4.12.3)
 
 ### Observability / Production
 

{agentbyte-0.2.1 → agentbyte-0.2.4}/docs/study/topic_tools.md

@@ -1571,6 +1571,176 @@ if __name__ == "__main__":
 
 ---
 
+## Part 6: MemoryTool — Agent-Managed Persistent Memory
+
+### Motivation
+
+Agents often need to remember information across sessions or across many turns within a single session. There are two memory models:
+
+- **Application-managed memory** (`BaseMemory` subclasses): the framework decides what to store and retrieve — transparent to the agent.
+- **Agent-managed memory** (`MemoryTool`): the agent explicitly calls a tool to read, write, and organise its own knowledge files — the agent is in full control.
+
+`MemoryTool` implements the second model. It mirrors the six file-system-style commands from Chapter 4.8.3 / picoagents `_memory_tool.py`.
+
+### Architecture: Two Classes
+
+```
+MemoryBackend   ← pure Python, no async, operates on the real filesystem
+     ↑
+MemoryTool      ← BaseTool subclass, wraps MemoryBackend, async execute()
+```
+
+Separating storage logic (`MemoryBackend`) from the tool interface (`MemoryTool`) makes each class easy to test independently and allows future backends (e.g. in-memory, remote) without changing the tool layer.
+
+### The Six Commands
+
+| Command | Required params | Optional params | Purpose |
+|---|---|---|---|
+| `view` | `path` | — | Read file content; list directory; `"/"` lists entire root |
+| `create` | `path`, `file_text` | — | Write (or overwrite) a file; creates parent dirs automatically |
+| `str_replace` | `path`, `old_str`, `new_str` | — | Replace **first occurrence** of `old_str` with `new_str` |
+| `insert` | `path`, `insert_line`, `insert_text` | — | Insert text after 1-based line number |
+| `delete` | `path` | — | Remove a file |
+| `rename` | `path`, `new_path` | — | Move / rename a file within the sandbox |
+
+### Security: Sandbox Model
+
+All paths are validated by `MemoryBackend._validate_path()`:
+
+```python
+def _validate_path(self, path: str) -> Path:
+    normalized = path.strip().lstrip("/")   # strip leading slashes
+    if not normalized:
+        raise ValueError("path cannot be empty")
+    full_path = (self.base_path / normalized).resolve()
+    try:
+        full_path.relative_to(self.base_path)   # raises if outside
+    except ValueError as exc:
+        raise ValueError("Access denied: path is outside memory directory") from exc
+    return full_path
+```
+
+**Key points:**
+- Leading `/` is stripped — `"/etc/passwd"` becomes `"etc/passwd"` inside the sandbox, not the real `/etc/passwd`.
+- `Path.resolve()` expands `..` — `"../../etc/passwd"` resolves outside `base_path` and raises `ValueError`.
+- `view("/")` is special-cased **before** `_validate_path` is called, so it lists the root without hitting the empty-path guard.
+
+### MemoryBackend Key Design Decisions
+
+**`create` (auto-mkdir):**
+```python
+def create(self, path: str, file_text: str) -> str:
+    target = self._validate_path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)  # ← auto-create subdirs
+    target.write_text(file_text, encoding="utf-8")
+    return f"Created: {path}"
+```
+
+**`str_replace` (first occurrence only):**
+```python
+def str_replace(self, path: str, old_str: str, new_str: str) -> str:
+    content = target.read_text(encoding="utf-8")
+    if old_str not in content:
+        raise ValueError(f"String not found in file: {old_str!r}")
+    updated = content.replace(old_str, new_str, 1)  # ← count=1
+    target.write_text(updated, encoding="utf-8")
+    return f"Replaced in: {path}"
+```
+Replacing only the *first* occurrence is intentional: it makes the edit deterministic and avoids unintended bulk replacements — the same design choice picoagents makes.
+
+**`insert` (1-based line numbers):**
+```python
+def insert(self, path: str, insert_line: int, insert_text: str) -> str:
+    lines = target.read_text(encoding="utf-8").splitlines(keepends=True)
+    # insert_line=0 → prepend; insert_line=len(lines) → append
+    lines.insert(insert_line, text)
+    target.write_text("".join(lines), encoding="utf-8")
+```
+Python's `list.insert(i, v)` treats `i` as the index *before* which to insert, so `insert_line=3` places text after line 3 (0-indexed slot 3 = after the 3rd line). The guard `0 <= insert_line <= len(lines)` keeps the range valid.
+
+### MemoryTool Parameters Schema
+
+The tool exposes all six commands as a single `command` enum plus optional per-command fields:
+
+```python
+@property
+def parameters(self) -> Dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "enum": ["view", "create", "str_replace", "insert", "delete", "rename"],
+            },
+            "path":        {"type": "string"},
+            "file_text":   {"type": "string"},        # create
+            "old_str":     {"type": "string"},        # str_replace
+            "new_str":     {"type": "string"},        # str_replace
+            "insert_line": {"type": "integer"},       # insert
+            "insert_text": {"type": "string"},        # insert
+            "new_path":    {"type": "string"},        # rename
+        },
+        "required": ["command"],   # ← only command is always required
+    }
+```
+
+Only `command` is globally required; per-command fields are validated at runtime inside `execute()` via `_require_str()` / `isinstance(insert_line, int)`.
+
+### Usage Example
+
+```python
+import asyncio
+from agentbyte.tools import MemoryTool
+
+async def demo():
+    mem = MemoryTool(base_path="/tmp/agent_memory")
+
+    # Create a file
+    r = await mem.execute({"command": "create", "path": "notes.md",
+                           "file_text": "# Notes\nFirst note."})
+    print(r.result)   # Created: notes.md
+
+    # Read it back
+    r = await mem.execute({"command": "view", "path": "notes.md"})
+    print(r.result)   # # Notes\nFirst note.
+
+    # Patch a line
+    r = await mem.execute({"command": "str_replace", "path": "notes.md",
+                           "old_str": "First note.", "new_str": "Updated note."})
+    print(r.result)   # Replaced in: notes.md
+
+    # Insert a new line after line 1
+    r = await mem.execute({"command": "insert", "path": "notes.md",
+                           "insert_line": 1, "insert_text": "Second note."})
+
+    # List all memory files
+    r = await mem.execute({"command": "view", "path": "/"})
+    print(r.result)   # ['notes.md']
+
+    # Rename
+    r = await mem.execute({"command": "rename", "path": "notes.md",
+                           "new_path": "archive/notes.md"})
+
+    # Delete
+    r = await mem.execute({"command": "delete", "path": "archive/notes.md"})
+
+asyncio.run(demo())
+```
+
+### Difference from Old (4-Command) MemoryTool
+
+| Old command | New equivalent |
+|---|---|
+| `read_knowledge` | `view` |
+| `write_knowledge` | `create` |
+| `list_knowledge` | `view` on directory path (or `view("/")`) |
+| `delete_knowledge` | `delete` |
+| *(missing)* | `str_replace` |
+| *(missing)* | `insert` |
+| *(missing)* | `rename` |
+
+---
+
 ## Part 5: Parity Checklist with picoagents
 
 ### ✅ BaseTool Interface
@@ -1615,6 +1785,20 @@ if __name__ == "__main__":
 - [x] Streaming tool outputs are forwarded and finalized into `ToolMessage` via `ToolResult`
 - [x] Covered by agent tests (`tests/agents/test_agent_basic.py`)
 
+### ✅ MemoryTool (Agent-Managed Memory)
+- [x] `MemoryBackend` class — pure Python, no async, real filesystem operations
+- [x] `MemoryTool` class — `BaseTool` subclass, async `execute()` dispatch
+- [x] `view` — file content OR directory listing; `view("/")` lists full root
+- [x] `create` — write/overwrite file, parent dirs auto-created
+- [x] `str_replace` — replaces **first occurrence** only (deterministic)
+- [x] `insert` — insert text after 1-based line number (0 = prepend, `len` = append)
+- [x] `delete` — remove file (directory deletion not allowed via this command)
+- [x] `rename` — move/rename within sandbox, validates both src and dst
+- [x] `_validate_path` sandbox — strips leading `/`, `resolve()` + `relative_to()` check
+- [x] `_require_str` helper — uniform required-field validation in `execute()`
+- [x] Parameters schema has `command` as only globally-required field
+- [x] 30+ tests in `tests/tools/test_memory_tool.py` covering all commands and security edge cases
+
 ---
 
 ## Summary
@@ -1627,7 +1811,6 @@ This study document provides:
 4. **Usage Examples**: Practical demonstrations of all features
 5. **Validation**: Test script to verify correctness
 6. **Parity Checklist**: Verification that Agentbyte matches picoagents capabilities
+7. **MemoryTool**: Agent-managed persistent file memory with 6-command picoagents-parity set, sandbox security, and full test coverage
 
-The implementation is ready to be added to `src/agentbyte/tools/` following the code provided in Part 3.
-
-Tool system is implemented in `src/agentbyte/tools/` and integrated with `Agent` execution paths.
+Tool system is fully implemented in `src/agentbyte/tools/` and integrated with `Agent` execution paths.

{agentbyte-0.2.1/notebooks → agentbyte-0.2.4/notebooks/concepts/agent}/01-tools-example.ipynb

@@ -16,7 +16,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "id": "f7df8759",
    "metadata": {},
    "outputs": [],
@@ -38,14 +38,14 @@
    "id": "406d7dd7",
    "metadata": {},
    "source": [
-    "## Understanding ToolResult\n",
+    "## Example 1a: Understanding ToolResult\n",
     "\n",
-    "`ToolResult` is the standardized structure for all tool execution outcomes. It's a Pydantic BaseModel with immutable fields.\n"
+    "`ToolResult` is the standardized structure for all tool execution outcomes. It's a Pydantic BaseModel with immutable fields."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 2,
    "id": "17c1e655",
    "metadata": {},
    "outputs": [
@@ -112,7 +112,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "f414f5ac",
    "metadata": {},
    "outputs": [
@@ -149,20 +149,12 @@
    "id": "ba737a65",
    "metadata": {},
    "source": [
-    "## Example 2: @tool Decorator (No Parentheses)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "28cf2bc4",
-   "metadata": {},
-   "source": [
-    "## Example 1b: ToolResult and Error Handling"
+    "## Example 1b: Error Handling with FunctionTool"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "id": "df267ff3",
    "metadata": {},
    "outputs": [
@@ -200,9 +192,17 @@
     "await test_error_handling()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "fc9a8a3b",
+   "metadata": {},
+   "source": [
+    "## Example 2a: @tool Decorator (No Parentheses)"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 5,
    "id": "e1f229c0",
    "metadata": {},
    "outputs": [
@@ -234,9 +234,17 @@
     "print(f\"\\nDirect call: multiply_numbers(4, 5) = {direct_result}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "bc29534f",
+   "metadata": {},
+   "source": [
+    "## Example 2b: Executing @tool Decorator"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 6,
    "id": "cf74f858",
    "metadata": {},
    "outputs": [
@@ -262,12 +270,12 @@
    "id": "366fb111",
    "metadata": {},
    "source": [
-    "## Example 3: @tool Decorator (With Parentheses)"
+    "## Example 3a: @tool Decorator (With Parentheses)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 7,
    "id": "56a451e5",
    "metadata": {},
    "outputs": [
@@ -322,9 +330,17 @@
     "print(f\"Approval Mode is ALWAYS: {reset_admin.approval_mode == ApprovalMode.ALWAYS}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "91525edb",
+   "metadata": {},
+   "source": [
+    "## Example 3b: Executing Tools with Approval"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 8,
    "id": "1ca85e41",
    "metadata": {},
    "outputs": [