What Is Deep Agents SDK? The Design Logic Behind the Agent Framework

You've probably used some agent frameworks before — maybe LangChain's create_agent, maybe a LangGraph workflow, maybe something you wired together yourself with tool calling.

For most cases they're fine. But there's one type of task where they almost always disappoint: tasks that require multiple steps, involve large amounts of intermediate information, and require adjusting the plan based on progress along the way.

The agent starts, gets lost halfway through, redoes things it already handled, or more commonly — skips certain steps and delivers a result that looks finished on the surface but isn't.

This isn't a problem you can solve by swapping in a smarter model — the framework itself never gave the agent the ability to "have a place to put things" or "figure out what to do next."

Three Things Most Frameworks Don't Provide

Let's look at what an agent actually lacks when executing complex tasks:

Gap 1: No Planning Capability

Most agent frameworks are designed as: receive prompt → decide which tool to use → get result → decide next step. This loop works fine for one or two-step tasks, but with a 15-step task, the agent easily "lives in the moment" — only aware of the current step, with no idea what's still ahead or what role this step plays in the overall plan.

Gap 2: Nowhere to Put Context

Tool return values get stuffed into the context window. The more complex the task, the more information accumulates, and the faster context fills up. What happens when it's full? Either it gets truncated (the agent starts forgetting things), or it throws an error (it just crashes).

Gap 3: No Memory Across Conversations

When a conversation ends, state resets to zero. The next time you open a new conversation, the agent has no idea what it did last time or what it learned. If your task spans multiple conversations, this problem forces you to start over every time.

Deep Agents SDK's Solutions

Deep Agents positions itself as an "agent harness" — the core tool-calling loop isn't much different from other frameworks, but it fills all three gaps:

Fix 1: write_todos Tool

Before starting execution, the agent can call write_todos to break the task into concrete steps and then track progress step by step. This isn't about prompt engineering to make it "remember to plan" — there's an actual tool for this. The plan is externalized and doesn't need context to maintain it.

Fix 2: Virtual Filesystem

ls, read_file, write_file, edit_file — the agent has its own virtual filesystem. Tool output doesn't need to all be stuffed in context; it can be written to files and read back when needed. The context window only holds "what's actually needed right now."

Fix 3: LangGraph Memory Store

Cross-session long-term memory, based on LangGraph's Memory Store. The agent can store information worth keeping and retrieve it in the next conversation — not through summaries or external notes, but as a capability directly supported at the SDK level.

Relationship with LangChain and LangGraph

All three live in the same ecosystem, but with different roles:

	LangChain	LangGraph	Deep Agents
Role	Core building blocks	Durable runtime	Agent harness
Use case	All kinds of AI app development	Complex workflow orchestration	Agents needing planning, memory, filesystem
Planning	Build it yourself	Build it yourself	Built-in write_todos
Context management	Build it yourself	Build it yourself	Built-in virtual filesystem
Long-term memory	Build it yourself	Memory Store available	Built-in integration

Deep Agents is built on top of LangChain and LangGraph — it inherits LangGraph's durable execution, streaming, and human-in-the-loop, then adds the three capabilities agents need at their foundation.

When to Use Deep Agents, When Not To

Good fit:

• Tasks that need to be broken down into multiple steps where each step's result influences the next decision
• Tool return data is large, context window fills easily (web scraping, analysis, document processing)
• Need to delegate subtasks to different specialized agents
• Need to retain information across conversations (user preferences, project state, completed work)

Lighter solutions work fine:

• Simple single-turn Q&A or one or two-step tool calls — LangChain's create_agent is enough
• Fixed workflows with no dynamic planning needed — building a LangGraph graph directly is cleaner
• Prototypes and demos — any framework works, Deep Agents' advantages only show up with complex tasks

One Sentence Summary

Deep Agents doesn't give you a smarter model — it gives the agent a planning board, a filesystem, and cross-conversation memory, so complex tasks have a place to be broken down, a place to store things, and a place to remember.

If your agent frequently gets lost in complex tasks, the next article will walk you through setting it up and running it.

---

Previous: Deep Agents SDK Beginner Course: Series Overview Next: Quickstart: Build Your First Deep Agent in 5 Minutes