К основному содержанию
скилл CX Codex

deepagents-architecture — скилл для Claude Code: обзор и установка

Скилл deepagents-architecture помогает выбрать архитектуру для приложений на Deep Agents, спланировать субагентов, настроить цепочки middleware и схему хранения данных.

Apache-2.0 162 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill deepagents-architecture -a claude-code
Открыть на GitHub

Что делает deepagents-architecture

Скилл формализует архитектурный выбор перед реализацией агентов. Он сверяет сценарий с каталогом альтернатив: если задача решается одиночным запросом к LLM, простым RAG-пайплайном на LangChain LCEL или не требует файловых правок, скилл рекомендует прямые вызовы API, чистый LangGraph или create_react_agent.

Внутри заложены правила выбора бэкендов: временный StateBackend, дисковый FilesystemBackend, долговременный межпоточный StoreBackend и гибридный CompositeBackend с маршрутизацией путей вроде /memories/. Для сохранения данных между сессиями через StoreBackend потребуется настроенное хранилище store из LangGraph, а для FilesystemBackend обязателен путь root_dir.

Модуль также разбирает порядок встроенных middleware: планирование через TodoListMiddleware, операции с файловой системой, делегирование через SubAgentMiddleware, сжатие контекста при достижении ~85% объема или 170k токенов в SummarizationMiddleware, кеширование Anthropic и паузы HumanInTheLoopMiddleware.

Какие задачи решает

  • сопоставить требования проекта с альтернативами вроде прямого вызова API, LangChain LCEL или чистого LangGraph
  • выбрать подходящий бэкенд хранения данных между StateBackend, FilesystemBackend, StoreBackend и маршрутами CompositeBackend
  • спроектировать изоляцию подзадач с помощью параллельных исследователей, специализированных субагентов или готовых графов CompiledSubAgent
  • настроить порядок выполнения цепочки middleware, включая автоматическую суммаризацию контекста и паузы для подтверждения человеком

Примеры запросов агенту

  • Помоги выбрать архитектуру между чистым LangGraph и Deep Agents для проекта с частыми правками локальных файлов.
  • Как настроить CompositeBackend в Deep Agents, чтобы связать StateBackend для рабочих файлов и StoreBackend для долгосрочных настроек?
  • Спроектируй структуру специализированных субагентов для параллельного анализа данных без переполнения контекста основного агента.

Как установить deepagents-architecture

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill deepagents-architecture -a claude-code

2Вручную: положить файлы

~/.claude/skills/deepagents-architecture/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/deepagents-architecture/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о deepagents-architecture

Как установить deepagents-architecture в Claude Code?

Выполните команду npx skills add existential-birds/beagle --skill deepagents-architecture -a claude-code. Также файл инструкции можно поместить напрямую в ~/.claude/skills/deepagents-architecture/SKILL.md.

В каких ситуациях Deep Agents избыточен?

Если нужен один вызов модели, достаточно прямого API. Для базового RAG проще взять LangChain LCEL, для произвольного графа управления — чистый LangGraph, а если файловые операции отсутствуют — агент create_react_agent.

Когда встроенный SummarizationMiddleware сжимает контекст?

Сжатие контекста активируется автоматически при заполнении контекстного окна примерно на 85% либо по достижении 170k токенов.

Исходный текст

SKILL.md · Apache-2.0
---
name: deepagents-architecture
description: Guides architectural decisions for Deep Agents applications. Use when deciding between Deep Agents vs alternatives, choosing backend strategies, designing subagent systems, or selecting middleware approaches.
---

# Deep Agents Architecture Decisions

## When to Use Deep Agents

### Use Deep Agents When You Need:

- **Long-horizon tasks** - Complex workflows spanning dozens of tool calls
- **Planning capabilities** - Task decomposition before execution
- **Filesystem operations** - Reading, writing, and editing files
- **Subagent delegation** - Isolated task execution with separate context windows
- **Persistent memory** - Long-term storage across conversations
- **Human-in-the-loop** - Approval gates for sensitive operations
- **Context management** - Auto-summarization for long conversations

### Consider Alternatives When:

| Scenario | Alternative | Why |
|----------|-------------|-----|
| Single LLM call | Direct API call | Deep Agents overhead not justified |
| Simple RAG pipeline | LangChain LCEL | Simpler abstraction |
| Custom graph control flow | LangGraph directly | More flexibility |
| No file operations needed | `create_react_agent` | Lighter weight |
| Stateless tool use | Function calling | No middleware needed |

## Backend Selection

### Backend Comparison

