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

# Open SWE

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

Open SWE — это open-source фреймворк LangChain Inc. для построения **внутренних кодинг-агентов организации**. Анонсирован в августе 2025, стабильная версия репозитория набрала 971+ коммитов и 10k stars к июню 2026. Open SWE — это **не готовое SaaS-решение**, а стартовый шаблон: он скомпонован поверх Deep Agents (а значит поверх LangGraph), поддерживает pluggable sandbox-провайдеры (Modal, Daytona, Runloop, LangSmith), триггеры из Slack / Linear / GitHub, и автоматически создаёт draft PR. Архитектура намеренно воспроизводит паттерны, которые Stripe (Minions), Ramp (Inspect) и Coinbase (Cloudbot) построили как proprietary — Open SWE даёт open-source реализацию «reference architecture» для кастомных внутренних coding agent-ов.

**Метаданные на дату snapshot 2026-06-22:**
- GitHub stars: ~10k
- Commits: 971+ (активная разработка)
- License: MIT
- JS-аналог: нет (Python-only проект, плюс TypeScript UI в `ui/`)
- Главный blog-пост: первоначальный анонс — август 2025, переработанная версия — 17 марта 2026

**Источники:**
- README `github.com/langchain-ai/open-swe` (raw-форма успешно получена)
- `blog.langchain.com/open-swe-an-open-source-framework-for-internal-coding-agents`
- https://github.com/langchain-ai/open-swe/blob/main/INSTALLATION.md
- https://github.com/langchain-ai/open-swe/blob/main/CUSTOMIZATION.md

---

## Ключевые API и архитектурные компоненты

Open SWE — это не библиотека, а **приложение**, состоящее из backend-агента (Python), UI (TypeScript), и набора middleware/интеграций. Поэтому «API» здесь — это точки расширения, через которые организация кастомизирует фреймворк.

### Импорты внутри Open SWE

```python
from open_swe.agent import create_agent  # точка входа в агент
from open_swe.middleware import (
    check_message_queue_before_model,
    notify_step_limit_reached,
    open_pr_if_needed,
    ToolErrorMiddleware,
)
from open_swe.sandbox import (
    SandboxBackend,
    ModalBackend,
    DaytonaBackend,
    RunloopBackend,
    LangSmithBackend,
)
from open_swe.tools import (
    execute,
    fetch_url,
    http_request,
    linear_comment,
    slack_thread_reply,
)
```

### Основная точка расширения — `create_deep_agent`

```python
from deepagents import create_deep_agent
from open_swe.middleware import check_message_queue_before_model
from open_swe.sandbox import DaytonaBackend

agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    system_prompt=construct_system_prompt(repo_dir, ...),
    tools=[
        execute,
        fetch_url,
        http_request,
        linear_comment,
        slack_thread_reply,
    ],
    backend=DaytonaBackend(api_key="..."),
    middleware=[
        ToolErrorMiddleware(),
        check_message_queue_before_model,
        open_pr_if_needed,
    ],
)
```

### Sandboxes (pluggable)

```python
from open_swe.sandbox import DaytonaBackend, ModalBackend, RunloopBackend

backend = DaytonaBackend(api_key="...")
# или ModalBackend(token_id="...", token_secret="...")
# или RunloopBackend(api_key="...")
```

Каждый backend — изолированный Linux-контейнер с полным shell-доступом, клоном репозитория и persistent state для thread-а.

### Triggers (поверхности вызова)

- **Slack** — `@openswe` в любом thread. Поддерживает синтаксис `repo:owner/name`.
- **Linear** — `@openswe` в комментарии к issue.
- **GitHub** — `@openswe` в PR-комментарии для авто-ответа на review.

Каждый триггер создаёт deterministic thread_id, чтобы follow-up сообщения маршрутизировались в тот же запущенный агент.

### Built-in tools

| Tool | Назначение |
|---|---|
| `execute` | shell-команды в sandbox |
| `fetch_url` | загрузка web-страниц как markdown |
| `http_request` | API calls (GET, POST, etc.) |
| `linear_comment` | комментарии в Linear-тикетах |
| `slack_thread_reply` | ответы в Slack-тредах |
| `read_file` / `write_file` / `edit_file` / `ls` / `glob` / `grep` | Deep Agents filesystem tools |
| `write_todos` | planning tool от Deep Agents |
| `task` | spawning subagent-ов |

