deepagents 0.3.6__py3-none-any.whl → 0.3.7a1__py3-none-any.whl

deepagents/backends/filesystem.py

@@ -1,11 +1,4 @@
-"""FilesystemBackend: Read and write files directly from the filesystem.
-
-Security and search upgrades:
-- Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
-- Prevent symlink-following on file I/O using O_NOFOLLOW when available
-- Ripgrep-powered grep with JSON parsing, plus Python fallback with regex
-  and optional glob include filtering, while preserving virtual path behavior
-"""
+"""`FilesystemBackend`: Read and write files directly from the filesystem."""
 
 import json
 import os
@@ -49,9 +42,20 @@ class FilesystemBackend(BackendProtocol):
         """Initialize filesystem backend.
 
         Args:
-            root_dir: Optional root directory for file operations. If provided,
-                     all file paths will be resolved relative to this directory.
-                     If not provided, uses the current working directory.
+            root_dir: Optional root directory for file operations.
+
+                If provided, all file paths will be resolved relative to this directory.
+                If not provided, uses the current working directory.
+            virtual_mode: Enables sandboxed operation where all paths are treated as
+                virtual paths rooted at `root_dir`.
+
+                Path traversal (using `..` or `~`) is disallowed and all resolved paths
+                must remain within the root directory. When `False` (default), absolute
+                paths are allowed as-is and relative paths resolve under cwd.
+            max_file_size_mb: Maximum file size in megabytes for operations like
+                grep's Python fallback search.
+
+                Files exceeding this limit are skipped during search. Defaults to 10 MB.
         """
         self.cwd = Path(root_dir).resolve() if root_dir else Path.cwd()
         self.virtual_mode = virtual_mode
@@ -60,16 +64,22 @@ class FilesystemBackend(BackendProtocol):
     def _resolve_path(self, key: str) -> Path:
         """Resolve a file path with security checks.
 
-        When virtual_mode=True, treat incoming paths as virtual absolute paths under
-        self.cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
-        When virtual_mode=False, preserve legacy behavior: absolute paths are allowed
+        When `virtual_mode=True`, treat incoming paths as virtual absolute paths under
+        `self.cwd`, disallow traversal (`..`, `~`) and ensure resolved path stays within
+        root.
+
+        When `virtual_mode=False`, preserve legacy behavior: absolute paths are allowed
         as-is; relative paths resolve under cwd.
 
         Args:
-            key: File path (absolute, relative, or virtual when virtual_mode=True)
+            key: File path (absolute, relative, or virtual when `virtual_mode=True`).
 
         Returns:
-            Resolved absolute Path object
+            Resolved absolute `Path` object.
+
+        Raises:
+            ValueError: If path traversal is attempted in `virtual_mode` or if the
+                resolved path escapes the root directory.
         """
         if self.virtual_mode:
             vpath = key if key.startswith("/") else "/" + key
@@ -94,8 +104,9 @@ class FilesystemBackend(BackendProtocol):
             path: Absolute directory path to list files from.
 
         Returns:
-            List of FileInfo-like dicts for files and directories directly in the directory.
-            Directories have a trailing / in their path and is_dir=True.
+            List of `FileInfo`-like dicts for files and directories directly in the
+                directory. Directories have a trailing `/` in their path and
+                `is_dir=True`.
         """
         dir_path = self._resolve_path(path)
         if not dir_path.exists() or not dir_path.is_dir():
@@ -242,7 +253,14 @@ class FilesystemBackend(BackendProtocol):
         content: str,
     ) -> WriteResult:
         """Create a new file with content.
-        Returns WriteResult. External storage sets files_update=None.
+
+        Args:
+            file_path: Path where the new file will be created.
+            content: Text content to write to the file.
+
+        Returns:
+            `WriteResult` with path on success, or error message if the file
+                already exists or write fails. External storage sets `files_update=None`.
         """
         resolved_path = self._resolve_path(file_path)
 
@@ -273,7 +291,18 @@ class FilesystemBackend(BackendProtocol):
         replace_all: bool = False,
     ) -> EditResult:
         """Edit a file by replacing string occurrences.
