Protocol reference required method: grep
grep(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> GrepResult must return structured matches. On error, return GrepResult(error="...") (do not raise).
LangChain · Deep Agents · all subjects
backends
31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Protocol reference required method: glob
glob(pattern: str, path: Optional[str] = None) -> GlobResult must return matched files as FileInfo entries (empty list if none).
Protocol reference required method: write
write(file_path: str, content: str) -> WriteResult must be create-only. On conflict, return WriteResult(error=...). On success, set path and for state backends set files_update={...}; external backends should use files_update=None.
Protocol reference required method: ls
ls(path: str) -> LsResult must return entries with at least path. Include is_dir, size, modified_at when available. Sort by path for deterministic output.
FilesystemBackend security risks and safeguards
FilesystemBackend grants agents direct filesystem read/write access. Security risks include: agents can read any accessible file including secrets (API keys, credentials, .env files); combined with network tools, secrets may be exfiltrated via SSRF attacks; file modifications are permanent and irreversible. Recommended safeguards: (1) Enable Human-in-the-Loop (HITL) middleware to review sensitive operations. (2) Exclude secrets from accessible filesystem paths, especially in CI/CD. (3) Use a sandbox backend for production environments requiring filesystem interaction. (4) Always use virtual_mode=True with root_dir to enable path-based access restrictions.
LocalShellBackend security risks
LocalShellBackend grants agents direct filesystem read/write access and unrestricted shell execution on the host. Security risks include: agents can execute arbitrary shell commands with the user's permissions; agents can read any accessible file including secrets (API keys, credentials, .env files); secrets may be exposed; file modifications and command execution are permanent and irreversible; commands run directly on the host system; commands can consume unlimited CPU, memory, disk.
LocalShellBackend appropriate use cases
LocalShellBackend is appropriate for local development CLIs (coding assistants, development tools), personal development environments where you trust the agent's code, and CI/CD pipelines with proper secret management. It is inappropriate for production environments (web servers, APIs, multi-tenant systems) and processing untrusted user input or executing untrusted code.
LocalShellBackend recommended safeguards
For LocalShellBackend: (1) Enable Human-in-the-Loop (HITL) middleware to review and approve operations before execution—this is strongly recommended. (2) Run in dedicated development environments only. Never use on shared or production systems. (3) Use a sandbox backend for production environments requiring shell execution. Note that virtual_mode=True provides no security with shell access enabled, since commands can access any path on the system.
Protocol reference required method: read
read(file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult must return file data on success. On missing file, return ReadResult(error="Error: File '/x' not found").
BackendProtocol required methods
BackendProtocol requires these methods: ls(path: str) -> LsResult—list files and directories at the given path; read(file_path: str, offset: int, limit: int) -> ReadResult—return file contents, optionally paginated; write(file_path: str, content: str) -> WriteResult—create or overwrite a file; edit(file_path: str, old_string: str, new_string: str, replace_all: bool) -> EditResult—find-and-replace within an existing file; glob(pattern: str, path: str | None) -> GlobResult—return paths matching a glob pattern; grep(pattern: str, path: str | None, glob: str | None) -> GrepResult—search file contents for a literal string; delete(file_path: str) -> DeleteResult—optional, remove a file or recursively a directory. To support execute tool, implement SandboxBackendProtocol instead, which extends BackendProtocol with an execute method. Always return structured result types with an error field for failure cases; do not raise exceptions.
BackendProtocolV2 required methods (JavaScript)
BackendProtocolV2 requires: ls(path: string) => Promise<LsResult>—list files and directories; read(filePath: string, offset?, limit?) => Promise<ReadResult>—return file contents, optionally paginated, with Uint8Array for binary files and mimeType; readRaw(filePath: string) => Promise<ReadRawResult>—return raw FileData; write(filePath: string, content: string) => Promise<WriteResult>—create-only; edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean) => Promise<EditResult>—find-and-replace; glob(pattern: string, path?: string) => Promise<GlobResult>—matching paths; grep(pattern: string, path?, glob?) => Promise<GrepResult>—search file contents. To support execute tool, implement SandboxBackendProtocolV2, which extends BackendProtocolV2 with an execute method. All methods must return structured Result objects with optional error field.
Result type specifications for protocol
LsResult(error, entries)—entries is a list[FileInfo] on success, None on failure. ReadResult(error, file_data)—file_data is a FileData dict on success, None on failure. GrepResult(error, matches)—matches is a list[GrepMatch] on success, None on failure. GlobResult(error, matches)—matches is a list[FileInfo] on success, None on failure. WriteResult(error, path, files_update). EditResult(error, path, files_update, occurrences). FileInfo with fields: path (required), optionally is_dir, size, modified_at. GrepMatch with fields: path, line, text. FileData with fields: content (str), encoding ('utf-8' or 'base64'), created_at, modified_at.
JavaScript ReadResult with binary file support
In JavaScript, ReadResult has success fields: content (string or Uint8Array), mimeType (optional), and error field. For text files, content is paginated by line offset/limit (default offset 0, limit 500). For binary files, full raw Uint8Array content is returned with mimeType field set. On missing file, return {error: "File '/x' not found"}.
JavaScript supported MIME types for multimodal files
Images: .png, .jpg/.jpeg, .gif, .webp, .svg, .heic, .heif with MIME types image/png, image/jpeg, image/gif, image/webp, image/svg+xml, image/heic, image/heif. Audio: .mp3, .wav, .aiff, .aac, .ogg, .flac with MIME types audio/mpeg, audio/wav, audio/aiff, audio/aac, audio/ogg, audio/flac. Video: .mp4, .webm, .mpeg/.mpg, .mov, .avi, .flv, .wmv, .3gpp with MIME types video/mp4, video/webm, video/mpeg, video/quicktime, video/x-msvideo, video/x-flv, video/x-ms-wmv, video/3gpp. Documents: .pdf, .ppt, .pptx with MIME types application/pdf, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation. Text: .txt, .html, .json, .js, .ts, .py, etc.
FileData format in JavaScript
FileData is the type used to store file content in state and store backends. Current format (v2): {content: string | Uint8Array, mimeType: string, created_at: string (ISO 8601), modified_at: string (ISO 8601)}. Legacy format (v1): {content: string[], created_at: string, modified_at: string}. Backends may encounter either format when reading from state or store. The framework handles both transparently. New writes default to v2 format. During rolling deployments where older readers need legacy format, pass fileFormat: "v1" to backend constructor (e.g., new StoreBackend({fileFormat: "v1"})).
Protocol reference required method: edit
edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult must enforce uniqueness of old_string unless replace_all=True. If not found, return error. Include occurrences on success.
Custom backend implementation pattern
To implement a custom backend (e.g., S3Backend), subclass BackendProtocol and implement all required methods: ls, read, grep, glob, write, edit. Map filesystem paths to storage system operations (list, read, search, upload, read-modify-write). Always return structured result types with an error field; do not raise exceptions.
Policy hooks for custom backend validation
For custom validation logic beyond path-based allow/deny rules (rate limiting, audit logging, content inspection), enforce enterprise rules by subclassing or wrapping a backend. Can subclass a backend like FilesystemBackend or create a generic wrapper implementing BackendProtocol that checks policies in write and edit methods.
JavaScript backend V1 to V2 migration methods
V1 to V2 method renames: lsInfo(path) → ls(path); read(filePath, offset, limit) → read(filePath, offset, limit); readRaw(filePath) → readRaw(filePath); grepRaw(pattern, path, glob) → grep(pattern, path, glob); globInfo(pattern, path) → glob(pattern, path). Type renames: BackendProtocol → BackendProtocolV2; SandboxBackendProtocol → SandboxBackendProtocolV2.
JavaScript adaptation utilities for V1 backends
Use adaptBackendProtocol() to adapt a V1 backend to V2 or adaptSandboxProtocol() to adapt a V1 sandbox to V2. The framework auto-adapts V1 backends passed to createDeepAgent(). Manual adaptation is only needed when calling protocol methods directly.
Sandboxes are backends that provide isolation
In Deep Agents, sandboxes are backends that define the environment where the agent operates. Unlike other backends (State, Filesystem, Store) which only expose file operations, sandbox backends also give the agent an execute tool for running shell commands. When you configure a sandbox backend, the agent gets all standard filesystem tools (ls, read_file, write_file, edit_file, delete, glob, grep) plus the execute tool for running arbitrary shell commands.
execute() is the only method providers must implement
Sandbox backends have a simple architecture where the only method a provider must implement is execute(), which runs a shell command and returns its output. Every other filesystem operation (read, write, edit, delete, ls, glob, grep) is built on top of execute() by the BaseSandbox base class, which constructs scripts and runs them inside the sandbox via execute().
execute() method return values
When the agent calls the execute tool, it provides a command string and gets back the combined stdout/stderr, exit code, and a truncation notice if the output was too large. If a command produces very large output, the result is automatically saved to a file and the agent is instructed to use read_file to access it incrementally.
SandboxBackendProtocol controls execute tool availability
The execute tool is conditionally available. On every model call, the harness checks whether the backend implements SandboxBackendProtocol. If not, the tool is filtered out and the agent never sees it.
Sandboxes do not protect against context injection
Sandboxes alone do not protect against context injection. An attacker who controls part of the agent's input can instruct it to run arbitrary commands inside the sandbox. The sandbox is isolated, but the agent has full control within it. Sandboxes also do not protect against network exfiltration unless network access is blocked.
Never put secrets inside a sandbox
API keys, tokens, database credentials, and other secrets injected into a sandbox (via environment variables, mounted files, or the secrets option) can be read and exfiltrated by a context-injected agent. This applies even to short-lived or scoped credentials—if an agent can access them, so can an attacker.
Handle secrets safely in sandboxes
If your agent needs to call authenticated APIs or access protected resources, you have two options: (1) Keep secrets in tools outside the sandbox by defining tools that run in your host environment and handle authentication there - the agent calls these tools by name but never sees the credentials (recommended approach), or (2) Use a network proxy that injects credentials by intercepting outgoing HTTP requests from the sandbox and attaching credentials before forwarding them (not yet widely available across providers).
Sandbox security best practices
General best practices for sandbox security include: review sandbox outputs before acting on them in your application, block sandbox network access when not needed, use middleware to filter or redact sensitive patterns in tool outputs, and treat everything produced inside the sandbox as untrusted input.
What sandboxes are used for
Sandboxes are used for security. They let agents execute arbitrary code, access files, and use the network without compromising your credentials, local files, or host system. This isolation is essential when agents run autonomously. Sandboxes are especially useful for coding agents that run autonomously using shell, git, clone repositories, and run Docker-in-Docker for build and test pipelines, and for data analysis agents that load files, install libraries, run calculations, and create outputs in a safe isolated environment.
Isolation boundaries of sandboxes
All sandbox providers protect your host system from the agent's filesystem and shell operations. The agent cannot read your local files, access environment variables on your machine, or interfere with other processes.
Sandboxes consume resources and cost money
Sandboxes consume resources and cost money until they are shut down. Make sure you shut sandboxes down once they are no longer in use.