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)

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

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

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

```python
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 (делегирование в изолированный контекст)

```python
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

```python
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 (для удалённого выполнения)

```python
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)

```python
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

```python
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)

```python
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

```python
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

```python
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 для делегирования

```python
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

```python
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

```python
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

```python
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 (загрузка поведений)

```python
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-аналог

```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-а** для кодинг-агента.