An Introduction to Deep Agents: Building Multi-Step Autonomous LLM Systems

In the landscape of large language model (LLM) applications, we are moving rapidly from simple single-turn prompts to autonomous systems capable of executing multi-step workflows. While traditional agent frameworks provide a basic tool-calling loop, developers are often left to implement critical system concerns—like sandbox execution, file persistence, permission enforcement, and subtask delegation—entirely from scratch.

Enter Deep Agents (packaged as deepagents). This powerful library acts as an “agent harness” built on top of the LangChain core and LangGraph production runtime. It solves these engineering challenges out of the box, offering built-in capabilities for task planning, virtual file systems, subagent delegation, and persistent context management.

In this guide, we will explore the core capabilities of Deep Agents and show you how to build a fully capable, autonomous LLM agent with just a few lines of code.

---

What is Deep Agents?

Deep Agents is a standalone, static-first, server-first library designed for developers who need to build agents that are safe, resilient, and highly capable in a real-world environment.

Rather than just triggering API calls, a Deep Agent operates within a managed execution environment that can read and write files, parallelize tasks through subagent delegation, retain guidelines in its memory, and pause for human approval before executing sensitive or destructive operations.

At a high level, its architecture is categorized into four core pillars:

graph TD
    A[Deep Agent Harness] --> B[Execution Environment]
    A --> C[Context Management]
    A --> D[Delegation]
    A --> E[Steering & Control]

    B --> B1[MCP Tools]
    B --> B2[Virtual Filesystem]
    B --> B3[Sandboxed Shell]

    C --> C1[On-demand Skills]
    C --> C2[Persistent Memory]
    C --> C3[Prompt Caching]

    D --> D1[Task Planning]
    D --> D2[Subagent Spawning]

    E --> E1[Human-in-the-Loop]
    E --> E2[Declarative Permissions]

---

1. The Execution Environment

An LLM is only as powerful as the tools it can access. Deep Agents provides a robust, layered execution environment containing:

• Model Context Protocol (MCP) Support: Connect natively to databases, APIs, and enterprise services through standard MCP interfaces.
• Virtual Filesystem: Built-in, high-level tools backed by pluggable backends (such as in-memory state, local disk, or GCS/S3 buckets).
• Declarative Permissions: First-match-wins permission rules ensuring that agents cannot read or modify unauthorized directories (e.g., locking down .env files).
• Code Execution: A sandboxed shell interpreter for executing terminal commands and a scoped QuickJS interpreter (eval) for running clean JavaScript logic.

Virtual Filesystem Tools

Deep Agents gives the LLM explicit tools to interact with its virtual file system. These tools handle large files and multimodal assets seamlessly:

