deepagents 1.3.1 → 1.4.1

package/README.md

@@ -1,4 +1,4 @@
-# 🧠🤖Deep Agents
+# 🧠🤖 Deep Agents
 
 Using an LLM to call tools in a loop is the simplest form of an agent.
 This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.
@@ -6,14 +6,43 @@ This architecture, however, can yield agents that are "shallow" and fail to plan
 Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things:
 a **planning tool**, **sub agents**, access to a **file system**, and a **detailed prompt**.
 
-> 💡 **Tip:** Looking for the Python version of this package? See [here: langchain-ai/deepagents](https://github.com/langchain-ai/deepagents)
+> 💡 **Tip:** Looking for the Python version of this package? See [langchain-ai/deepagents](https://github.com/langchain-ai/deepagents)
 
-<!-- TODO: Add image here -->
+![Deep Agents](https://blog.langchain.com/content/images/2025/07/Screenshot-2025-07-30-at-9.08.32-AM.png)
 
 `deepagents` is a TypeScript package that implements these in a general purpose way so that you can easily create a Deep Agent for your application.
 
 **Acknowledgements: This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so.**
 
+[![npm version](https://img.shields.io/npm/v/deepagents.svg)](https://www.npmjs.com/package/deepagents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+[Documentation](https://docs.langchain.com/oss/javascript/deepagents/overview) | [Examples](./examples) | [Report Bug](https://github.com/langchain-ai/deepagentsjs/issues) | [Request Feature](https://github.com/langchain-ai/deepagentsjs/issues)
+
+## 📖 Overview
+
+Using an LLM to call tools in a loop is the simplest form of an agent. However, this architecture can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.
+
+Applications like **Deep Research**, **Manus**, and **Claude Code** have overcome this limitation by implementing a combination of four key components:
+
+1. **Planning Tool** - Strategic task decomposition
+2. **Sub-Agents** - Specialized agents for subtasks
+3. **File System Access** - Persistent state and memory
+4. **Detailed Prompts** - Context-rich instructions
+
+**Deep Agents** is a TypeScript package that implements these patterns in a general-purpose way, enabling you to easily create sophisticated agents for your applications.
+
+## ✨ Features
+
+- 🎯 **Task Planning & Decomposition** - Break complex tasks into manageable steps
+- 🤖 **Sub-Agent Architecture** - Delegate specialized work to focused agents
+- 💾 **File System Integration** - Persistent memory and state management
+- 🌊 **Streaming Support** - Real-time updates, token streaming, and progress tracking
+- 🔄 **LangGraph Powered** - Built on the robust LangGraph framework
+- 📝 **TypeScript First** - Full type safety and IntelliSense support
+- 🔌 **Extensible** - Easy to customize and extend for your use case
+
 ## Installation
 
 ```bash
@@ -440,6 +469,81 @@ const agent4 = createDeepAgent({
 
 See [examples/backends/](examples/backends/) for detailed examples of each backend type.
 
+### Sandbox Execution
+
+For agents that need to run shell commands, you can create a sandbox backend by extending `BaseSandbox`. This enables the `execute` tool which allows agents to run arbitrary shell commands in an isolated environment.
+
+```typescript
+import {
+  createDeepAgent,
+  BaseSandbox,
+  type ExecuteResponse,
+  type FileUploadResponse,
+  type FileDownloadResponse,
+} from "deepagents";
+import { spawn } from "child_process";
+
+// Create a concrete sandbox by extending BaseSandbox
+class LocalShellSandbox extends BaseSandbox {
+  readonly id = "local-shell";
+  private readonly workingDirectory: string;
+
+  constructor(workingDirectory: string) {
+    super();
+    this.workingDirectory = workingDirectory;
+  }
+
+  // Only execute() is required - BaseSandbox implements all file operations
+  async execute(command: string): Promise<ExecuteResponse> {
+    return new Promise((resolve) => {
+      const child = spawn("/bin/bash", ["-c", command], {
+        cwd: this.workingDirectory,
+      });
+
+      const chunks: string[] = [];
+      child.stdout.on("data", (data) => chunks.push(data.toString()));
+      child.stderr.on("data", (data) => chunks.push(data.toString()));
+
+      child.on("close", (exitCode) => {
+        resolve({
+          output: chunks.join(""),
+          exitCode,
+          truncated: false,
+        });
+      });
+    });
+  }
+
+  async uploadFiles(
+    files: Array<[string, Uint8Array]>,
+  ): Promise<FileUploadResponse[]> {
+    // Implement file upload logic
+    return files.map(([path]) => ({ path, error: null }));
+  }
+
+  async downloadFiles(paths: string[]): Promise<FileDownloadResponse[]> {
+    // Implement file download logic
+    return paths.map((path) => ({
+      path,
+      content: null,
+      error: "file_not_found",
+    }));
+  }
+}
+
+// Use the sandbox with your agent
+const sandbox = new LocalShellSandbox("./workspace");
+
+const agent = createDeepAgent({
+  backend: sandbox,
+  systemPrompt: "You can run shell commands using the execute tool.",
+});
+```
+
+When using a sandbox backend, the agent gains access to an `execute` tool that can run shell commands. The tool automatically returns the command output, exit code, and whether the output was truncated.
+
+See [examples/sandbox/local-sandbox.ts](examples/sandbox/local-sandbox.ts) for a complete implementation.
+
 ## Deep Agents Middleware
 
 Deep Agents are built with a modular middleware architecture. As a reminder, Deep Agents have access to:
@@ -486,6 +590,7 @@ Context engineering is one of the main challenges in building effective agents.
 - **edit_file**: Edit an existing file in your filesystem
 - **glob**: Find files matching a pattern
 - **grep**: Search for text within files
+- **execute**: Run shell commands (only available when using a `SandboxBackendProtocol`)
 
 ```typescript
 import { createAgent } from "langchain";