GitHub-операции делаются через `gh` CLI внутри sandbox с `GH_TOKEN=dummy`, авторизация через LangSmith-прокси.

### AGENTS.md конвенция

Если в репозитории есть файл `AGENTS.md` в корне, он автоматически читается из sandbox и инжектится в system prompt. Это «правила команды» — conventions, testing requirements, архитектурные решения.

### Middleware (точки расширения)

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

class MyCustomMiddleware(AgentMiddleware):
    def before_model(self, state, runtime):
        # модифицировать state перед model call
        return state

    def after_model(self, state, runtime):
        # логирование / проверка результата
        return state
```

Типичные middleware в Open SWE:
- `check_message_queue_before_model` — инжектит follow-up сообщения до следующего model call.
- `notify_step_limit_reached` — после-agent hook для Slack-уведомления, если лимит исчерпан.
- `open_pr_if_needed` — safety net: коммитит и открывает PR, если агент этого не сделал.
- `ToolErrorMiddleware` — graceful handling ошибок tool-ов.

### Customization точка: `CUSTOMIZATION.md`

Согласно документации, pluggable компоненты:
1. **Sandbox provider** — Modal / Daytona / Runloop / LangSmith / свой.
2. **Model** — любой провайдер через `langchain.chat_models.init_chat_model`.
3. **Tools** — добавить/удалить через массив `tools`.
4. **Triggers** — модифицировать Slack / Linear / GitHub интеграции.
5. **System prompt** — база + логика инкорпорирования AGENTS.md.
6. **Middleware** — добавить свой для validation / approval / logging.

---

## Что нового в первом релизе

### Оригинальный анонс (август 2025)
- Multi-agent архитектура: Manager + Planner + Programmer + Reviewer.
- Single sandbox (Daytona).
- GitHub Issues + Web UI триггеры.

### Переработанная архитектура (март 2026)
- Замена multi-agent на единый `create_deep_agent` harness + subagents + middleware.
- Добавление pluggable sandbox providers (Modal, Runloop, LangSmith).
- Добавление Slack и Linear триггеров.
- Subagent-ы через `task` tool от Deep Agents.
- Middleware-система для deterministic orchestration.

### Ключевой сдвиг
Open SWE **переехал с multi-agent на single-deep-agent-harness + subagents**. Это консолидация архитектурного паттерна: вместо явных Manager/Planner/Programmer/Reviewer — один главный агент с набором subagent-специализаций и middleware для orchestration. Бенефиты: upgrade path (подтягивать улучшения Deep Agents), меньше кастомного кода, чище orchestration через `Send` API.

---

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

- **Почему «внутренний» кодинг-агент, а не IDE-assistant** — модель «colleague, not copilot».
- **«Trust the LLM» внутри sandbox** — изоляция важнее confirmation prompts.
- **Pluggable sandboxes** — почему несколько провайдеров и как мигрировать.
- **AGENTS.md как организационный паттерн** — те же conventions применяются и для AI.
- **Subagent isolation** — каждый child получает свой контекст.
- **Middleware для validation** — детерминированные проверки между шагами агента.
- **Сравнение со Stripe Minions / Ramp Inspect / Coinbase Cloudbot** — почему конвергенция паттернов важна.
- **Open source как reference architecture** — не finished product, а стартовая точка.

---

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

### 1. Минимальный запуск агента Open SWE (из README)

```python
from deepagents import create_deep_agent
from open_swe.sandbox import DaytonaBackend
from open_swe.middleware import check_message_queue_before_model, open_pr_if_needed

agent = create_deep_agent(
    model="openai:gpt-5.5",
    system_prompt="You are an internal coding agent.",
    tools=[],  # будут добавлены built-in
    backend=DaytonaBackend(api_key="..."),
    middleware=[check_message_queue_before_model, open_pr_if_needed],
)
```

### 2. Кастомный system prompt с инкорпорированием AGENTS.md

```python
def construct_system_prompt(repo_dir: str, base_prompt: str) -> str:
    agents_md_path = Path(repo_dir) / "AGENTS.md"
    extra = ""
    if agents_md_path.exists():
        extra = f"\n\nRepository rules:\n{agents_md_path.read_text()}"
    return base_prompt + extra
