deepagents

Create a Deep Agent.

By default, this agent has access to the following tools:

• write_todos: manage a todo list
• ls, read_file, write_file, edit_file, glob, grep: file operations
• execute: run shell commands
• task: call subagents

The execute tool allows running shell commands if the backend implements SandboxBackendProtocol. For non-sandbox backends, the execute tool will return an error message.

Specification for an async subagent running on a remote Agent Protocol server.

Async subagents connect to any Agent Protocol-compliant server via the LangGraph SDK. They run as background tasks that the main agent can monitor and update.

Compatible with LangGraph Platform (managed) and self-hosted servers. Authentication for LangGraph Platform is handled automatically by the SDK via environment variables (LANGGRAPH_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY). For self-hosted servers, pass custom auth via headers.

Middleware for async subagents running on remote Agent Protocol servers.

This middleware adds tools for launching, monitoring, and updating background tasks on remote Agent Protocol servers. Unlike the synchronous SubAgentMiddleware, async subagents return immediately with a task ID, allowing the main agent to continue working while subagents execute.

Works with any Agent Protocol-compliant server — LangGraph Platform (managed) or self-hosted (e.g. a FastAPI server implementing the Agent Protocol spec).

Task IDs are persisted in the agent state under async_tasks so they survive context compaction/offloading and can be accessed programmatically.

Middleware for providing filesystem and optional execution tools to an agent.

This middleware adds filesystem tools to the agent: ls, read_file, write_file, edit_file, glob, and grep.

Files can be stored using any backend that implements the BackendProtocol.

If the backend implements SandboxBackendProtocol, an execute tool is also added for running shell commands.

This middleware also automatically evicts large tool results to the file system when they exceed a token threshold, preventing context window saturation.

Middleware for loading agent memory from AGENTS.md files.

Loads memory content from configured sources and injects into the system prompt.

Supports multiple sources that are combined together.

A single access rule for filesystem operations.

Rules are evaluated in declaration order. The first matching rule's mode is applied. If no rule matches, the call is allowed (permissive default).

A pre-compiled agent spec.

When the subagent completes, the final message in the 'messages' list will be extracted and returned as a ToolMessage to the parent agent.

Specification for an agent.

When using create_deep_agent, subagents automatically receive a default middleware stack (TodoListMiddleware, FilesystemMiddleware, SummarizationMiddleware, etc.) before any custom middleware specified in this spec.

Middleware for providing subagents to an agent via a task tool.

This middleware adds a task tool to the agent that can be used to invoke subagents. Subagents are useful for handling complex tasks that require multiple steps, or tasks that require a lot of context to resolve.

A chief benefit of subagents is that they can handle multi-step tasks, and then return a clean, concise response to the main agent.

Subagents are also great for different domains of expertise that require a narrower subset of tools and focus.

Primary graph assembly module for Deep Agents.

Provides create_deep_agent, the main entry point for constructing a fully configured Deep Agent with planning, filesystem, subagent, and summarization middleware.

Middleware for the Deep Agents agent.

Overview

The LLM receives tools through two paths:

1. SDK middleware (this package) -- tools, system-prompt injection, and request interception that any SDK consumer gets automatically.
2. Consumer-provided tools -- plain callable functions passed via the tools parameter to create_deep_agent(). The CLI uses this path for lightweight, consumer-specific tools.

Both are merged by create_deep_agent() into the final tool set the LLM sees.

Why middleware instead of plain tools?

Middleware subclasses AgentMiddleware, overriding its wrap_model_call() hook that intercepts every LLM request before it is sent. This lets middleware:

• Filter tools dynamically -- e.g. FilesystemMiddleware removes the execute tool at call-time when the resolved backend doesn't support it.
• Inject system-prompt context -- e.g. MemoryMiddleware and SkillsMiddleware inject relevant instructions into the system message on every call so the LLM knows how to use the tools they provide.
• Transform messages -- e.g. SummarizationMiddleware counts tokens, truncates old tool arguments, and replaces history with summaries when the context window fills up.
• Maintain cross-turn state -- middleware can read/write a typed state dict that persists across agent turns (e.g. summarization events).

A plain tool function in a tools=[] list cannot do any of this -- it is only invoked by the LLM, not before the LLM call.

When to use each path

Use middleware when the tool needs to:

• Modify the system prompt or tool list per-call
• Track state across turns
• Be available to all SDK consumers (not just the CLI)

Use a plain tool when:

• The function is stateless and self-contained
• No system-prompt or request modification is needed
• The tool is specific to a single consumer (e.g. CLI-only)

Harness profiles and provider-specific configuration.

Re-exports the profile dataclass, registry helpers, and provider modules so internal consumers can import from deepagents.profiles directly.

Memory backends for pluggable file storage.