diff --git a/src/oss/deepagents/backends.mdx b/src/oss/deepagents/backends.mdx
index 1d1c2d56bc..df93256c80 100644
--- a/src/oss/deepagents/backends.mdx
+++ b/src/oss/deepagents/backends.mdx
@@ -5,6 +5,22 @@ description: Choose and configure filesystem backends for deep agents. You can s
 
 Deep agents expose a filesystem surface to the agent via tools like `ls`, `read_file`, `write_file`, `edit_file`, `glob`, and `grep`. These tools operate through a pluggable backend.
 
+```mermaid
+graph TB
+    Tools[Filesystem Tools] --> Backend[Backend]
+
+    Backend --> State[State]
+    Backend --> Disk[Filesystem]
+    Backend --> Store[Store]
+    Backend --> Composite[Composite]
+    Backend --> Custom[Custom]
+
+    Composite --> Router{Routes}
+    Router --> State
+    Router --> Disk
+    Router --> Store
+```
+
 This page explains how to [choose a backend](#specify-a-backend), [route different paths to different backends](#route-to-different-backends), [implement your own virtual filesystem](#use-a-virtual-filesystem) (e.g., S3 or Postgres), [add policy hooks](#add-policy-hooks), and [comply with the backend protocol](#protocol-reference).
 
 ## Quickstart
diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx
index 6e50bbf008..d0b90651a3 100644
--- a/src/oss/deepagents/customization.mdx
+++ b/src/oss/deepagents/customization.mdx
@@ -4,6 +4,27 @@ sidebarTitle: Customization
 description: Learn how to customize deep agents with system prompts, tools, subagents, and more
 ---
 
+```mermaid
+graph LR
+    Create[create_deep_agent] --> Core[Core Config]
+    Create --> Features[Features]
+
+    Core --> Model[Model]
+    Core --> Prompt[System Prompt]
+    Core --> Tools[Tools]
+
+    Features --> Backend[Backend]
+    Features --> Sub[Subagents]
+    Features --> Interrupt[Interrupts]
+
+    Model --> Agent[Customized Agent]
+    Prompt --> Agent
+    Tools --> Agent
+    Backend --> Agent
+    Sub --> Agent
+    Interrupt --> Agent
+```
+
 ## Model
 
 By default, `deepagents` uses `"claude-sonnet-4-5-20250929"`. You can customize this by passing any [LangChain model object](https://python.langchain.com/docs/integrations/chat/).
diff --git a/src/oss/deepagents/harness.mdx b/src/oss/deepagents/harness.mdx
index 8b2878eac5..0e315ebb7a 100644
--- a/src/oss/deepagents/harness.mdx
+++ b/src/oss/deepagents/harness.mdx
@@ -5,6 +5,21 @@ sidebarTitle: Agent harness
 
 We think of `deepagents` as an "agent harness". It is the same core tool calling loop as other agent frameworks, but with built-in tools and capabilities.
 
+```mermaid
+graph TB
+    Agent[Deep Agent] --> Tools[File System Tools]
+    Agent --> Todo[To-Do List]
+    Agent --> Sub[Subagents]
+
+    Tools --> Backend[Storage Backend]
+    Backend --> State[State]
+    Backend --> Disk[Filesystem]
+    Backend --> Store[Store]
+
+    Sub --> |isolated work| Result[Final Result]
+    Result --> Agent
+```
+
 This page lists out the components that make up the agent harness.
 
 ## File system access
diff --git a/src/oss/deepagents/human-in-the-loop.mdx b/src/oss/deepagents/human-in-the-loop.mdx
index 822b1b8e42..b6068c3b46 100644
--- a/src/oss/deepagents/human-in-the-loop.mdx
+++ b/src/oss/deepagents/human-in-the-loop.mdx
@@ -5,6 +5,20 @@ description: Learn how to configure human approval for sensitive tool operations
 
 Some tool operations may be sensitive and require human approval before execution. Deep agents support human-in-the-loop workflows through LangGraph's interrupt capabilities. You can configure which tools require approval using the `interrupt_on` parameter.
 
+```mermaid
+graph LR
+    Agent[Agent] --> Check{Interrupt?}
+    Check --> |no| Execute[Execute]
+    Check --> |yes| Human{Human}
+
+    Human --> |approve| Execute
+    Human --> |edit| Execute
+    Human --> |reject| Cancel[Cancel]
+
+    Execute --> Agent
+    Cancel --> Agent
+```
+
 ## Basic configuration
 
 The `interrupt_on` parameter accepts a dictionary mapping tool names to interrupt configurations. Each tool can be configured with:
diff --git a/src/oss/deepagents/long-term-memory.mdx b/src/oss/deepagents/long-term-memory.mdx
index 001f5e12dd..ea42be2cb9 100644
--- a/src/oss/deepagents/long-term-memory.mdx
+++ b/src/oss/deepagents/long-term-memory.mdx
@@ -7,6 +7,17 @@ Deep agents come with a local filesystem to offload memory. By default, this fil
 
 You can extend deep agents with **long-term memory** by using a **CompositeBackend** that routes specific paths to persistent storage. This enables hybrid storage where some files persist across threads while others remain ephemeral.
 
+```mermaid
+graph LR
+    Agent[Deep Agent] --> Router{Path Router}
+
+    Router --> |/memories/*| Store[Store Backend]
+    Router --> |other| State[State Backend]
+
+    Store --> Persist[(Persistent<br/>across threads)]
+    State --> Ephemeral[(Ephemeral<br/>single thread)]
+```
+
 ## Setup
 
 Configure long-term memory by using a `CompositeBackend` that routes the `/memories/` path to a `StoreBackend`:
diff --git a/src/oss/deepagents/middleware.mdx b/src/oss/deepagents/middleware.mdx
index c931062548..17dab0b2fc 100644
--- a/src/oss/deepagents/middleware.mdx
+++ b/src/oss/deepagents/middleware.mdx
@@ -12,6 +12,17 @@ Deep agents are built with a modular middleware architecture. Deep agents have a
 
 Each feature is implemented as separate middleware. When you create a deep agent with `create_deep_agent`, we automatically attach `TodoListMiddleware`, `FilesystemMiddleware`, and `SubAgentMiddleware` to your agent.
 
+```mermaid
+graph LR
+    Agent[create_deep_agent] --> Todo[TodoList]
+    Agent --> FS[Filesystem]
+    Agent --> Sub[SubAgent]
+
+    Todo --> Tools[Agent Tools]
+    FS --> Tools
+    Sub --> Tools
+```
+
 Middleware is composable—you can add as many or as few middleware to an agent as needed. You can use any middleware independently.
 
 The following sections explain what each middleware provides.
diff --git a/src/oss/deepagents/subagents.mdx b/src/oss/deepagents/subagents.mdx
index 19e0b07480..ea8ce4c7f8 100644
--- a/src/oss/deepagents/subagents.mdx
+++ b/src/oss/deepagents/subagents.mdx
@@ -5,6 +5,21 @@ description: Learn how to use subagents to delegate work and keep context clean
 
 Deep agents can create subagents to delegate work. You can specify custom subagents in the `subagents` parameter. Subagents are useful for [context quarantine](https://www.dbreunig.com/2025/06/26/how-to-fix-your-context.html#context-quarantine) (keeping the main agent's context clean) and for providing specialized instructions.
 
+```mermaid
+graph TB
+    Main[Main Agent] --> |task tool| Sub[Subagent]
+
+    Sub --> Research[Research]
+    Sub --> Code[Code]
+    Sub --> General[General]
+
+    Research --> |isolated work| Result[Final Result]
+    Code --> |isolated work| Result
+    General --> |isolated work| Result
+
+    Result --> Main
+```
+
 ## Why use subagents?
 
 Subagents solve the **context bloat problem**. When agents use tools with large outputs (web search, file reads, database queries), the context window fills up quickly with intermediate results. Subagents isolate this detailed work—the main agent receives only the final result, not the dozens of tool calls that produced it.