-        Returns EditResult. External storage sets files_update=None.
+
+        Args:
+            file_path: Path to the file to edit.
+            old_string: The text to search for and replace.
+            new_string: The replacement text.
+            replace_all: If `True`, replace all occurrences. If `False` (default),
+                replace only if exactly one occurrence exists.
+
+        Returns:
+            `EditResult` with path and occurrence count on success, or error
+                message if file not found or replacement fails. External storage sets
+                `files_update=None`.
         """
         resolved_path = self._resolve_path(file_path)
 
@@ -311,6 +340,19 @@ class FilesystemBackend(BackendProtocol):
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
+        """Search for a regex pattern in files.
+
+        Uses ripgrep if available, falling back to Python regex search.
+
+        Args:
+            pattern: Regular expression pattern to search for.
+            path: Directory or file path to search in. Defaults to current directory.
+            glob: Optional glob pattern to filter which files to search.
+
+        Returns:
+            List of GrepMatch dicts containing path, line number, and matched text.
+            Returns an error string if the regex pattern is invalid.
+        """
         # Validate regex
         try:
             re.compile(pattern)
@@ -338,6 +380,17 @@ class FilesystemBackend(BackendProtocol):
         return matches
 
     def _ripgrep_search(self, pattern: str, base_full: Path, include_glob: str | None) -> dict[str, list[tuple[int, str]]] | None:
+        """Search using ripgrep with JSON output parsing.
+
+        Args:
+            pattern: Regex pattern to search for.
+            base_full: Resolved base path to search in.
+            include_glob: Optional glob pattern to filter files.
+
+        Returns:
+            Dict mapping file paths to list of `(line_number, line_text)` tuples.
+                Returns `None` if ripgrep is unavailable or times out.
+        """
         cmd = ["rg", "--json"]
         if include_glob:
             cmd.extend(["--glob", include_glob])
@@ -383,6 +436,18 @@ class FilesystemBackend(BackendProtocol):
         return results
 
     def _python_search(self, pattern: str, base_full: Path, include_glob: str | None) -> dict[str, list[tuple[int, str]]]:
+        """Fallback search using Python regex when ripgrep is unavailable.
+
+        Recursively searches files, respecting `max_file_size_bytes` limit.
+
+        Args:
+            pattern: Regex pattern to search for.
+            base_full: Resolved base path to search in.
+            include_glob: Optional glob pattern to filter files by name.
+
+        Returns:
+            Dict mapping file paths to list of `(line_number, line_text)` tuples.
+        """
         try:
             regex = re.compile(pattern)
         except re.error:
@@ -392,7 +457,10 @@ class FilesystemBackend(BackendProtocol):
         root = base_full if base_full.is_dir() else base_full.parent
 
         for fp in root.rglob("*"):
-            if not fp.is_file():
+            try:
+                if not fp.is_file():
+                    continue
+            except (PermissionError, OSError):
                 continue
             if include_glob and not wcglob.globmatch(fp.name, include_glob, flags=wcglob.BRACE):
                 continue
@@ -419,6 +487,16 @@ class FilesystemBackend(BackendProtocol):
         return results
 
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern to match files against (e.g., `'*.py'`, `'**/*.txt'`).
+            path: Base directory to search from. Defaults to root (`/`).
+
+        Returns:
+            List of `FileInfo` dicts for matching files, sorted by path. Each dict
+                contains `path`, `is_dir`, `size`, and `modified_at` fields.
+        """
         if pattern.startswith("/"):
             pattern = pattern.lstrip("/")
 
@@ -432,7 +510,7 @@ class FilesystemBackend(BackendProtocol):
             for matched_path in search_path.rglob(pattern):
                 try:
                     is_file = matched_path.is_file()
-                except OSError:
+                except (PermissionError, OSError):
                     continue
                 if not is_file:
                     continue

deepagents/backends/sandbox.py

@@ -172,7 +172,7 @@ try:
     with os.scandir(path) as it:
         for entry in it:
             result = {{
-                'path': entry.name,
+                'path': os.path.join(path, entry.name),
                 'is_dir': entry.is_dir(follow_symlinks=False)
             }}
             print(json.dumps(result))

deepagents/backends/store.py

@@ -279,6 +279,30 @@ class StoreBackend(BackendProtocol):
 
         return format_read_response(file_data, offset, limit)
 
