docs(deepagents): document custom state schemas (#4194)

Author: open-swe[bot]

pipeline/preprocessors/link_map.py

@@ -34,6 +34,7 @@ class LinkMap(TypedDict):
             "langchain_text_splitters": "langchain-text-splitters/",
             # Deep Agents
             "create_deep_agent": "deepagents/graph/create_deep_agent",
+            "DeepAgentState": "deepagents/graph/DeepAgentState",
             "SubAgent": "deepagents/middleware/subagents/SubAgent",
             "CompiledSubAgent": "deepagents/middleware/subagents/CompiledSubAgent",
             "SubAgentMiddleware": "deepagents/middleware/subagents/SubAgentMiddleware",

src/oss/deepagents/context-engineering.mdx

@@ -306,6 +306,51 @@ const result = await agent.invoke(
 
 Runtime context **propagates to all subagents**. When a subagent runs, it receives the same runtime context as the parent. See [Subagents](/oss/deepagents/subagents#context-management) for per-subagent context (namespaced keys).
 
+:::python
+## Custom state schema
+
+<Note>
+    Custom state schemas require `deepagents>=0.6.6`.
+</Note>
+
+Use `state_schema` when data must be part of the agent's mutable graph state, checkpointed with the thread, or available through `runtime.state`. For immutable per-run inputs such as user IDs, credentials, or feature flags, prefer [runtime context](#runtime-context).
+
+Custom state schemas must subclass @[DeepAgentState]. This preserves the built-in `DeltaChannel` reducer on `messages`, which keeps checkpoint growth linear as conversations get longer.
+
+```python
+from deepagents import DeepAgentState, create_deep_agent
+from langchain.tools import ToolRuntime, tool
+
+
+class ResearchState(DeepAgentState):
+    page_url: str
+    file_urls: list[str]
+
+
+@tool
+def cite_page(runtime: ToolRuntime) -> str:
+    """Return the current page URL."""
+    return runtime.state["page_url"]
+
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    tools=[cite_page],
+    state_schema=ResearchState,
+)
+
+result = agent.invoke(
+    {
+        "messages": [{"role": "user", "content": "Cite the current page"}],
+        "page_url": "https://example.com/report",
+        "file_urls": [],
+    }
+)
+```
+
+The schema is merged with state schemas contributed by middleware. Declarative @[SubAgent] specs passed to `subagents=` inherit the parent `state_schema` when Deep Agents compiles them for the `task` tool. @[CompiledSubAgent] runnables and remote @[AsyncSubAgent] specs do not inherit it because their graphs are already compiled or hosted separately. Compile those graphs with a compatible schema if they need the same state fields.
+:::
+
 ## Context compression
 
 Long-running tasks produce large tool outputs and long conversation history.

src/oss/deepagents/customization.mdx

@@ -78,6 +78,7 @@ agent = create_deep_agent(
 | [`middleware=`](#middleware) | Extra middleware to add to the stack |
 | [`interrupt_on=`](#human-in-the-loop) | Pause before tool calls for human approval |
 | [`response_format=`](#structured-output) | Structured output schema |
+| [`state_schema=`](/oss/deepagents/context-engineering#custom-state-schema) | Custom graph state schema |
 | [profiles](#profiles) | Per-model defaults as a reusable bundle |
 
 <Accordion title="Full function signature">
@@ -491,12 +492,13 @@ Do **not** do this:
 
 :::python
 Mutation in place, such as modifying `self.x` in `before_agent` or changing other shared values in hooks, can lead to subtle bugs and race conditions because many operations run concurrently (subagents, parallel tools, and parallel invocations on different threads).
+
+For full details on extending state with custom properties, see [Custom middleware - Custom state schema](/oss/langchain/middleware/custom#custom-state-schema).
 :::
 :::js
 Mutation in place, such as modifying `state.x` in `beforeAgent`, mutating a shared variable in `beforeAgent`, or changing other shared values in hooks, can lead to subtle bugs and race conditions because many operations run concurrently (subagents, parallel tools, and parallel invocations on different threads).
 :::
 
-For full details on extending state with custom properties, see [Custom middleware - Custom state schema](/oss/langchain/middleware/custom#custom-state-schema).
 If you must use mutation in custom middleware, consider what happens when subagents, parallel tools, or concurrent agent invocations run at the same time.
 </Warning>
 

src/oss/javascript/integrations/providers/google.mdx

@@ -96,15 +96,15 @@ npm install @langchain/google-genai @langchain/core
 
 ### `@langchain/google-vertexai`
 
-The `@langchain/google-vertexai` package provides [`ChatVertexAI`](/oss/integrations/chat/google_vertex_ai), [`VertexAIEmbeddings`](/oss/integrations/embeddings/google_vertex_ai), and [`VertexAI`](/oss/integrations/llms/google_vertex_ai) for Vertex AI on Node.js. It depends on [`@langchain/google-gauth`](#langchaingoogle-gauth) for authentication. This package is superseded by the Vertex AI support built into `@langchain/google` for chat.
+The `@langchain/google-vertexai` package provides [`ChatVertexAI`](/oss/integrations/chat/google_vertex_ai), [`VertexAIEmbeddings`](/oss/integrations/embeddings/google_vertex_ai), and [`VertexAI`](/oss/integrations/llms/google_vertex_ai) for Vertex AI on Node.js. It depends on [`@langchain/google-gauth`](#%40langchain%2Fgoogle-gauth) for authentication. This package is superseded by the Vertex AI support built into `@langchain/google` for chat.
 
 ```bash
 npm install @langchain/google-vertexai @langchain/core
 ```
 
 ### `@langchain/google-vertexai-web`
 
-The `@langchain/google-vertexai-web` package provides the same Vertex AI chat, embedding, and LLM classes for browser and Edge runtimes. Install this package (not `@langchain/google-vertexai`) when running in web environments. It depends on [`@langchain/google-webauth`](#langchaingoogle-webauth).
+The `@langchain/google-vertexai-web` package provides the same Vertex AI chat, embedding, and LLM classes for browser and Edge runtimes. Install this package (not `@langchain/google-vertexai`) when running in web environments. It depends on [`@langchain/google-webauth`](#%40langchain%2Fgoogle-webauth).
 
 ```bash
 npm install @langchain/google-vertexai-web @langchain/core
@@ -120,7 +120,7 @@ Set service account JSON in `GOOGLE_WEB_CREDENTIALS` (or the deprecated `GOOGLE_
 
 ### `@langchain/google-gauth`
 
-The [`@langchain/google-gauth`](https://github.com/langchain-ai/langchainjs/tree/main/libs/providers/langchain-google-gauth) package provides Node.js authentication for legacy Google integrations built on [`@langchain/google-common`](#langchaingoogle-common). It is installed automatically when you add `@langchain/google-vertexai`—you typically do **not** install or import `@langchain/google-gauth` directly.
+The [`@langchain/google-gauth`](https://github.com/langchain-ai/langchainjs/tree/main/libs/providers/langchain-google-gauth) package provides Node.js authentication for legacy Google integrations built on [`@langchain/google-common`](#%40langchain%2Fgoogle-common). It is installed automatically when you add `@langchain/google-vertexai`—you typically do **not** install or import `@langchain/google-gauth` directly.
 
 On Node.js, credentials are resolved in this order: