Deep Agents Core

• Task Planning: TodoListMiddleware for breaking down complex tasks
• Context Management: Filesystem tools with pluggable backends
• Task Delegation: SubAgent middleware for spawning specialized agents
• Long-term Memory: Persistent storage across threads via Store
• Human-in-the-loop: Approval workflows for sensitive operations
• Skills: On-demand loading of specialized capabilities

The agent harness provides these capabilities automatically - you configure, not implement.

@tool def get_weather(city: str) -> str: """Get the weather for a given city.""" return f"It is always sunny in {city}"

agent = create_deep_agent( model="claude-sonnet-4-5-20250929", tools=[get_weather], system_prompt="You are a helpful assistant" )

config = {"configurable": {"thread_id": "user-123"}} result = agent.invoke({ "messages": [{"role": "user", "content": "What's the weather in Tokyo?"}] }, config=config)

</python>
<typescript>
Create a basic deep agent with a custom tool and invoke it with a user message.
```typescript
import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `It is always sunny in ${city}`,
  { name: "get_weather", description: "Get weather for a city", schema: z.object({ city: z.string() }) }
);

const agent = await createDeepAgent({
  model: "claude-sonnet-4-5-20250929",
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant"
});

const config = { configurable: { thread_id: "user-123" } };
const result = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in Tokyo?" }]
}, config);

agent = create_deep_agent( name="my-assistant", model="claude-sonnet-4-5-20250929", tools=[custom_tool1, custom_tool2], system_prompt="Custom instructions", subagents=[research_agent, code_agent], backend=FilesystemBackend(root_dir=".", virtual_mode=True), interrupt_on={"write_file": True}, skills=["./skills/"], memory=["/AGENTS.md"], checkpointer=MemorySaver(), store=InMemoryStore() )

</python>
<typescript>
Configure a deep agent with all available options including subagents, skills, and persistence.
```typescript
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const agent = await createDeepAgent({
  name: "my-assistant",
  model: "claude-sonnet-4-5-20250929",
  tools: [customTool1, customTool2],
  systemPrompt: "Custom instructions",
  subagents: [researchAgent, codeAgent],
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true },
  skills: ["./skills/"],
  memory: ["/AGENTS.md"],
  checkpointer: new MemorySaver(),
  store: new InMemoryStore()
});

1. Planning: write_todos - Track multi-step tasks
2. Filesystem: ls, read_file, write_file, edit_file, glob, grep
3. Delegation: task - Spawn specialized subagents

SKILL.md Format

Directory Structure

skills/
└── my-skill/
    ├── SKILL.md        # Required: main skill file
    ├── examples.py     # Optional: supporting files
    └── templates/      # Optional: templates

SKILL.md Format

---
name: my-skill
description: Clear, specific description of what this skill does
---

# Skill Name

## Overview
Brief explanation of the skill's purpose.

## When to Use
Conditions when this skill applies.

## Instructions
Step-by-step guidance for the agent.

1. Match — When a user prompt arrives, the agent checks skill descriptions to find relevant ones.
2. Read — If a skill applies, the agent uses read_file to load the full SKILL.md content.
3. Execute — The agent follows the skill's instructions and accesses supporting files as needed.

Write clear, specific descriptions in SKILL.md frontmatter — the agent decides whether to use a skill based on the description alone.

agent = create_deep_agent( backend=FilesystemBackend(root_dir=".", virtual_mode=True), skills=["./skills/"], checkpointer=MemorySaver() )

result = agent.invoke({ "messages": [{"role": "user", "content": "Use the python-testing skill"}] }, config={"configurable": {"thread_id": "session-1"}})