+    async def aread(
+        self,
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000,
+    ) -> str:
+        """Async version of read using native store async methods.
+
+        This avoids sync calls in async context by using store.aget directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+        item: Item | None = await store.aget(namespace, file_path)
+
+        if item is None:
+            return f"Error: File '{file_path}' not found"
+
+        try:
+            file_data = self._convert_store_item_to_file_data(item)
+        except ValueError as e:
+            return f"Error: {e}"
+
+        return format_read_response(file_data, offset, limit)
+
     def write(
         self,
         file_path: str,
@@ -301,6 +325,29 @@ class StoreBackend(BackendProtocol):
         store.put(namespace, file_path, store_value)
         return WriteResult(path=file_path, files_update=None)
 
+    async def awrite(
+        self,
+        file_path: str,
+        content: str,
+    ) -> WriteResult:
+        """Async version of write using native store async methods.
+
+        This avoids sync calls in async context by using store.aget/aput directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+
+        # Check if file exists using async method
+        existing = await store.aget(namespace, file_path)
+        if existing is not None:
+            return WriteResult(error=f"Cannot write to {file_path} because it already exists. Read and then make an edit, or write to a new path.")
+
+        # Create new file using async method
+        file_data = create_file_data(content)
+        store_value = self._convert_file_data_to_store_value(file_data)
+        await store.aput(namespace, file_path, store_value)
+        return WriteResult(path=file_path, files_update=None)
+
     def edit(
         self,
         file_path: str,
@@ -338,6 +385,44 @@ class StoreBackend(BackendProtocol):
         store.put(namespace, file_path, store_value)
         return EditResult(path=file_path, files_update=None, occurrences=int(occurrences))
 
+    async def aedit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Async version of edit using native store async methods.
+
+        This avoids sync calls in async context by using store.aget/aput directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+
+        # Get existing file using async method
+        item = await store.aget(namespace, file_path)
+        if item is None:
+            return EditResult(error=f"Error: File '{file_path}' not found")
+
+        try:
+            file_data = self._convert_store_item_to_file_data(item)
+        except ValueError as e:
+            return EditResult(error=f"Error: {e}")
+
+        content = file_data_to_string(file_data)
+        result = perform_string_replacement(content, old_string, new_string, replace_all)
+
+        if isinstance(result, str):
+            return EditResult(error=result)
+
+        new_content, occurrences = result
+        new_file_data = update_file_data(file_data, new_content)
+
+        # Update file in store using async method
+        store_value = self._convert_file_data_to_store_value(new_file_data)
+        await store.aput(namespace, file_path, store_value)
+        return EditResult(path=file_path, files_update=None, occurrences=int(occurrences))
+
     # Removed legacy grep() convenience to keep lean surface
 
     def grep_raw(

deepagents/backends/utils.py

@@ -15,7 +15,7 @@ import wcmatch.glob as wcglob
 from deepagents.backends.protocol import FileInfo as _FileInfo, GrepMatch as _GrepMatch
 
 EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
-MAX_LINE_LENGTH = 10000
+MAX_LINE_LENGTH = 5000
 LINE_NUMBER_WIDTH = 6
 TOOL_RESULT_TOKEN_LIMIT = 20000  # Same threshold as eviction
 TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]"

deepagents/graph.py

@@ -12,6 +12,7 @@ from langchain.chat_models import init_chat_model
 from langchain_anthropic import ChatAnthropic
 from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
 from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import SystemMessage
 from langchain_core.tools import BaseTool
 from langgraph.cache.base import BaseCache
 from langgraph.graph.state import CompiledStateGraph
@@ -45,7 +46,7 @@ def create_deep_agent(
     model: str | BaseChatModel | None = None,
     tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
     *,
-    system_prompt: str | None = None,
+    system_prompt: str | SystemMessage | None = None,
     middleware: Sequence[AgentMiddleware] = (),
     subagents: list[SubAgent | CompiledSubAgent] | None = None,
     skills: list[str] | None = None,
@@ -83,7 +84,7 @@ def create_deep_agent(
             file management, and subagent spawning.
         system_prompt: The additional instructions the agent should have.
 
-            Will go in the system prompt.
+            Will go in the system prompt. Can be a string or a `SystemMessage`.
         middleware: Additional middleware to apply after standard middleware.
         subagents: The subagents to use.
 
@@ -202,9 +203,23 @@ def create_deep_agent(
     if interrupt_on is not None:
         deepagent_middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))
 
+    # Combine system_prompt with BASE_AGENT_PROMPT
+    if system_prompt is None:
+        final_system_prompt: str | SystemMessage = BASE_AGENT_PROMPT
+    elif isinstance(system_prompt, SystemMessage):
+        # SystemMessage: append BASE_AGENT_PROMPT to content_blocks
+        new_content = [
+            *system_prompt.content_blocks,
+            {"type": "text", "text": f"\n\n{BASE_AGENT_PROMPT}"},
+        ]
+        final_system_prompt = SystemMessage(content=new_content)
+    else:
+        # String: simple concatenation
+        final_system_prompt = system_prompt + "\n\n" + BASE_AGENT_PROMPT
+
     return create_agent(
         model,
-        system_prompt=system_prompt + "\n\n" + BASE_AGENT_PROMPT if system_prompt else BASE_AGENT_PROMPT,
+        system_prompt=final_system_prompt,
         tools=tools,
         middleware=deepagent_middleware,
         response_format=response_format,

deepagents/middleware/_utils.py

@@ -0,0 +1,23 @@
+"""Utility functions for middleware."""
+
+from langchain_core.messages import SystemMessage
+
+
+def append_to_system_message(
+    system_message: SystemMessage | None,
+    text: str,
+) -> SystemMessage:
+    """Append text to a system message.
+
+    Args:
+        system_message: Existing system message or None.
+        text: Text to add to the system message.
+
+    Returns:
+        New SystemMessage with the text appended.
+    """
+    new_content: list[str | dict[str, str]] = list(system_message.content_blocks) if system_message else []
+    if new_content:
+        text = f"\n\n{text}"
+    new_content.append({"type": "text", "text": text})
+    return SystemMessage(content=new_content)

deepagents/middleware/filesystem.py

@@ -33,12 +33,12 @@ from deepagents.backends.utils import (
     sanitize_tool_call_id,
     truncate_if_too_long,
 )
+from deepagents.middleware._utils import append_to_system_message
 
 EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
-MAX_LINE_LENGTH = 2000
 LINE_NUMBER_WIDTH = 6
 DEFAULT_READ_OFFSET = 0
-DEFAULT_READ_LIMIT = 500
+DEFAULT_READ_LIMIT = 100
 
 
 class FileData(TypedDict):
@@ -167,14 +167,14 @@ Assume this tool is able to read all files on the machine. If the User provides
 
 Usage:
 - The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 500 lines starting from the beginning of the file
+- By default, it reads up to 100 lines starting from the beginning of the file
 - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
   - First scan: read_file(path, limit=100) to see file structure
   - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
   - Only omit limit (read full file) when necessary for editing
 - Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
-- Any lines longer than 2000 characters will be truncated
 - Results are returned using cat -n format, with line numbers starting at 1
+- Lines longer than 5,000 characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
 - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
 - You should ALWAYS make sure a file has been read before editing it."""
@@ -373,7 +373,14 @@ def _read_file_tool_generator(
         """Synchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
         file_path = _validate_path(file_path)
-        return resolved_backend.read(file_path, offset=offset, limit=limit)
+        result = resolved_backend.read(file_path, offset=offset, limit=limit)
+
+        lines = result.splitlines(keepends=True)
+        if len(lines) > limit:
+            lines = lines[:limit]
+            result = "".join(lines)
+
+        return result
 
     async def async_read_file(
         file_path: str,
@@ -384,7 +391,14 @@ def _read_file_tool_generator(
         """Asynchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
         file_path = _validate_path(file_path)
-        return await resolved_backend.aread(file_path, offset=offset, limit=limit)
+        result = await resolved_backend.aread(file_path, offset=offset, limit=limit)
+
+        lines = result.splitlines(keepends=True)
+        if len(lines) > limit:
+            lines = lines[:limit]
+            result = "".join(lines)
+
+        return result
 
     return StructuredTool.from_function(
         name="read_file",
@@ -933,7 +947,8 @@ class FilesystemMiddleware(AgentMiddleware):
             system_prompt = "\n\n".join(prompt_parts)
 
         if system_prompt:
-            request = request.override(system_prompt=request.system_prompt + "\n\n" + system_prompt if request.system_prompt else system_prompt)
+            new_system_message = append_to_system_message(request.system_message, system_prompt)
+            request = request.override(system_message=new_system_message)
 
         return handler(request)
 
@@ -980,7 +995,8 @@ class FilesystemMiddleware(AgentMiddleware):
             system_prompt = "\n\n".join(prompt_parts)
 
         if system_prompt:
-            request = request.override(system_prompt=request.system_prompt + "\n\n" + system_prompt if request.system_prompt else system_prompt)
+            new_system_message = append_to_system_message(request.system_message, system_prompt)
+            request = request.override(system_message=new_system_message)
 
         return await handler(request)
 
@@ -1057,6 +1073,64 @@ class FilesystemMiddleware(AgentMiddleware):
         )
         return processed_message, result.files_update
 
+    async def _aprocess_large_message(
+        self,
+        message: ToolMessage,
+        resolved_backend: BackendProtocol,
+    ) -> tuple[ToolMessage, dict[str, FileData] | None]:
+        """Async version of _process_large_message.
+
+        Uses async backend methods to avoid sync calls in async context.
+        See _process_large_message for full documentation.
+        """
+        # Early exit if eviction not configured
+        if not self.tool_token_limit_before_evict:
+            return message, None
+
+        # Convert content to string once for both size check and eviction
+        # Special case: single text block - extract text directly for readability
+        if (
+            isinstance(message.content, list)
+            and len(message.content) == 1
+            and isinstance(message.content[0], dict)
+            and message.content[0].get("type") == "text"
+            and "text" in message.content[0]
+        ):
+            content_str = str(message.content[0]["text"])
+        elif isinstance(message.content, str):
+            content_str = message.content
+        else:
+            # Multiple blocks or non-text content - stringify entire structure
+            content_str = str(message.content)
+
+        # Check if content exceeds eviction threshold
+        # Using 4 chars per token as a conservative approximation (actual ratio varies by content)
+        # This errs on the high side to avoid premature eviction of content that might fit
+        if len(content_str) <= 4 * self.tool_token_limit_before_evict:
+            return message, None
+
+        # Write content to filesystem using async method
+        sanitized_id = sanitize_tool_call_id(message.tool_call_id)
+        file_path = f"/large_tool_results/{sanitized_id}"
+        result = await resolved_backend.awrite(file_path, content_str)
+        if result.error:
+            return message, None
+
+        # Create truncated preview for the replacement message
+        content_sample = format_content_with_line_numbers([line[:1000] for line in content_str.splitlines()[:10]], start_line=1)
+        replacement_text = TOO_LARGE_TOOL_MSG.format(
+            tool_call_id=message.tool_call_id,
+            file_path=file_path,
+            content_sample=content_sample,
+        )
+
+        # Always return as plain string after eviction
+        processed_message = ToolMessage(
+            content=replacement_text,
+            tool_call_id=message.tool_call_id,
+        )
+        return processed_message, result.files_update
+
     def _intercept_large_tool_result(self, tool_result: ToolMessage | Command, runtime: ToolRuntime) -> ToolMessage | Command:
         """Intercept and process large tool results before they're added to state.
 
@@ -1113,6 +1187,52 @@ class FilesystemMiddleware(AgentMiddleware):
             return Command(update={**update, "messages": processed_messages, "files": accumulated_file_updates})
         raise AssertionError(f"Unreachable code reached in _intercept_large_tool_result: for tool_result of type {type(tool_result)}")
 
+    async def _aintercept_large_tool_result(self, tool_result: ToolMessage | Command, runtime: ToolRuntime) -> ToolMessage | Command:
+        """Async version of _intercept_large_tool_result.
+
+        Uses async backend methods to avoid sync calls in async context.
+        See _intercept_large_tool_result for full documentation.
+        """
+        if isinstance(tool_result, ToolMessage):
+            resolved_backend = self._get_backend(runtime)
+            processed_message, files_update = await self._aprocess_large_message(
+                tool_result,
+                resolved_backend,
+            )
+            return (
+                Command(
+                    update={
+                        "files": files_update,
+                        "messages": [processed_message],
+                    }
+                )
+                if files_update is not None
+                else processed_message
+            )
+
+        if isinstance(tool_result, Command):
+            update = tool_result.update
+            if update is None:
+                return tool_result
+            command_messages = update.get("messages", [])
+            accumulated_file_updates = dict(update.get("files", {}))
+            resolved_backend = self._get_backend(runtime)
+            processed_messages = []
+            for message in command_messages:
+                if not isinstance(message, ToolMessage):
+                    processed_messages.append(message)
+                    continue
+
+                processed_message, files_update = await self._aprocess_large_message(
+                    message,
+                    resolved_backend,
+                )
+                processed_messages.append(processed_message)
+                if files_update is not None:
+                    accumulated_file_updates.update(files_update)
+            return Command(update={**update, "messages": processed_messages, "files": accumulated_file_updates})
+        raise AssertionError(f"Unreachable code reached in _aintercept_large_tool_result: for tool_result of type {type(tool_result)}")
+
     def wrap_tool_call(
         self,
         request: ToolCallRequest,
@@ -1151,4 +1271,4 @@ class FilesystemMiddleware(AgentMiddleware):
             return await handler(request)
 
         tool_result = await handler(request)
-        return self._intercept_large_tool_result(tool_result, request.runtime)
+        return await self._aintercept_large_tool_result(tool_result, request.runtime)

deepagents/middleware/memory.py

@@ -53,7 +53,6 @@ import logging
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Annotated, NotRequired, TypedDict
 
-from langchain.messages import SystemMessage
 from langchain_core.runnables import RunnableConfig
 
 if TYPE_CHECKING:
@@ -69,6 +68,8 @@ from langchain.agents.middleware.types import (
 from langchain.tools import ToolRuntime
 from langgraph.runtime import Runtime
 
+from deepagents.middleware._utils import append_to_system_message
+
 logger = logging.getLogger(__name__)
 
 
@@ -354,23 +355,20 @@ class MemoryMiddleware(AgentMiddleware):
         return MemoryStateUpdate(memory_contents=contents)
 
     def modify_request(self, request: ModelRequest) -> ModelRequest:
-        """Inject memory content into the system prompt.
+        """Inject memory content into the system message.
 
         Args:
             request: Model request to modify.
 
         Returns:
-            Modified request with memory injected into system prompt.
+            Modified request with memory injected into system message.
         """
         contents = request.state.get("memory_contents", {})
         agent_memory = self._format_agent_memory(contents)
 
-        if request.system_prompt:
-            system_prompt = agent_memory + "\n\n" + request.system_prompt
-        else:
-            system_prompt = agent_memory
+        new_system_message = append_to_system_message(request.system_message, agent_memory)
 
-        return request.override(system_message=SystemMessage(system_prompt))
+        return request.override(system_message=new_system_message)
 
     def wrap_model_call(
         self,

deepagents/middleware/skills.py

@@ -114,6 +114,8 @@ from langchain_core.runnables import RunnableConfig
 from langgraph.prebuilt import ToolRuntime
 from langgraph.runtime import Runtime
 
+from deepagents.middleware._utils import append_to_system_message
+
 logger = logging.getLogger(__name__)
 
 # Security: Maximum size for SKILL.md files to prevent DoS attacks (10MB)
@@ -563,13 +565,13 @@ class SkillsMiddleware(AgentMiddleware):
         return "\n".join(lines)
 
     def modify_request(self, request: ModelRequest) -> ModelRequest:
-        """Inject skills documentation into a model request's system prompt.
+        """Inject skills documentation into a model request's system message.
 
         Args:
             request: Model request to modify
 
         Returns:
-            New model request with skills documentation injected into system prompt
+            New model request with skills documentation injected into system message
         """
         skills_metadata = request.state.get("skills_metadata", [])
         skills_locations = self._format_skills_locations()
@@ -580,12 +582,9 @@ class SkillsMiddleware(AgentMiddleware):
             skills_list=skills_list,
         )
 
-        if request.system_prompt:
-            system_prompt = request.system_prompt + "\n\n" + skills_section
-        else:
-            system_prompt = skills_section
+        new_system_message = append_to_system_message(request.system_message, skills_section)
 
-        return request.override(system_prompt=system_prompt)
+        return request.override(system_message=new_system_message)
 
     def before_agent(self, state: SkillsState, runtime: Runtime, config: RunnableConfig) -> SkillsStateUpdate | None:
         """Load skills metadata before agent execution (synchronous).

deepagents/middleware/subagents.py

@@ -13,6 +13,8 @@ from langchain_core.runnables import Runnable
 from langchain_core.tools import StructuredTool
 from langgraph.types import Command
 
+from deepagents.middleware._utils import append_to_system_message
+
 
 class SubAgent(TypedDict):
     """Specification for an agent.
@@ -84,7 +86,16 @@ class CompiledSubAgent(TypedDict):
     """What this subagent does."""
 
     runnable: Runnable
-    """The Runnable to use for the agent. Must return a state with a 'messages' key."""
+    """A custom agent implementation.
+
+    Create a custom agent using either:
+
+    1. LangChain's `create_agent()`: https://docs.langchain.com/oss/python/langchain/quickstart
+    2. A custom graph using langgraph: https://docs.langchain.com/oss/python/langgraph/quickstart
+
+    If you're creating a custom graph, make sure the state schema includes a 'messages' key.
+    This is required for the subagent to communicate results back to the main agent.
+    """
 
 
 DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools."
@@ -513,10 +524,10 @@ class SubAgentMiddleware(AgentMiddleware):
         request: ModelRequest,
         handler: Callable[[ModelRequest], ModelResponse],
     ) -> ModelResponse:
-        """Update the system prompt to include instructions on using subagents."""
+        """Update the system message to include instructions on using subagents."""
         if self.system_prompt is not None:
-            system_prompt = request.system_prompt + "\n\n" + self.system_prompt if request.system_prompt else self.system_prompt
-            return handler(request.override(system_prompt=system_prompt))
+            new_system_message = append_to_system_message(request.system_message, self.system_prompt)
+            return handler(request.override(system_message=new_system_message))
         return handler(request)
 
     async def awrap_model_call(
@@ -524,8 +535,8 @@ class SubAgentMiddleware(AgentMiddleware):
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelResponse:
-        """(async) Update the system prompt to include instructions on using subagents."""
+        """(async) Update the system message to include instructions on using subagents."""
         if self.system_prompt is not None:
-            system_prompt = request.system_prompt + "\n\n" + self.system_prompt if request.system_prompt else self.system_prompt
-            return await handler(request.override(system_prompt=system_prompt))
+            new_system_message = append_to_system_message(request.system_message, self.system_prompt)
+            return await handler(request.override(system_message=new_system_message))
         return await handler(request)

{deepagents-0.3.6.dist-info → deepagents-0.3.7a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.3.6
+Version: 0.3.7a1
 Summary: General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph.
 License: MIT
 Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
@@ -46,7 +46,7 @@ poetry add deepagents
 
 ## Usage
 
-> **Note:** `deepagents` requires using a LLM that supports [tool calling](https://python.langchain.com/docs/concepts/tool_calling/).
+> **Note:** `deepagents` requires using a LLM that supports [tool calling](https://docs.langchain.com/oss/python/langchain/overview).
 
 This example uses [Tavily](https://tavily.com/) as an example search provider, but you can substitute any search API (e.g., DuckDuckGo, SerpAPI, Brave Search). To run the example below, you will need to `pip install tavily-python`.
 
@@ -125,7 +125,7 @@ There are several parameters you can pass to `create_deep_agent` to create your
 
 ### `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/).
+By default, `deepagents` uses `claude-sonnet-4-5-20250929`. You can customize this by passing any [LangChain model object](https://docs.langchain.com/oss/python/integrations/providers/overview).
 
 > **Tip:** Use the `provider:model` format (e.g., `openai:gpt-5`) to quickly switch between models. See the [reference](https://reference.langchain.com/python/langchain/models/#langchain.chat_models.init_chat_model(model)) for more info.
 
@@ -237,6 +237,7 @@ class CompiledSubAgent(TypedDict):
 ```
 
 **`SubAgent` fields:**
+
 - **name**: This is the name of the subagent, and how the main agent will call the subagent
 - **description**: This is the description of the subagent that is shown to the main agent
 - **system_prompt**: This is the system prompt used for the subagent
@@ -246,6 +247,7 @@ class CompiledSubAgent(TypedDict):
 - **interrupt_on** A custom interrupt config that specifies human-in-the-loop interactions for your tools.
 
 **CompiledSubAgent fields:**
+
 - **name**: This is the name of the subagent, and how the main agent will call the subagent
 - **description**: This is the description of the subagent that is shown to the main agent  
 - **runnable**: A pre-built LangGraph graph/agent that will be used as the subagent. **Important:** The runnable's state schema must include a `messages` key. This is required for the subagent to communicate results back to the main agent.

deepagents-0.3.7a1.dist-info/RECORD

@@ -0,0 +1,21 @@
+deepagents/__init__.py,sha256=LHQm0v_7N9Gd4pmpRjhnlOCMIK2O0jQ4cEU8RiXEI8k,447
+deepagents/graph.py,sha256=Rk1qDzPpjSKGHc1NJ1CQcbFrFoMlPgKIGFm2EWW3--0,9802
+deepagents/backends/__init__.py,sha256=BOKu2cQ1OdMyO_l2rLqZQiXppYFmQbx7OIQb7WYwvZc,457
+deepagents/backends/composite.py,sha256=WZ_dnn63BmrU19ZJ5-m728f99pSa0Uq_CnwZjwmxz1U,26198
+deepagents/backends/filesystem.py,sha256=Okr4zUJkDc_tx01Sya8sHTsYzahsRiDdFWWX2A_G-RQ,24617
+deepagents/backends/protocol.py,sha256=HUmIrwYGduPfDcs_wtOzVU2QPA9kICZuGO-sUwxzz5I,15997
+deepagents/backends/sandbox.py,sha256=PE4-DkVRU5Z3zp4NViHCkNHUHKiFUKh55UAXCicBvRo,10884
+deepagents/backends/state.py,sha256=Qq4uRjKg6POEqLl4tNnWnXzbmLBpu3bZdMkcUROIgHw,7899
+deepagents/backends/store.py,sha256=9gdUQqPWChYgHVoopOUaocUdyUbFBpf-PxhTiXRXCto,18219
+deepagents/backends/utils.py,sha256=CE_HXddNTr954auqFIVgYLLD4Gdsfr9U8b384g07Wuc,13932
+deepagents/middleware/__init__.py,sha256=2smUxjwghA3Eml_wp0kd4dAY-rwLyW-XQPBE3dAoo50,467
+deepagents/middleware/_utils.py,sha256=ojy62kQLASQ2GabevWJaPGLItyccdNxLMPpYV25Lf20,687
+deepagents/middleware/filesystem.py,sha256=z6jrmXuksloebN6ZlNbjKw847AC8IjLS-TYz6ELyXFY,52745
+deepagents/middleware/memory.py,sha256=1w-laeDHCiY0hxf5fURFnwcXvI78FhPo7_mYjvZudWE,15826
+deepagents/middleware/patch_tool_calls.py,sha256=PdNhxPaQqwnFkhEAZEE2kEzadTNAOO3_iJRA30WqpGE,1981
+deepagents/middleware/skills.py,sha256=3UhHWGzVlmX6qubvhFTx14LUhd6-ZK6nhkhxV8XrIMQ,24045
+deepagents/middleware/subagents.py,sha256=jU1a45CTlMNz1D3U9f3V5J2AoWzKMDXOf-55N6PNG00,26596
+deepagents-0.3.7a1.dist-info/METADATA,sha256=P8TN8XaOCgNTfy9R-7VLgVMl7S1WkAggGqJqtmubAj0,19764
+deepagents-0.3.7a1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+deepagents-0.3.7a1.dist-info/top_level.txt,sha256=drAzchOzPNePwpb3_pbPuvLuayXkN7SNqeIKMBWJoAo,11
+deepagents-0.3.7a1.dist-info/RECORD,,

deepagents-0.3.6.dist-info/RECORD

@@ -1,20 +0,0 @@
-deepagents/__init__.py,sha256=LHQm0v_7N9Gd4pmpRjhnlOCMIK2O0jQ4cEU8RiXEI8k,447
-deepagents/graph.py,sha256=oqcL-H14t-oYxc7RvMkNCge1twVjqogFcLCzH-4vSdc,9161
-deepagents/backends/__init__.py,sha256=BOKu2cQ1OdMyO_l2rLqZQiXppYFmQbx7OIQb7WYwvZc,457
-deepagents/backends/composite.py,sha256=WZ_dnn63BmrU19ZJ5-m728f99pSa0Uq_CnwZjwmxz1U,26198
-deepagents/backends/filesystem.py,sha256=kGBFuW3ie0LLz4wXCPGJm3WAiYpimJTgEwodJSnXWCs,21477
-deepagents/backends/protocol.py,sha256=HUmIrwYGduPfDcs_wtOzVU2QPA9kICZuGO-sUwxzz5I,15997
-deepagents/backends/sandbox.py,sha256=8Bi8itqjW2PpXORlIfT8thMN1aBXExgHz8cm8xwVaxI,10864
-deepagents/backends/state.py,sha256=Qq4uRjKg6POEqLl4tNnWnXzbmLBpu3bZdMkcUROIgHw,7899
-deepagents/backends/store.py,sha256=0mmeTsim4J8bjcf62dljwNrDv4PavT2KHdGbaBzVzRE,15197
-deepagents/backends/utils.py,sha256=wXMzfrUxp-ZAKlbl3QFZXlSSPRmIXQIUEehqsy2Agy8,13933
-deepagents/middleware/__init__.py,sha256=2smUxjwghA3Eml_wp0kd4dAY-rwLyW-XQPBE3dAoo50,467
-deepagents/middleware/filesystem.py,sha256=Qx9NuRZPNuK1NVYomPCRauDY0ZqZ5j_wro9MRYyvcx0,47563
-deepagents/middleware/memory.py,sha256=E1UAtBAyIxkyNHuG2-j_X_fClMbbSwobdKa3e_P0FDk,15883
-deepagents/middleware/patch_tool_calls.py,sha256=PdNhxPaQqwnFkhEAZEE2kEzadTNAOO3_iJRA30WqpGE,1981
-deepagents/middleware/skills.py,sha256=EABvIq4ES_NHGFL9USUnlH1WwiZgnAacoOLz2kkkVkw,24043
-deepagents/middleware/subagents.py,sha256=c_JxFb2Z3yBWEInqNEciC9Rlu4uGo1tpuN9tLXivWeY,26196
-deepagents-0.3.6.dist-info/METADATA,sha256=KpjDBOFZXmVrZYfuec3UiFsm193LLjfkigSlFhULJE4,19743
-deepagents-0.3.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-deepagents-0.3.6.dist-info/top_level.txt,sha256=drAzchOzPNePwpb3_pbPuvLuayXkN7SNqeIKMBWJoAo,11
-deepagents-0.3.6.dist-info/RECORD,,