langchain-evolution-deck/research/per-tech/deepagents.md

Deep Agents

Что это в одном абзаце

Deep Agents — это Python-библиотека LangChain Inc., позиционируемая как «batteries-included agent harness». Построена поверх LangGraph (граф-рантайм) и langchain.agents.create_agent (минимальный harness от LangChain 1.0). Deep Agents добавляет opinionated defaults: встроенный planning tool, pluggable filesystem backend, subagent-ы для изоляции контекста, persistent memory через Store, human-in-the-loop middleware. Вдохновлена Claude Code, Deep Research и Manus — то есть это попытка формализовать то, что делает Claude Code, в виде переиспользуемой библиотеки. Важно: на дату snapshot 2026-06-22 формального major 1.0 для пакета не выпущено — последняя стабильная версия deepagents==0.6.11, хотя README и блог-посты уже описывают архитектуру как «1.0-ready».

Метаданные на дату snapshot 2026-06-22:

• GitHub stars: ~24.9k
• Latest stable (Python): deepagents==0.6.11 (от 18.06.2026)
• License: MIT
• JS-аналог: deepagents (npm, репо langchain-ai/deepagentsjs)

Источники:

• README github.com/langchain-ai/deepagents
• https://docs.langchain.com/oss/python/deepagents/overview
• https://www.langchain.com/blog/introducing-deepagents-cli
• https://medium.com/data-science-collective/building-deep-agents-with-langchain-1-0s-middleware-architecture-7fdbb3e47123

---

Ключевые API (≥ 0.6.x)

Импорты верхнего уровня

from deepagents import create_deep_agent
from deepagents.middleware import SubAgentMiddleware
from deepagents.backends import FilesystemBackend, SandboxBackend

Минимальный агент

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})

Subagents (делегирование в изолированный контекст)

from deepagents import create_deep_agent

research_agent = {
    "name": "research",
    "description": "Does deep web research",
    "system_prompt": "You are a research specialist.",
    "tools": [web_search],
}

writing_agent = {
    "name": "writer",
    "description": "Writes polished reports",
    "system_prompt": "You are a writing specialist.",
    "tools": [],
}

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    subagents=[research_agent, writing_agent],
)
# Main agent может вызывать subagents через `task` tool

Filesystem backend

from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    backend=FilesystemBackend(root_dir="./workspace"),
)
# Встроенные tools: read_file, write_file, edit_file, ls, glob, grep

Sandbox backend (для удалённого выполнения)

from deepagents.backends import SandboxBackend

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    backend=SandboxBackend(provider="daytona", api_key="..."),
)

Custom middleware (через LangChain 1.0 middleware)

from langchain.agents.middleware import HumanInTheLoopMiddleware
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"bash": True})],
)

Persistent memory через Store

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    store=store,
)
# Cross-session memory через `store` namespace

Skills (reusable behaviors)

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    skills=[
        {"name": "code_review", "path": "./skills/code_review.md"},
        {"name": "deploy", "path": "./skills/deploy.md"},
    ],
)

---

Что нового

Архитектурные изменения по сравнению с просто create_agent

• Planning tool write_todos — встроенный, не надо писать свой.
• Filesystem tools — read_file / write_file / edit_file / ls / glob / grep — стандартный набор.
• Subagent tool task — вызов child-агента с изолированным контекстом.
• Context management — суммаризация длинных тредов, offloading tool outputs на диск.
• Shell access — bash tool для выполнения команд.
• Pluggable backends — local filesystem или remote sandbox.
• Persistent memory — cross-session recall через Store.
• HITL middleware — approve/edit/reject tool calls до их исполнения.
• Skills system — переиспользуемые поведения, загружаемые on-demand.

Что нового в 0.6.x (последняя ветка на snapshot)

• Полная интеграция с LangChain 1.0 middleware-системой.
• Поддержка Send API для параллельных subagent-вызовов.
• Стабилизация плагинной системы backends.
• Улучшения в skills: версионирование и hot-reload.

---

Что нужно раскрыть в презентации