</python>
<typescript>
Set up an agent with skills directory and filesystem backend for on-demand skill loading.
```typescript
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"],
  checkpointer: new MemorySaver()
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Use the python-testing skill" }]
}, { configurable: { thread_id: "session-1" } });

store = InMemoryStore()

Load skill content into store

skill_content = """--- name: python-testing description: Best practices for Python testing with pytest

Python Testing Skill

..."""

store.put( namespace=("filesystem",), key="/skills/python-testing/SKILL.md", value=create_file_data(skill_content) )

agent = create_deep_agent( backend=lambda rt: StoreBackend(rt), store=store, skills=["/skills/"] )

</python>
</ex-skills-with-store-backend>

<ex-skills-with-statebackend>
<python>
Seed skill files into StateBackend via invoke(). Use create_file_data() to format content.
```python
from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver

skill_content = """---
name: python-testing
description: Best practices for Python testing with pytest
---
# Python Testing Skill
..."""

skills_files = {
    "/skills/python-testing/SKILL.md": create_file_data(skill_content)
}

agent = create_deep_agent(
    skills=["/skills/"],
    checkpointer=MemorySaver(),
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Write tests for my module"}],
        "files": skills_files  # Seed virtual filesystem
    },
    config={"configurable": {"thread_id": "12345"}},
)

• Model selection and parameters
• Additional custom tools
• System prompt customization
• Backend storage strategy
• Which tools require approval
• Custom subagents with specialized tools
• Model via string format: "provider:model" (e.g., "openai:gpt-4o", "anthropic:claude-sonnet-4-6")

What Agents CANNOT Configure

• Core middleware removal (TodoList, Filesystem, SubAgent always present)
• The write_todos, task, or filesystem tool names
• The SKILL.md frontmatter format

CORRECT

agent = create_deep_agent(interrupt_on={"write_file": True}, checkpointer=MemorySaver())

</python>
<typescript>
Interrupts require a checkpointer.
```typescript
// WRONG
const agent = await createDeepAgent({ interruptOn: { write_file: true } });

// CORRECT
const agent = await createDeepAgent({ interruptOn: { write_file: true }, checkpointer: new MemorySaver() });

CORRECT

agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

</python>
<typescript>
StoreBackend requires a Store instance for persistent memory across threads.
```typescript
// WRONG
const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config) });

// CORRECT
const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config), store: new InMemoryStore() });

CORRECT

config = {"configurable": {"thread_id": "user-123"}} agent.invoke({"messages": [...]}, config=config) agent.invoke({"messages": [...]}, config=config)

</python>
<typescript>
Use consistent thread_id to maintain conversation context across invocations.
```typescript
// WRONG: Each invocation is isolated
await agent.invoke({ messages: [{ role: "user", content: "Hi" }] });
await agent.invoke({ messages: [{ role: "user", content: "What did I say?" }] });

// CORRECT
const config = { configurable: { thread_id: "user-123" } };
await agent.invoke({ messages: [...] }, config);
await agent.invoke({ messages: [...] }, config);

CORRECT: Include YAML frontmatter

name: my-skill description: Python testing best practices with pytest fixtures and mocking

My Skill

This is my skill...

</fix-frontmatter-required>

<fix-backend-for-skills>
<python>
Skills require a proper backend to load from the filesystem.
```python
# WRONG: Skills won't load without proper backend
agent = create_deep_agent(skills=["./skills/"])

# CORRECT: Use FilesystemBackend for local skills
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    skills=["./skills/"]
)

CORRECT: Specific description

name: python-testing description: Python testing best practices with pytest fixtures, mocking, and async patterns

</fix-specific-skill-descriptions>

<fix-skill-source-precedence>
When multiple skill sources contain a skill with the same name, the last source wins.
```python
# If both sources contain "web-search", the one from "/skills/project/" wins.
agent = create_deep_agent(
    skills=["/skills/user/", "/skills/project/"],  # Last wins
    ...
)

CORRECT: Provide skills explicitly

agent = create_deep_agent( skills=["/main-skills/"], subagents=[{"name": "helper", "skills": ["/helper-skills/"], ...}] )

</python>
</fix-subagent-skills>