Разбор 05

Агент строит исполняемые детерминированные workflow

Агент находит существующий workflow и переиспользует его — не генерирует реализацию заново. Тот же n8n_workflow_id, тот же граф обработки, тот же результат при каждом прогоне. IDE → MCP → n8n REST API; dual-file pattern: workflow.json и meta.md — в одном коммите.

CTO Head of AI Architect Tech Lead

Проблема

Чат-агент интерпретирует задачу каждый раз заново: один запрос — разная реализация, разное поведение, нет аудита. Для разовой задачи терпимо. Для автоматизации в проде нужен другой класс решения: исполняемый граф, который работает одинаково независимо от того, кто его запустил и когда.

Методика

Пять шагов, которые превращают «агент что-то сделал» в детерминированный workflow, готовый к повторному запуску.

1. Архитектура: IDE → MCP-сервер → n8n REST API. Никакой UI-автоматизации; только контракт через MCP и REST.
2. Loop агента: искать существующий workflow в workflows/ → если нет, спроектировать граф → экспорт JSON + метаданные → импорт в n8n через API → тестовый прогон → активация по валидации → для повторяющихся задач переиспользовать проверенный workflow (не регенерировать).

3. Dual-file pattern: <name>.workflow.json (экспорт n8n) + <name>.meta.md (YAML-frontmatter с guidance для агента и n8n_workflow_id, чтобы последующие прогоны шли в тот же workflow, не создавали новый).

<!-- daily-sales-sync.meta.md -->
---
schema_version: 1
slug: daily-sales-sync
name: Daily Sales Sync
summary: Синхронизирует заказы из Bitrix в ERP каждое утро
status: active
tags: [sales, sync, erp]
triggers: [cron]
version: 3
updated: 2026-05-01
n8n_workflow_id: 47
owner: data-platform
mcp_agent: >
  Не пересоздавать workflow — он привязан к n8n_workflow_id: 47.
  При изменении схемы источника править только nodes[2].parameters,
  не трогать credentials и triggers.
---

n8n_workflow_id: 47 — то, что превращает «агент сделал workflow» в «агент обновил тот же workflow»: воспроизводимость держится на этом поле.

4. Изоляция инфраструктуры: Docker Compose поднимает выделенный n8n на нестандартных портах — без конфликта с другими локальными инсталляциями.
5. Граница автономии: агент знает только имена credentials в n8n, не их значения. Он ссылается на credentialId в графе — но прочитать токен или пароль не может. Доступ к проду — только через явно настроенную политику.

Артефакт

github.com/dobryakov/ai-n8n-workflow-builder (Python). Воспроизводимо: run-n8n-mcp.sh читает env и поднимает MCP через npx.

Подпись серии

Где ломается

Дрейф между git и n8n UI. Кто-то поправил workflow руками в интерфейсе — workflow.json в git устарел. Агент работает по stale meta.md и уверен, что всё верно. Единственная защита — дисциплина: UI только для просмотра, все изменения через агента.
Стареющий meta.md. Guidance в meta.md — это инструкция агенту. Если она не обновилась после изменения схемы источника, агент сделает «правильно по инструкции», но неправильно по факту. Качество автоматизации прямо зависит от качества метаданных.
Паттерн гарантирует тот же граф, но не тот же результат. Если workflow пишет во внешнюю систему — запустить его дважды не то же самое, что один раз. Детерминизм исполнения и идемпотентность side effects — разные свойства, их нужно проектировать отдельно.

Для кого и почему

Если вы строите автоматизации с AI и хотите, чтобы они работали одинаково в следующий раз — здесь про архитектурный принцип: детерминированный исполняемый граф вместо интерпретации задачи на лету.

Хотите автоматизации, которые работают одинаково каждый раз?

Постановка детерминированной агентной автоматизации: исполняемый граф в git, dual-file pattern, MCP-контракт и граница автономии — под вашу задачу.

Написать на почту

Другие разборы

Серия инженерных разборов: реальная задача → методика → работающий артефакт → честный разбор, где он ломается.

К серии →