• Зачем Deep Agents поверх LangChain и LangGraph? — opinionated defaults, батарейки в комплекте.
• task tool и subagent isolation — почему subagent-ы получают свой контекст, а не общий.
• write_todos planning — как агент декомпозирует задачу.
• Filesystem как context overflow protection — большие результаты offload-ятся на диск.
• Sandbox backends — Daytona, Modal, Runloop, LangSmith — паттерн «isolate first, full permissions inside».
• Skills vs Tools — skills это «знания» (markdown-инструкции), tools это «действия».
• Security model — «trust the LLM», границы только на уровне tool / sandbox.
• Сравнение с Claude Code — попытка воспроизвести паттерн, но в виде библиотеки.

---

7 рабочих примеров кода Python

1. Hello world

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    system_prompt="You are a helpful assistant.",
)
result = agent.invoke({"messages": "Write a haiku about Python"})

2. С кастомным tool

from langchain.tools import tool
from deepagents import create_deep_agent

@tool
def get_stock_price(ticker: str) -> str:
    """Return current stock price."""
    return f"${ticker}: 123.45 USD"

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[get_stock_price],
)
result = agent.invoke({"messages": "What's the price of AAPL?"})

3. Subagent для делегирования

from deepagents import create_deep_agent

researcher = {
    "name": "researcher",
    "description": "Researches topics on the web",
    "system_prompt": "You do thorough research.",
    "tools": [],
}

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    subagents=[researcher],
)
result = agent.invoke({"messages": "Research quantum computing and write a 200-word summary"})

4. Filesystem backend

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    backend=FilesystemBackend(root_dir="./workspace"),
)
result = agent.invoke({"messages": "Create a file notes.md with Python best practices"})

5. HITL middleware

from langchain.agents.middleware import HumanInTheLoopMiddleware
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"bash": True, "write_file": True})],
)
# При попытке выполнить bash или write_file — interrupt, ждёт человека

6. Persistent memory

from langgraph.store.memory import InMemoryStore
from deepagents import create_deep_agent

store = InMemoryStore()
agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    store=store,
    system_prompt="Remember user preferences.",
)
# Store put/get вызываются изнутри нод агента

7. Skills (загрузка поведений)

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    tools=[],
    skills=["./skills/code_review.md", "./skills/deploy.md"],
)
# Агент загрузит skill когда посчитает нужным

---

TypeScript-аналог

import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "openai:gpt-4.1",
  tools: [],
  systemPrompt: "You are a helpful assistant.",
});

const result = await agent.invoke({ messages: "Write a haiku" });

JS-версия (langchain-ai/deepagentsjs) покрывает базовый API, но filesystem/sandbox backend-ы и subagents-конфигурация могут отставать от Python.

---

Плюсы и минусы текущей версии (0.6.x)

Плюсы

• Batteries included — planning + filesystem + subagents + skills из коробки.
• Меньше boilerplate чем LangGraph, opinionated defaults.
• Плагинные backends — local / Daytona / Modal / Runloop / LangSmith.
• Skills system — переиспользуемые поведения on-demand.
• Open source + MIT — можно форкать и адаптировать.
• Хорошо документированный security model — «trust the LLM, restrict at tool level».

Минусы

• Major 1.0 не зафиксирован — нумерация 0.6.x может означать breaking changes в minor.
• Opinionated — если дефолты не подходят, override-ы могут быть сложными.
• Sandbox providers требуют внешние аккаунты — Daytona / Modal / Runloop — это SaaS.
• Skills — новый концепт — экосистема готовых skills ещё формируется.
• Документация по middleware+skills — некоторые edge cases не покрыты.
• Performance overhead — плагинная архитектура добавляет latency.

---

Заметки для презентации

• Подчеркнуть иерархию: LangGraph = runtime, LangChain.create_agent = thin harness, Deep Agents = opinionated harness.
• Использовать аналогию: Deep Agents = "Django поверх raw WSGI", даёт быстрый старт, но с conventions.
• Показать, как task tool позволяет main agent делегировать без загрязнения своего контекста.
• Объяснить, почему именно Claude Code вдохновил — это конкурентный аргумент: «посмотрите, что сделал Anthropic, мы сделали то же в open source».
• Если рассказывать про Open SWE — это реальный пример использования Deep Agents как harness-а для кодинг-агента.