Tool	Description
ls	List files and directories with metadata (size, modification time).
read_file	Read files line-by-line, supporting chunking/offsets to prevent context-window blowup. Supports multimodal parsing of .png, .mp4, .wav, and .pdf files.
write_file	Programmatically create new files inside the allowed workspace.
edit_file	Perform precise, target-content string replacements (no need to rewrite whole files).
glob & grep	Find files matching patterns (**/*.ts) or search for exact string patterns.
execute	Run shell commands inside sandboxed environments.

---

2. Hands-On Quickstart: Building Your First Deep Agent

Let’s look at how simple it is to get up and running with Deep Agents. In this example, we will build an agent with custom tool access using Node.js and LangChain.

Prerequisites

First, ensure you have Node.js 20+ installed. Install the necessary packages:

npm install deepagents langchain @langchain/core zod

The Code (index.ts)

Create a new file named index.ts and add the following implementation:

import * as z from "zod";
import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";

// 1. Define a custom tool for getting the weather
const getWeather = tool(
  ({ city }) => {
    return `It's always sunny in ${city}! Currently 24°C with a light breeze.`;
  },
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get weather for"),
    }),
  }
);

// 2. Instantiate the Deep Agent with our tools and system prompt
const agent = await createDeepAgent({
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant with weather monitoring capabilities.",
});

// 3. Invoke the agent to see tool calling in action
const response = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
});

console.log("Agent Response:\n", response.messages[response.messages.length - 1].content);

Run the Example

Execute the file using tsx or compile it with tsc:

npx tsx index.ts

Deep Agents will automatically run the tool-calling loop, observe that the user is asking about the weather in Tokyo, call the get_weather tool, retrieve the result, and format a beautiful response for the client.

---

3. Advanced Context Management

Managing token window limitations is one of the hardest parts of engineering long-running agents. Deep Agents solves this on multiple fronts:

Progressive Skills Discovery

Deep Agents introduces the Agent Skills standard. A “skill” is packaged inside a folder containing a SKILL.md instruction file and supporting assets.

To prevent bloating the LLM’s context at startup, Deep Agents only reads the frontmatter of your skills initially. When the agent identifies that a task requires a specific skill, it loads the full contents of SKILL.md dynamically.

Memory & Preferences

Unlike ephemeral skills, Memory represents the global core guidelines—like code styles, database schemas, or naming conventions—loaded immediately from an AGENTS.md file. The agent can update its memory during execution based on feedback, carrying those learnings forward across future conversation threads.

Prompt Caching & Summarization

Deep Agents automatically detects when you are running on models that support prompt caching (such as Anthropic Claude or Amazon Bedrock Nova). It tags static system instructions, loaded memory files, and skill metadata as cache-eligible. This results in up to a 90% reduction in token costs and significantly faster response times.

---

4. Scaling with Delegation: The Subagent Pattern

For complex, multi-step tasks, a single agent can quickly become overwhelmed by long logs and crowded context windows. Deep Agents provides a built-in Delegation Layer:

1. Task Planning (write_todos): Allows the agent to maintain an active checklist (pending, in_progress, completed) in its internal state, keeping it focused on the overarching goal.
2. Ephemeral Subagents (task tool): When a large subtask is encountered (e.g., compiling a codebase, writing 10 unit tests, or cleaning a large CSV file), the main agent spawns a specialized child subagent.
   • Isolated Context: The subagent gets its own pristine context window, isolated filesystem access, and narrow toolsets.
   • Stateless Execution: The subagent works autonomously and returns only a compiled final report to the parent, preventing intermediate clutter from polluting the main conversation history.

sequenceDiagram
    participant Parent as Main Agent
    participant Task as Task Tool
    participant Sub as Subagent (Isolated Context)

    Parent->>Task: Invoke task("Run security audit")
    activate Task
    Task->>Sub: Initialize with target files
    activate Sub
    Sub->>Sub: Check file permissions
    Sub->>Sub: Execute static analysis
    Sub-->>Task: Return JSON audit report
    deactivate Sub
    Task-->>Parent: Compact summary of findings
    deactivate Task
    Note over Parent: Main context remains clean and cost-efficient.

---

5. Steering and Human-in-the-Loop Safety

Running autonomous agents in production can be intimidating, especially if they have write-access to file systems or payment APIs. Deep Agents features native support for LangGraph Interrupts:

Using the interrupt_on parameter, developers can specify exact tools that require manual approval:

const agent = await createDeepAgent({
  tools: [editFileTool, deleteFileTool],
  interrupt_on: {
    "edit_file": true,
    "delete_file": true,
  },
});

When the agent attempts to delete or edit a file, the run pauses, yielding an event stream to the client. The human operator can review the proposed changes, supply feedback or alternative instructions, and resume or abort the operation safely.

---

Summary and Next Steps

Deep Agents provides the engineering infrastructure that transforms standard LLMs into robust, production-grade autonomous assistants. By unifying sandboxed file systems, declarative permissions, subagent spawning, and prompt caching into a single, cohesive framework, it lets you focus on building features rather than stitching infrastructure together.

To take your agents further:

• Read more about the Model Context Protocol (MCP) to expose your databases directly to your agents.
• Incorporate Agentic Data Cleaning to clean messy ETL pipelines programmatically.
• Explore Nano Stores for lightweight, shared client-state management in Astro projects.

Happy coding!