| Backend | Persistence | Use Case | Requires |
|---------|-------------|----------|----------|
| `StateBackend` | Ephemeral (per-thread) | Working files, temp data | Nothing (default) |
| `FilesystemBackend` | Disk | Local development, real files | `root_dir` path |
| `StoreBackend` | Cross-thread | User preferences, knowledge bases | LangGraph `store` |
| `CompositeBackend` | Mixed | Hybrid memory patterns | Multiple backends |

### Backend Decision Tree

```
Need real disk access?
├─ Yes → FilesystemBackend(root_dir="/path")
└─ No
   └─ Need persistence across conversations?
      ├─ Yes → Need mixed ephemeral + persistent?
      │  ├─ Yes → CompositeBackend
      │  └─ No → StoreBackend
      └─ No → StateBackend (default)
```

### CompositeBackend Routing

Route different paths to different storage backends:

```python
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Working files (ephemeral)
        routes={
            "/memories/": StoreBackend(store=store),    # Persistent
            "/preferences/": StoreBackend(store=store), # Persistent
        },
    ),
)
```

## Subagent Architecture

### When to Use Subagents

**Use subagents when:**
- Task is complex, multi-step, and can run independently
- Task requires heavy context that would bloat the main thread
- Multiple independent tasks can run in parallel
- You need isolated execution (sandboxing)
- You only care about the final result, not intermediate steps

**Don't use subagents when:**
- Task is trivial (few tool calls)
- You need to see intermediate reasoning
- Splitting adds latency without benefit
- Task depends on main thread state mid-execution

### Subagent Patterns

#### Pattern 1: Parallel Research
```
         ┌─────────────┐
         │  Orchestrator│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Task A│  │Task B│  │Task C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  Synthesize │
      └─────────────┘
```

Best for: Research on multiple topics, parallel analysis, batch processing.

#### Pattern 2: Specialized Agents
```python
research_agent = {
    "name": "researcher",
    "description": "Deep research on complex topics",
    "system_prompt": "You are an expert researcher...",
    "tools": [web_search, document_reader],
}

coder_agent = {
    "name": "coder",
    "description": "Write and review code",
    "system_prompt": "You are an expert programmer...",
    "tools": [code_executor, linter],
}

agent = create_deep_agent(subagents=[research_agent, coder_agent])
```

Best for: Domain-specific expertise, different tool sets per task type.

#### Pattern 3: Pre-compiled Subagents
```python
from deepagents import CompiledSubAgent, create_deep_agent

# Use existing LangGraph graph as subagent
custom_graph = create_react_agent(model=..., tools=...)

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom-workflow",
        description="Runs specialized workflow",
        runnable=custom_graph
    )]
)
```

Best for: Reusing existing LangGraph graphs, complex custom workflows.

## Middleware Architecture

### Built-in Middleware Stack

Deep Agents applies middleware in this order:

1. **TodoListMiddleware** - Task planning with `write_todos`/`read_todos`
2. **FilesystemMiddleware** - File ops: `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`
3. **SubAgentMiddleware** - Delegation via `task` tool
4. **SummarizationMiddleware** - Auto-summarizes at ~85% context or 170k tokens
5. **AnthropicPromptCachingMiddleware** - Caches system prompts (Anthropic only)
6. **PatchToolCallsMiddleware** - Fixes dangling tool calls from interruptions
7. **HumanInTheLoopMiddleware** - Pauses for approval (if `interrupt_on` configured)

### Custom Middleware Placement

```python
from langchain.agents.middleware import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    tools = [my_custom_tool]

    def transform_request(self, request):
        # Modify system prompt, inject context
        return request

    def transform_response(self, response):
        # Post-process, log, filter
        return response

# Custom middleware added AFTER built-in stack
agent = create_deep_agent(middleware=[MyMiddleware()])
```

### Middleware vs Tools Decision

| Need | Use Middleware | Use Tools |
|------|----------------|-----------|
| Inject system prompt content | ✅ | ❌ |
| Add tools dynamically | ✅ | ❌ |
| Transform requests/responses | ✅ | ❌ |
| Standalone capability | ❌ | ✅ |
| User-invokable action | ❌ | ✅ |

### Subagent Middleware Inheritance

Subagents receive their own middleware stack by default:
- TodoListMiddleware
- FilesystemMiddleware (shared backend)
- SummarizationMiddleware
- AnthropicPromptCachingMiddleware
- PatchToolCallsMiddleware

Override with `default_middleware=[]` in SubAgentMiddleware or per-subagent `middleware` key.

## Gates: architecture decisions before implementation

Complete **in order**. A step **passes** only when the stated artifact exists in the design note, ADR stub, or ticket; internal intent alone does not count.

1. **Fit** - Confirm Deep Agents vs alternatives (see tables above).
   - **Pass:** Short written rationale that either names one matching "Use Deep Agents When You Need" bullet **or** one "Consider Alternatives" row plus the chosen alternative.

