diff --git a/src/oss/deepagents/backends.mdx b/src/oss/deepagents/backends.mdx index 692d1f4405..0f070b371e 100644 --- a/src/oss/deepagents/backends.mdx +++ b/src/oss/deepagents/backends.mdx @@ -15,10 +15,12 @@ import BackendContextHubPy from '/snippets/code-samples/backend-context-hub-py.m import BackendCompositePy from '/snippets/code-samples/backend-composite-py.mdx'; import BackendCompositeJs from '/snippets/code-samples/backend-composite-js.mdx'; -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. The `read_file` tool natively supports image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) across all backends, returning them as multimodal content blocks. +:::python +Deep Agents expose a filesystem surface to the agent via tools like `ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, and `grep`. These tools operate through a pluggable backend. The `read_file` tool natively supports image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) across all backends, returning them as multimodal content blocks. +::: :::js -The `read_file` tool natively supports binary files (images, PDFs, audio, video) across all backends, returning a `ReadResult` with typed `content` and `mimeType`. +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. The `read_file` tool natively supports binary files (images, PDFs, audio, video) across all backends, returning a `ReadResult` with typed `content` and `mimeType`. ::: Sandboxes and the @[`LocalShellBackend`] also provide an `execute` tool. @@ -514,6 +516,7 @@ Subclass @[`BackendProtocol`] and implement the following methods: | `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. If the backend does not support deletion, the tool is automatically hidden from the model at request time. | To also support the `execute` tool (running shell commands), implement @[`SandboxBackendProtocol`] instead, which extends `BackendProtocol` with an `execute` method. diff --git a/src/oss/deepagents/code/overview.mdx b/src/oss/deepagents/code/overview.mdx index 2329125665..12378fd66f 100644 --- a/src/oss/deepagents/code/overview.mdx +++ b/src/oss/deepagents/code/overview.mdx @@ -74,7 +74,7 @@ Persistent memory carries context across conversations, customizable skills shap Deep Agents Code has the following built-in capabilities: -* **File operations** - read, write, and edit files on disk. +* **File operations** - read, write, edit, and delete files on disk. * **Shell execution** - execute commands to run tests, build projects, manage dependencies, and interact with version control. * **[Remote sandboxes](/oss/deepagents/code/remote-sandboxes)** - run agent tools remotely instead of on your local machine. * **Web search** - search the web for up-to-date information and documentation. Requires a [Tavily API key](/oss/deepagents/code/configuration#enable-web-search-with-tavily). @@ -99,7 +99,7 @@ Deep Agents Code has the following built-in capabilities: | `read_file` | Read contents of a file; returns multimodal blocks for images, audio, video, and PDFs | - | | `write_file` | Create or overwrite a file | Required1 | | `edit_file` | Make targeted edits to existing files | Required1 | - | `delete` | Delete a file or directory recursively | Required1 | + | `delete` | Delete a file, or a directory and its contents recursively | Required1 | | `glob` | Find files matching a pattern | - | | `grep` | Search for text patterns across files | - | | `execute` | Execute shell commands locally or in a [remote sandbox](/oss/deepagents/code/remote-sandboxes) | Required1 | diff --git a/src/oss/deepagents/context-engineering.mdx b/src/oss/deepagents/context-engineering.mdx index 7eb22c6b08..5c08193157 100644 --- a/src/oss/deepagents/context-engineering.mdx +++ b/src/oss/deepagents/context-engineering.mdx @@ -152,7 +152,12 @@ Keep each skill focused on a single workflow or domain; broad or overlapping ski **Built-in tools** – Middleware that adds harness capabilities (planning, filesystem, subagents) automatically appends tool-specific instructions to the system prompt, creating tool prompts that explain how to use those tools effectively. See [Customization](/oss/deepagents/customization#middleware) for the full list: - Planning prompt – Instructions for `write_todos` to maintain a structured task list +:::python +- Filesystem prompt – Documentation for `ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep` (and `execute` when using a sandbox backend) +::: +:::js - Filesystem prompt – Documentation for `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` (and `execute` when using a sandbox backend) +::: - Subagent prompt – Guidance for delegating work with the `task` tool - Human-in-the-loop prompt – Usage for pausing at specified tool calls (when `interrupt_on` is set) - Local context prompt – Current directory and project info (CLI only) diff --git a/src/oss/deepagents/frontend/sandbox.mdx b/src/oss/deepagents/frontend/sandbox.mdx index ebc193047b..7f283402d8 100644 --- a/src/oss/deepagents/frontend/sandbox.mdx +++ b/src/oss/deepagents/frontend/sandbox.mdx @@ -24,10 +24,22 @@ import FrontendSandboxThreadBackendPy from "/snippets/code-samples/frontend-sand This setup has three parts: +:::python + +1. **Deep agent with a sandbox backend:** The agent gets filesystem tools + (`read_file`, `write_file`, `edit_file`, `delete`, `execute`) automatically + from the sandbox + +::: + +:::js + 1. **Deep agent with a sandbox backend:** The agent gets filesystem tools (`read_file`, `write_file`, `edit_file`, `execute`) automatically from the sandbox +::: + :::python 2. **Custom API server** — A FastAPI app exposed via `langgraph.json`'s `http.app` @@ -797,8 +809,16 @@ Frontend-specific: - **Persist `threadId` in `sessionStorage`** so page reloads reconnect to the same thread and sandbox instead of creating new ones. + +:::python +- **Sync files on every relevant tool call**, not just when the run finishes. Watch for `write_file`, `edit_file`, `delete`, and `execute` + tool messages and refresh immediately. +::: +:::js - **Sync files on every relevant tool call**, not just when the run finishes. Watch for `write_file`, `edit_file`, and `execute` tool messages and refresh immediately. +::: + - **Default to diff view for changed files**. When a user clicks a file that was modified by the agent, show the diff first — that's what they care about. - **Show compact tool results for read-only operations**. Instead of dumping diff --git a/src/oss/deepagents/overview.mdx b/src/oss/deepagents/overview.mdx index 93633d12c9..d6a977dc01 100644 --- a/src/oss/deepagents/overview.mdx +++ b/src/oss/deepagents/overview.mdx @@ -111,20 +111,35 @@ The harness provides a configurable virtual filesystem which can be backed by di The backends support the following file system operations: +:::python + | Tool | Description | | ---- | ----------- | | `ls` | List files in a directory with metadata (size, modified time) | | `read_file` | Read file contents with line numbers, supports offset/limit for large files. Also supports returning multimodal content blocks for non-text files (images, video, audio, and documents). See supported extensions below. | | `write_file` | Create a new file, or overwrite an existing one | | `edit_file` | Perform exact string replacements in files (with global replace mode) | +| `delete` | Delete a file, or a directory and its contents recursively | +| `glob` | Find files matching patterns (e.g., `**/*.py`) | +| `grep` | Search file contents with multiple output modes (files only, content with context, or counts) | +| `execute` | Run shell commands in the environment (available with [sandbox backends](/oss/deepagents/sandboxes) only) | + +The `delete` tool requires `deepagents` 0.7.a1 or newer. Recursive directory deletion requires 0.7.a2 or newer. Backends that do not support deletion have the tool automatically hidden from the model. + +::: + +:::js + +| Tool | Description | +| ---- | ----------- | +| `ls` | List files in a directory with metadata (size, modified time) | +| `read_file` | Read file contents with line numbers, supports offset/limit for large files. Also supports returning multimodal content blocks for non-text files (images, video, audio, and documents). See supported extensions below. | +| `write_file` | Create new files | +| `edit_file` | Perform exact string replacements in files (with global replace mode) | | `glob` | Find files matching patterns (e.g., `**/*.py`) | | `grep` | Search file contents with multiple output modes (files only, content with context, or counts) | | `execute` | Run shell commands in the environment (available with [sandbox backends](/oss/deepagents/sandboxes) only) | -:::python - - `write_file` overwrites a file if it already exists, as of `deepagents>=0.7.0a2`. On earlier versions, `write_file` errors instead. Use `edit_file` to modify an existing file. - ::: @@ -141,7 +156,18 @@ The backends support the following file system operations: To hide the filesystem tools listed above from the model, register a [harness profile](/oss/deepagents/profiles#harness-profiles) with `excluded_tools`: - + ```python + from deepagents import HarnessProfile, register_harness_profile + + register_harness_profile( + "anthropic:claude-sonnet-4-6", + HarnessProfile( + excluded_tools=frozenset( + {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep"} + ), + ), + ) + ``` Removing @[`FilesystemMiddleware`] itself via `excluded_middleware` is intentionally rejected—it is required scaffolding in the [default middleware stack](/oss/deepagents/customization#default-stack-main-agent). Use `excluded_tools` to hide only the model-visible tool surface and leave the middleware in place. To remove the `task` tool, see [Running without subagents](/oss/deepagents/subagents#running-without-subagents). diff --git a/src/oss/deepagents/permissions.mdx b/src/oss/deepagents/permissions.mdx index de1f1cc3f9..ee018146cb 100644 --- a/src/oss/deepagents/permissions.mdx +++ b/src/oss/deepagents/permissions.mdx @@ -37,7 +37,13 @@ Control which files and directories an agent can read or write to using declarat ::: +:::python +Permissions only apply to the built-in filesystem tools (`ls`, `read_file`, `glob`, `grep`, `write_file`, `edit_file`, `delete`). Custom tools and MCP tools that access the filesystem are not covered. Permissions also do not apply to [sandbox backends](/oss/deepagents/sandboxes), which support arbitrary command execution via the `execute` tool. +::: + +:::js Permissions only apply to the built-in filesystem tools (`ls`, `read_file`, `glob`, `grep`, `write_file`, `edit_file`). Custom tools and MCP tools that access the filesystem are not covered. Permissions also do not apply to [sandbox backends](/oss/deepagents/sandboxes), which support arbitrary command execution via the `execute` tool. +::: Use `permissions` when you need **path-based allow/deny rules** on the built-in filesystem tools. Use [backend policy hooks](/oss/deepagents/backends#add-policy-hooks) when you need custom validation logic (rate limiting, audit logging, content inspection) or need to control custom tools. @@ -69,7 +75,7 @@ Each `FilesystemPermission` has three fields: | Field | Type | Description | |-------|------|-------------| -| `operations` | `list["read" \| "write"]` | Operations this rule applies to. `"read"` covers `ls`, `read_file`, `glob`, `grep`. `"write"` covers `write_file`, `edit_file`. | +| `operations` | `list["read" \| "write"]` | Operations this rule applies to. `"read"` covers `ls`, `read_file`, `glob`, `grep`. `"write"` covers `write_file`, `edit_file`, `delete`. | | `paths` | `list[str]` | Glob patterns for matching file paths (e.g., `["/workspace/**"]`). Supports `**` for recursive matching and `{a,b}` for alternation. | | `mode` | `"allow" \| "deny" \| "interrupt"` | Whether to allow, deny, or pause for human approval on matching operations. Defaults to `"allow"`. See [Pause for human approval](#pause-for-human-approval). | @@ -101,14 +107,18 @@ Paths must be absolute (start with `/`) and cannot contain `..` or `~`. Invalid The `"interrupt"` mode requires `deepagents>=0.6.8`. -Set `mode="interrupt"` to pause for human approval instead of allowing or denying a matching operation outright. When the agent calls a built-in write tool (`write_file`, `edit_file`) on a path that matches an interrupt-mode rule, `create_deep_agent` raises a human-in-the-loop interrupt rather than running the tool, and a reviewer can approve, edit, or reject the call. +Set `mode="interrupt"` to pause for human approval instead of allowing or denying a matching operation outright. When the agent calls a built-in write tool (`write_file`, `edit_file`, `delete`) on a path that matches an interrupt-mode rule, `create_deep_agent` raises a human-in-the-loop interrupt rather than running the tool, and a reviewer can approve, edit, or reject the call. Interrupt-mode rules are wired into the agent's human-in-the-loop middleware automatically and merge with any `interrupt_on` you pass, so you handle and resume them the same way as tool-call interrupts. See [Human-in-the-loop](/oss/deepagents/human-in-the-loop) for the resume flow. + +Deleting a directory is all-or-nothing: `delete` checks the `write` permission on the target and every descendant path, and refuses the entire operation if any of them is denied, rather than removing part of the tree. + + -Anchor interrupt patterns with a literal leading segment (for example, `/secrets/**` or `/projects/*/secrets/**`). Bulk tools (`ls`, `glob`, `grep`) fire the interrupt when their search subtree could overlap the rule's anchored prefix, so a fully unanchored pattern like `/**/secrets` conservatively over-fires. +Anchor interrupt patterns with a literal leading segment (for example, `/secrets/**` or `/projects/*/secrets/**`). Bulk tools (`ls`, `glob`, `grep`, and `delete` on a directory) fire the interrupt when their search subtree could overlap the rule's anchored prefix, so a fully unanchored pattern like `/**/secrets` conservatively over-fires. ::: diff --git a/src/oss/deepagents/sandboxes.mdx b/src/oss/deepagents/sandboxes.mdx index d24009e049..6bbeb8aa0d 100644 --- a/src/oss/deepagents/sandboxes.mdx +++ b/src/oss/deepagents/sandboxes.mdx @@ -15,7 +15,12 @@ Agents generate code, interact with filesystems, and run shell commands. Because In Deep Agents, **sandboxes are [backends](/oss/deepagents/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: +:::python +- All standard filesystem tools (`ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep`) +::: +:::js - All standard filesystem tools (`ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`) +::: - The `execute` tool for running arbitrary shell commands in the sandbox - A secure boundary that protects your host system @@ -307,7 +312,14 @@ See [security considerations](#security-considerations) for how to handle secret ### The `execute` method -Sandbox backends have a simple architecture: 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`, `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()`. +Sandbox backends have a simple architecture: the only method a provider must implement is `execute()`, which runs a shell command and returns its output. + +:::python +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()`. +::: +:::js +Every other filesystem operation (`read`, `write`, `edit`, `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()`. +::: ```mermaid graph TB @@ -542,7 +554,12 @@ If a command produces very large output, the result is automatically saved to a There are two distinct ways files move in and out of a sandbox, and it's important to understand when to use each: -**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, and `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task. +:::python +**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `delete`, `ls`, `glob`, `grep`, `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task. +::: +:::js +**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task. +::: **File transfer APIs**: the `uploadFiles()` and `downloadFiles()` methods that your application code calls. These use the provider's native file transfer APIs (not shell commands) and are designed for moving files between your host environment and the sandbox. Use these to: - **Seed the sandbox** with source code, configuration, or data before the agent runs diff --git a/src/oss/deepagents/tools.mdx b/src/oss/deepagents/tools.mdx index cf0d46b4cf..02027f3978 100644 --- a/src/oss/deepagents/tools.mdx +++ b/src/oss/deepagents/tools.mdx @@ -74,22 +74,39 @@ For detailed configuration options — including stdio servers, OAuth authentica In addition to the tools you provide, every Deep Agent comes with a built-in set of tools from the harness: +:::python + | Tool | Description | | ---- | ----------- | | `ls` | List files in a directory | | `read_file` | Read file contents (with pagination and multimodal support) | | `write_file` | Create a new file, or overwrite an existing one | | `edit_file` | Perform exact string replacements in files | +| `delete` | Delete a file, or a directory and its contents recursively | +| `glob` | Find files matching a glob pattern | +| `grep` | Search file contents | +| `execute` | Run shell commands (sandbox backends only) | +| `task` | Spawn a subagent to handle a delegated task | +| `write_todos` | Manage a structured todo list | + +The `delete` tool requires `deepagents` 0.7.a1 or newer. Recursive directory deletion requires 0.7.a2 or newer. + +::: + +:::js + +| Tool | Description | +| ---- | ----------- | +| `ls` | List files in a directory | +| `read_file` | Read file contents (with pagination and multimodal support) | +| `write_file` | Create new files | +| `edit_file` | Perform exact string replacements in files | | `glob` | Find files matching a glob pattern | | `grep` | Search file contents | | `execute` | Run shell commands (sandbox backends only) | | `task` | Spawn a subagent to handle a delegated task | | `write_todos` | Manage a structured todo list | -:::python - - `write_file` overwrites a file if it already exists, as of `deepagents>=0.7.0a2`. On earlier versions, `write_file` errors instead. Use `edit_file` to modify an existing file. - ::: For a full breakdown of what each built-in tool does, see [Harness overview](/oss/deepagents/overview#execution-environment). diff --git a/src/oss/langchain/deep-agent-from-scratch.mdx b/src/oss/langchain/deep-agent-from-scratch.mdx index 22722da0ba..3106431960 100644 --- a/src/oss/langchain/deep-agent-from-scratch.mdx +++ b/src/oss/langchain/deep-agent-from-scratch.mdx @@ -125,7 +125,14 @@ This runs, but the agent has no filesystem and no way to execute code. If you as To analyze data efficiently, the agent needs to run code on files. This requires two things: - An isolated [sandbox](/oss/deepagents/sandboxes) where the agent can place files and run code on the files without giving the agent access to your host machine. -- A [backend](/oss/deepagents/backends) which provides the file system tools to work with the sandbox (`read_file`, `write_file`, `edit_file`, `glob`, and `grep`) using the @[`FilesystemMiddleware`]:**. Because the `LangSmithSandbox` backend implements the sandbox protocol, @[`FilesystemMiddleware`] also adds the `execute` tool, which allows the agent to run shell commands. + +:::python +- A [backend](/oss/deepagents/backends) which provides the file system tools to work with the sandbox (`read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep`) using the @[`FilesystemMiddleware`]:**. Because the `LangSmithSandbox` backend implements the sandbox protocol, @[`FilesystemMiddleware`] also adds the `execute` tool, which allows the agent to run shell commands. +::: + +:::js +- A [backend](/oss/deepagents/backends) which provides the file system tools to work with the sandbox (`read_file`, `write_file`, `edit_file`, `glob`, `grep`) using the @[`FilesystemMiddleware`]:**. Because the `LangSmithSandbox` backend implements the sandbox protocol, @[`FilesystemMiddleware`] also adds the `execute` tool, which allows the agent to run shell commands. +::: @[`LangSmithSandbox`] is where files live and commands run. @[`FilesystemMiddleware`] is what exposes that environment to the model as tools. The same middleware works with other backends if you swap the backend later.