```

### 3. Кастомный middleware для логирования

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

class AuditMiddleware(AgentMiddleware):
    def __init__(self, logger):
        self.logger = logger

    def after_model(self, state, runtime):
        self.logger.info(f"model_called_at_step_{state.get('step')}")
        return state
```

### 4. Subagent-конфигурация для специализаций

```python
test_runner = {
    "name": "test_runner",
    "description": "Runs project tests and reports results",
    "system_prompt": "You run tests, parse failures, suggest fixes.",
    "tools": ["execute", "read_file"],
}

doc_writer = {
    "name": "doc_writer",
    "description": "Updates documentation after code changes",
    "system_prompt": "You update markdown docs based on code changes.",
    "tools": ["read_file", "edit_file"],
}

agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    tools=[],
    subagents=[test_runner, doc_writer],
)
```

### 5. Кастомный sandbox backend (заглушка)

```python
from open_swe.sandbox import SandboxBackend

class MyInternalBackend(SandboxBackend):
    def __init__(self, connection_string: str):
        self.conn = connection_string

    def execute(self, command: str) -> str:
        # подключение к внутреннему devbox-пулу
        return self._run_in_devbox(command)

    def read_file(self, path: str) -> str:
        return self._fetch_from_devbox(path)
```

---

## TypeScript

**UI:** репозиторий содержит `ui/` (TypeScript, 26.6% от кода). Это web-приложение для управления: GitHub login, per-user model/profile settings, team defaults, enabled-repo management, chat UI.

```typescript
// Пример из ui/ (псевдокод, точная структура зависит от версии)
import { OpenSWEClient } from "@openswe/client";

const client = new OpenSWEClient({
  langsmithApiKey: process.env.LANGSMITH_API_KEY,
});

await client.invoke({
  threadId: "issue-123",
  prompt: "Fix the bug in src/auth.py",
  repo: "owner/name",
});
```

**Где нет TS-аналога для backend:** Open SWE — это Python-приложение (LangGraph/Deep Agents), TypeScript только в UI-слое.

---

## Плюсы и минусы

### Плюсы
- **MIT license** — можно форкать и адаптировать.
- **Pluggable sandbox** — Modal / Daytona / Runloop / LangSmith / свой.
- **Subagents + middleware** — composable вместо monolithic.
- **AGENTS.md convention** — переиспользует существующий паттерн документации.
- **Multiple triggers** — Slack / Linear / GitHub / Web UI.
- **Built on Deep Agents** — automatic upgrade path для improvements.
- **Хорошая документация** — INSTALLATION.md и CUSTOMIZATION.md детальные.
- **Active development** — 971+ коммитов, 10k stars.

### Минусы
- **Не finished product** — нужно кастомизировать под свою org.
- **Sandbox costs** — Modal / Daytona / Runloop требуют платных аккаунтов.
- **Slack / Linear / GitHub интеграции** — нужен OAuth setup для каждого.
- **Security model «trust the LLM»** — высокие требования к sandbox-изоляции.
- **Production deployment сложный** — требует LangSmith, GitHub App, sandbox provider, secrets management.
- **Observability** — нужен Datadog или LangSmith setup.
- **Документация быстро устаревает** — архитектура переписывалась за 9 месяцев.

---

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

- Это **reference architecture, not product**. Подчеркнуть, что каждый компонент заменяем.
- Использовать аналогию: **Open SWE = «Kubernetes для AI агентов»** — даёт framework, но ожидает ops-работу.
- Показать, как именно Open SWE воспроизводит паттерны Stripe/Ramp/Coinbase — это главный аргумент «convergence proof».
- Если есть audience с enterprise-бэкграундом — акцент на **sandbox isolation как security primitive**.
- Подчеркнуть, что Open SWE **не замена Cursor или Claude Code**, а инфраструктура для «своего Claude Code».
- Если показывать схему архитектуры — выделить слои: Harness (Deep Agents) → Sandbox (pluggable) → Tools (curated) → Context (AGENTS.md) → Orchestration (subagents + middleware) → Invocation (Slack/Linear/GitHub) → Validation (prompt + middleware).