2. **Backend** - Match the Backend Decision Tree to a concrete choice.
   - **Pass:** Backend name(s) from the Backend Comparison table; if `FilesystemBackend` or `CompositeBackend`, `root_dir` and any route prefixes are written down (path placeholders OK).

3. **Subagents** - Decide delegation boundaries.
   - **Pass:** Either "no subagents" plus one sentence why **or** a named list where each subagent maps to at least one "When to Use Subagents" reason; parallel plans state what merges outputs.

4. **Human-in-the-loop** - Approval surface.
   - **Pass:** Explicit list of tools/operations that use `interrupt_on`, **or** "no HITL" plus one-line risk acceptance.

5. **Middleware** - Custom vs built-in only.
   - **Pass:** Either "custom middleware: none" **or** each custom piece named, placed after the built-in stack, and tied to prompt injection, tools, or request/response transforms.

6. **Context** - Long threads and large inputs.
   - **Pass:** Stated plan for default summarization behavior (~85% context / ~170k tokens) or an alternative cap; large files handled via references/chunking or equivalent, named in text.

7. **Checkpointing** - Resume and durability.
   - **Pass:** Checkpoint/checkpointer approach named for the graph **or** "none" with one-line rationale (e.g. ephemeral demo only).

© existential-birds · Apache-2.0 · existential-birds/beagle

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
deepagents-setup-configuration soba-labs Скилл deepagents-setup-configuration для Claude Code создаёт и проверяет проекты Deep Agents на Python или JavaScript. Помогает настроить субагентов, память и подтверждение действий человеком. CX Codex +1 ★ 106звёзд репо deepagents-python-quickstart langchain-ai Скилл deepagents-python-quickstart собирает минимального Deep Agent на Python по живому quickstart LangChain: спрашивает модель, поднимает отдельную папку проекта, меняет Tavily на встроенный поиск провайдера. CX Codex +1 5 900установок langchain-dev-guide ob-labs Скилл langchain-dev-guide для Claude Code помогает разбирать проблемы LangChain и LangGraph. Включается при сбоях, выборе архитектуры и подключении моделей. CX Codex +1 895установок langchain-architecture Seth Hobson Скилл langchain-architecture для Claude Code помогает проектировать LLM-приложения на LangChain 1.x и LangGraph: агентов, память, состояние и вызов инструментов. Разбирает сложные AI-воркфлоу. CX Codex +1 13 150установок express-microservices-architecture manutej Скилл express-microservices-architecture обучает ассистента паттернам микросервисов на Express.js: от API-шлюзов до распределённых транзакций Saga. Помогает проектировать надёжные бэкенд-сервисы. CX Codex +1 450установок architecture-design Galaxy-Dawn Скилл architecture-design для Claude Code задаёт структуру ML-проекта с фабриками и реестрами компонентов. Создаёт датасеты и модели с декораторами регистрации. CX Codex +1 387установок

Из того же набора68

Весь набор →
shadcn-code-review Скилл shadcn-code-review проверяет React-компоненты на базе shadcn/ui, Radix и Tailwind CSS на доступность, работу с CVA и шаблоны asChild. Помогает находить ошибки в кастомной вёрстке. CX Codex +1 206установок react-router-code-review Скилл react-router-code-review для Claude Code проверяет код роутинга в React Router v6.4 и новее: лоадеры, экшены, границы ошибок и навигацию. CX Codex +1 202установок swift-testing-code-review Скилл swift-testing-code-review проверяет тесты Swift Testing: макросы, параметризованные и асинхронные сценарии, организацию наборов. Нужен при ревью .swift-файлов. CX Codex +1 196установок docs-style Скилл docs-style задаёт правила редполитики для технической документации: выбор формата по Diataxis, активный залог и структура для людей и нейросетей. CX Codex +1 180установок pydantic-ai-tool-system Скилл pydantic-ai-tool-system помогает агенту корректно объявлять инструменты PydanticAI с нужными декораторами, докстрингами и типами контекста. CX Codex +1 161установок langgraph-implementation Скилл langgraph-implementation помогает собирать состояния графов LangGraph, задавать узлы и переходы, добавлять сохранение и паузы для участия человека. CX Codex +1 161установок postgres-code-review Скилл postgres-code-review проверяет SQL, схемы и код работы с PostgreSQL: ищет проблемы с индексами, JSONB, соединениями и транзакциями. Подключайте его при ревью изменений в базе. CX Codex +1 158установок explanation-docs Скилл explanation-docs для Claude Code помогает писать документы о том, как и почему устроена система. Документирует архитектурные решения и материалы для онбординга. CX Codex +1 152установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой