WAT-фреймворк — Воркфлоу, Агент, Инструменты

Модуль: 3. WAT-фреймворк | Время: ~35 мин теории + 30 мин практики

Суть урока

Хорошая кухня состоит из трёх частей: рецепта (что и в каком порядке делать), ингредиентов (конкретные продукты) и шеф-повара (тот кто читает рецепт и использует ингредиенты). Убери любую часть — ничего не выйдет. WAT — это та же логика для агентных систем.

Ключевые концепции

WAT = Workflows + Agent + Tools — три неотделимые части системы
Воркфлоу (воркфлоу — рабочий процесс, поток задач) = рецепт на естественном языке (markdown — Markdown — язык разметки текста)
Инструменты = конкретные действия (вызовы API — интерфейса программирования приложений, скрипты)
Агент (агент — автономная программа-исполнитель) = исполнитель который читает рецепт и использует ингредиенты
Структура папок WAT-проекта
Как агент улучшает систему со временем

Теория

Три компонента: от абстракции к реальности

Большинство людей которые слышат «агентный AI» думают просто об «умном чат-боте». Но настоящие агентные системы устроены сложнее — и в этой сложности скрыта вся мощь.

WAT-фреймворк — простой способ думать об архитектуре любой агентной системы.

W — Workflows (Воркфлоу)

A — Agent (Агент)

T — Tools (Инструменты)

Каждый компонент выполняет свою роль. Вместе они образуют систему которая может выполнять сложные многошаговые задачи.

W: Воркфлоу — рецепт на естественном языке

🎨 Образ: Воркфлоу — как рецепт в кулинарной книге. Написан на обычном языке, понятен любому кто умеет читать. Не нужно быть химиком чтобы понять «добавь соль». Не нужно быть программистом чтобы понять «найди 5 новостей и отправь письмо».

Воркфлоу — это пошаговая инструкция написанная на обычном языке (markdown). Это рецепт который агент будет выполнять.

Что входит в воркфлоу:

Цель: что должно произойти в результате
Шаги: что делать и в каком порядке
Условия: что делать если что-то пошло не так
Инструменты: какие инструменты использовать на каком шаге
Точки проверки: где нужно подтверждение человека

Пример воркфлоу для еженедельного newsletter:

Напиши в чат

# Воркфлоу: Еженедельный Newsletter о Недвижимости

## Цель
Собрать 5 актуальных новостей, сгенерировать HTML-письмо, 
отправить списку получателей каждый понедельник в 9:00.

## Шаги

### Шаг 1: Сбор новостей
Используй инструмент `research_news` для поиска.
Запрос: "рынок недвижимости [текущая неделя]"
Ожидаемый результат: 5-7 новостей с заголовком, кратким описанием и ссылкой.

### Шаг 2: Генерация письма
Используй инструмент `generate_newsletter_html`.
Передай: список новостей из шага 1, текущую дату.
Стиль: смотри /config/newsletter_style.json.

### Шаг 3: ⚠️ ЧЕЛОВЕЧЕСКАЯ ПРОВЕРКА
Останови выполнение. Покажи HTML-превью.
Жди подтверждения перед отправкой.

### Шаг 4: Отправка
Используй инструмент `send_via_gmail`.
Получатели: из /config/recipients.json.
Тема: "Дайджест недвижимости: [текущая дата]"

### Шаг 5: Архивирование
Сохрани финальный HTML в /archive/YYYY-MM-DD.html.
Запиши в лог: дата отправки, количество получателей, тема.

Обрати внимание: воркфлоу написан на русском языке, не на Python (Питон — язык программирования). Это принципиально. Его может читать и редактировать любой человек — не только разработчик. Это делает систему понятной и управляемой.

T: Инструменты — конкретные действия

🎨 Образ: Инструменты — как отдельные специалисты в бригаде. Один умеет только класть плитку. Другой только красить. Третий только электрику. Каждый делает своё — никто не лезет в чужую зону. Агент-прораб решает кого звать на каждом этапе.

Инструменты — это исполняемые функции. Если воркфлоу говорит «используй инструмент research_news» — это значит вызови конкретный скрипт или API.

Каждый инструмент делает одну конкретную вещь. Принцип: одна функция — одна ответственность.

Примеры инструментов:

Инструмент	Что делает	Технически
`research_news`	Ищет новости по теме	Вызов Perplexity API
`generate_newsletter_html`	Создаёт HTML из данных	Вызов Anthropic API + шаблон
`send_via_gmail`	Отправляет письмо	Gmail API через OAuth
`archive_to_sheets`	Записывает в Google Sheets	Google Sheets API
`generate_infographic`	Создаёт изображение	Image generation API

Структура типичного инструмента (Python):

python

# tools/research_news.py

def research_news(query: str, num_results: int = 5) -> list[dict]:
    """
    Ищет новости по запросу через Perplexity API.
    
    Возвращает список словарей: [{title, description, url, date}]
    """
    # вызов API
    # обработка ответа
    # возврат структурированных данных

Инструменты не принимают решений. Они просто выполняют конкретное действие и возвращают результат. Решения принимает агент на основе воркфлоу.

A: Агент — шеф-повар

Агент — это сам Claude Code (или другая LLM — большая языковая модель). Он:

Читает воркфлоу (рецепт)
Выбирает какой инструмент использовать на каком шаге
Передаёт данные между инструментами
Обрабатывает нестандартные ситуации
Останавливается в нужных местах для проверки человеком
Адаптируется если что-то пошло не так

Главная сила агента — адаптивность.

Если инструмент research_news вернул только 3 новости вместо 5 — детерминированная автоматизация упадёт с ошибкой. Агент адаптируется: сделает повторный поиск с другим запросом, или продолжит с тремя новостями, или спросит тебя как поступить.

Если новость оказалась на английском — агент сам переведёт, потому что понимает что newsletter на русском (это написано в CLAUDE.md).

Взаимодействие трёх компонентов

Код

Воркфлоу (рецепт)
       ↓ читает
    Агент
    ↙   ↘  вызывает
Инструмент1  Инструмент2
    ↘   ↙  получает результаты
    Агент
       ↓ продолжает по воркфлоу
    ...следующий шаг...

Воркфлоу без инструментов = рецепт без ингредиентов.

Написал «смешай муку с яйцами» — но нет ни муки, ни яиц. Воркфлоу с инструкциями «ищи новости» бесполезен если нет инструмента который умеет искать.

Инструменты без воркфлоу = ингредиенты без рецепта.

У тебя есть мука, яйца, сахар, молоко. Что из них приготовить? Хаос выбора. Инструменты без воркфлоу не дают системе направления.

Агент без воркфлоу и инструментов = шеф без кухни.

Умный, опытный — но без рецепта и ингредиентов ничего не приготовит.

🎨 Образ: WAT без одной из частей — как оркестр без дирижёра (агент), без нот (воркфлоу) или без инструментов (tools). Каждый компонент незаменим. Можно сыграть концерт из трёх скрипок, но нельзя — из дирижёра и нот без скрипок.

Структура папок WAT-проекта

Вот стандартная структура которую ты будешь использовать для каждого проекта:

Код

my-project/
├── CLAUDE.md                    ← системный промпт (промпт — текстовый запрос к AI), см. урок про CLAUDE.md
├── .env                         ← API ключи (никогда в git (гит — система контроля версий кода)!)
├── main.py                      ← точка входа
│
├── workflows/                   ← Воркфлоу
│   ├── main_workflow.md         ← главный воркфлоу
│   └── fallback_workflow.md     ← запасной при ошибках
│
├── tools/                       ← Инструменты
│   ├── research.py              ← поиск информации
│   ├── generate_content.py      ← генерация контента
│   ├── send_email.py            ← отправка писем
│   └── archive.py               ← архивирование
│
├── config/                      ← Конфигурация
│   ├── style.json               ← стиль, цвета, параметры
│   └── recipients.json          ← получатели/параметры
│
├── brand_assets/                ← Брендовые материалы
│   ├── logo.png                 ← логотип
│   └── brand_guidelines.md     ← правила бренда
│
├── docs/                        ← Документация (опционально)
│   └── api-reference.md
│
└── logs/                        ← Автоматические логи
    └── (создаётся автоматически)

Почему именно такая структура:

Все воркфлоу в одном месте → легко найти и изменить
Каждый инструмент в отдельном файле → легко заменить или улучшить один
Конфиги отдельно от кода → меняешь настройки не трогая код
Brand assets отдельно → агент знает откуда брать брендовые материалы
.env в корне → стандартное место для ключей

Как агент улучшает систему со временем

🎨 Образ: После первого сезона шеф-повар смотрит на отзывы: «борщ хвалят, рыба возвращается недоеденной». Он улучшает меню. Агент делает то же самое с логами: анализирует паттерны, предлагает улучшения. Система умнеет от использования.

Это важная особенность WAT которую часто недооценивают.

После нескольких запусков воркфлоу агент начинает видеть паттерны:

«Каждый раз когда ищу новости про вторичный рынок — результаты хуже. Может уточнить запрос?»
«Этот инструмент часто возвращает дублирующиеся новости — добавить дедупликацию?»
«Письма открывают лучше когда тема содержит дату — включить это в шаблон?»

Ты можешь попросить агента:

Напиши в чат

Проанализируй последние 10 запусков newsletter воркфлоу в /logs/.
Что работает хорошо? Что стоит улучшить?
Предложи конкретные изменения в воркфлоу или инструментах.

Агент прочитает логи, проанализирует, предложит конкретные изменения. Это и есть «агент улучшает систему» — не магически, а через анализ реальных данных.

Реальный пример структуры: Lead Qualifier (квалификация лидов)

Код

lead-qualifier/
├── CLAUDE.md                        ← системный промпт
├── .env                             ← API-ключи (CRM (си-ар-эм, Customer Relationship Management — управление отношениями с клиентами), email, Anthropic)
├── .gitignore                       ← исключить .env, logs/, node_modules/
├── main.py                          ← точка входа
│
├── workflows/
│   ├── qualify_lead.md              ← главный воркфлоу квалификации
│   └── escalate_to_human.md         ← воркфлоу для сложных случаев
│
├── tools/
│   ├── fetch_lead_from_crm.py       ← получить данные лида из CRM
│   ├── enrich_company_data.py       ← дополнить данные о компании
│   ├── score_lead.py                ← оценить лида (scoring)
│   ├── send_notification.py         ← уведомить менеджера
│   └── update_crm_status.py         ← обновить статус в CRM
│
├── config/
│   ├── scoring_rules.json           ← правила скоринга (отрасль, размер, бюджет)
│   └── notification_templates.json  ← шаблоны уведомлений
│
├── docs/
│   └── crm-api-reference.md         ← документация API CRM
│
└── logs/
    └── (создаётся автоматически)

Обрати внимание: каждый инструмент делает ровно одну вещь. Воркфлоу описывает порядок вызовов. Агент координирует.

Практика

Задание: Нарисовать WAT-схему для автоматизации которую хочешь построить.

Шаг 1 — Выбор задачи (5 мин):

Выбери одну из:

Автоматическая рассылка новостей клиентам
Автоматическая публикация постов в соцсети
Автоматический отчёт по продажам
Автоматическая квалификация входящих лидов
Своя задача

Шаг 2 — WAT-схема (15 мин):

На бумаге или в любом редакторе нарисуй три блока:

Код

[ВОРКФЛОУ]
1. Шаг первый
2. Шаг второй
3. ⚠️ Проверка человека
4. Шаг четвёртый

[ИНСТРУМЕНТЫ]
- Название → что делает → какое API/сервис
- Название → что делает → какое API/сервис

[АГЕНТ]
- Что агент решает самостоятельно
- Где агент останавливается для проверки

Шаг 3 — Создание структуры (10 мин):

Создай папку проекта с пустой WAT-структурой через Claude Code:

Напиши в чат

Создай стандартную WAT-структуру проекта для [твоя задача].
Создай пустые файлы с правильными именами. 
В каждом файле напиши комментарий что в нём должно быть.
Создай CLAUDE.md с описанием проекта.

Частые ошибки

❌ Ошибка: Писать всю логику в одном файле main.py (God Object паттерн).

✅ Правильно: Один инструмент = один файл. Воркфлоу координирует вызовы. Это позволяет менять и тестировать инструменты по отдельности, не ломая всю систему.

❌ Ошибка: Писать воркфлоу на Python/JavaScript (ДжаваСкрипт — язык программирования) вместо markdown.

✅ Правильно: Воркфлоу пишется на естественном языке (markdown). Это главное преимущество: его может читать и редактировать любой человек, не только разработчик. Агент сам переводит инструкцию в действия.

❌ Ошибка: Не добавлять точку проверки человеком (Human-in-the-loop) в воркфлоу.

✅ Правильно: Всегда ставь пометку ЧЕЛОВЕЧЕСКАЯ ПРОВЕРКА перед необратимыми действиями (отправка email, публикация, изменение CRM). Особенно на первых запусках, пока система не проверена.

Инструменты и ресурсы

Claude Code — для создания структуры проекта
draw.io — бесплатный онлайн-инструмент для визуализации схем
Excalidraw — простой инструмент для рисования архитектурных схем
trigger.dev — платформа для продакшн-запуска воркфлоу
n8n — альтернатива для визуального построения: можно развернуть на своём сервере (Community Edition бесплатно) или взять облачный тариф. Актуальные цены: Актуальное сейчас
Claude Code GitHub — примеры проектов и issues

→ См. урок CLAUDE.md — системный промпт который описывает WAT-проект

→ См. урок Four C's Framework — Context, Connections, Capabilities, Cadence

→ См. урок Первый воркфлоу LIVE — от идеи до рабочей автоматизации

Ключевые выводы

WAT = три неразделимые части. Убери любую — система не работает.

Воркфлоу пишется на естественном языке (markdown), не на коде. Любой человек может его прочитать и изменить.

Каждый инструмент делает одну вещь. Агент координирует — инструменты выполняют.

Стандартная структура папок ускоряет работу: агент знает где что искать без объяснений.

Следующий урок

→ Первый воркфлоу LIVE — Newsletter Automation от идеи до запуска