Практическая архитектура 12 минут чтения Уровень: продвинутый

Граф агентов для выполнения задач разработки

Граф агентов для выполнения задач разработки
Temporary fallback cover; replace in editorial pass.

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

Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

Зачем превращать выполнение задачи в граф

Одиночная сессия агента удобна для прототипа, но плохо подходит для длительной разработки. Контекст может быть усечён, агент может завершиться с ошибкой, а итоговое сообщение не всегда показывает, какие проверки действительно выполнялись.

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

Цель такой схемы — не заставить агентов работать строго последовательно. Цель — сделать каждое важное решение наблюдаемым и проверяемым:

  • требования зафиксированы отдельно от кода;
  • план и изменения имеют собственные доказательства;
  • проверки запускаются в отдельном этапе;
  • ревьюер не является тем же агентом, который писал результат;
  • переход дальше возможен только при выполнении формального условия.

Минимальная архитектура

Для большинства задач достаточно шести узлов. Это не универсальный стандарт, а практический шаблон, который можно адаптировать под репозиторий.

intake
  │
  ▼
spec ──► plan ──► implement ──► verify ──► review
  │                                      │
  └────────────── retry / blocked ◄──────┘
Пример графа. Стрелка означает разрешённый переход, а не обязательную передачу всей истории чата.

1. Intake

Агент приёма нормализует запрос: фиксирует цель, ограничения, критерии готовности и предполагаемые области репозитория. Он не должен сразу менять код.

2. Spec

Агент спецификации превращает исходный запрос в проверяемые требования. Хорошая спецификация отвечает на вопрос: «Как понять, что задача выполнена?» Если ответ нельзя выразить через файл, команду, состояние или наблюдаемое поведение, требование пока слишком расплывчато.

3. Plan

Агент планирования сопоставляет требования с файлами и шагами изменения. План должен содержать границы: что не входит в задачу, какие риски известны и какие проверки обязательны.

4. Implement

Агент реализации работает только после принятого плана. Его результат — не сообщение «готово», а набор изменений и журнал действий.

5. Verify

Агент проверки запускает разрешённые команды и сохраняет их вывод. Он не должен подменять отсутствующую проверку предположением о корректности.

6. Review

Независимый ревьюер читает требования, план, diff и доказательства проверки. Он оценивает не красоту отчёта, а соответствие результата условиям перехода.

Файлы-доказательства как контракт между агентами

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

Один из возможных layouts рабочего состояния:

.agent/
├── state.json
├── intake.md
├── spec.md
├── plan.md
├── implementation.md
├── verification.md
├── review.md
└── attempts/
    ├── 001/
    └── 002/

Это пример структуры, а не требование конкретного инструмента. Важно другое: каждый файл должен иметь владельца этапа и понятный формат.

Что записывать в доказательство

  • Идентификатор задачи и номер попытки.
  • Входы: commit, список файлов, версия окружения или ссылка на предыдущий артефакт.
  • Действия: какие команды и операции были выполнены.
  • Результат: коды возврата, изменённые файлы и важные фрагменты вывода.
  • Ограничения: что не проверялось и почему.
  • Решение: pass, retry или blocked.

Файл доказательства не обязан содержать полный лог. Для воспроизводимости достаточно сохранить точную команду, код завершения, краткий итог и путь к полному логу, если он существует.

Проверяемые переходы между этапами

Оркестратор не должен переходить к следующему узлу только потому, что предыдущий агент завершил ответ. Переход проверяется по предикату — явному условию, которое можно вычислить из файлов и состояния.

{
  "task_id": "example-001",
  "stage": "verify",
  "attempt": 1,
  "artifacts": {
    "spec": ".agent/spec.md",
    "plan": ".agent/plan.md",
    "verification": ".agent/verification.md"
  },
  "transitions": {
    "verify_to_review": {
      "requires": [
        "verification.exists",
        "verification.exit_code == 0",
        "verification.scope_complete == true"
      ]
    }
  }
}

Формат JSON выше — иллюстративный. В рабочей системе проверка должна быть строгой: отсутствие поля, неоднозначное значение или устаревший commit должны блокировать переход.

Пример правил

  • intake → spec: заполнены цель, ограничения и критерии готовности.
  • spec → plan: каждое требование имеет способ проверки.
  • plan → implement: указаны файлы или области изменений и риски.
  • implement → verify: diff существует, а журнал реализации указывает изменённые пути.
  • verify → review: обязательные проверки завершились успешно либо явно получили статус «не выполнено» с причиной.
  • review → done: ревьюер подтвердил критерии и не оставил блокирующих замечаний.

Воспроизводимый рабочий процесс

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

# 1. Проверить рабочий каталог
pwd
git status --short

# 2. Создать каталог доказательств в текущем проекте
mkdir -p .agent/attempts/001

# 3. Сохранить список отслеживаемых файлов
git ls-files > .agent/attempts/001/files-before.txt

# 4. После работы агента посмотреть изменения
git diff --stat
git diff --check

# 5. Зафиксировать состояние без публикации
git status --short

Команды git diff --check и git status --short не доказывают корректность бизнес-логики. Они лишь помогают обнаружить часть механических проблем. Набор проверок должен соответствовать проекту и быть объявлен в спецификации.

Возобновление после сбоя

При перезапуске оркестратор читает state.json, сверяет существование артефактов и определяет последний допустимый переход. Он не продолжает «с места в памяти» и не доверяет последнему сообщению агента без проверки файлов.

if state.stage == "implement":
    if exists(".agent/implementation.md") and diff_is_present():
        next_stage = "verify"
    else:
        next_stage = "implement"
elif state.stage == "verify":
    if verification_is_current():
        next_stage = "review"
    else:
        next_stage = "verify"

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

Почему ревьюер должен быть независимым

Агент, который написал код, естественным образом склонен интерпретировать неоднозначности в свою пользу. Независимый ревьюер получает ограниченный, но достаточный набор материалов:

  1. исходную спецификацию;
  2. план;
  3. diff или список изменений;
  4. отчёт проверки;
  5. правила приёма.

Ревьюеру не обязательно знать всю историю диалога. Более того, отсутствие доступа к ней повышает качество проверки: решение опирается на опубликованные артефакты, а не на устные обещания.

Формат результата ревью

# Review

status: pass | retry | blocked

## Findings
- severity: blocker | major | minor
- location: path:line
- evidence: какой артефакт подтверждает замечание
- action: что нужно изменить

## Coverage
- requirement-1: pass
- requirement-2: pass

## Decision
Краткое объяснение решения.

Статус retry означает, что этап можно выполнить повторно после исправления. Статус blocked означает отсутствие необходимого входа или разрешения; он не должен маскироваться под успешное выполнение.

Типовые ошибки

«Успех» определяется текстом ответа

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

Один общий журнал на весь граф

Общий лог быстро превращается в неструктурированную стену текста. Исправление: отдельный артефакт на этап плюс общий индекс состояния.

Ревьюер повторяет работу автора

Если ревьюер получает только фразу «проверено», независимость теряется. Исправление: выдавать ему требования, diff и первичные результаты проверок.

Повторная попытка перезаписывает первую

Так исчезает информация о причине сбоя. Исправление: хранить попытки отдельно и ссылаться на предыдущий артефакт.

Слишком широкие полномочия агента

Агенту реализации не нужны права менять конфигурацию CI или публиковать изменения, если это не часть задачи. Ограничивайте команды, рабочий каталог и доступные секреты.

Устаревшие доказательства

Успешная проверка до последнего изменения не подтверждает текущий код. Исправление: сохранять идентификатор commit или хеш входных файлов и сравнивать его перед переходом.

Ограничения подхода

Граф повышает проверяемость, но не устраняет неопределённость. Он не может доказать корректность требований, если сами требования неверны. Он также не заменяет человеческое решение в областях, где требуется продуктовый, юридический или риск-анализ.

Цена надёжности — дополнительная работа: проектирование форматов артефактов, хранение логов, обработка повторных запусков и поддержка правил перехода. Для маленькой одноразовой правки такая схема может быть избыточной. Практический критерий прост: чем дороже ошибка, длиннее выполнение и выше вероятность прерывания, тем полезнее отдельные этапы и доказательства.

Проверка результата перед завершением

Перед переводом задачи в конечное состояние оркестратор и ревьюер должны независимо проверить:

  • все обязательные артефакты существуют;
  • артефакты относятся к текущей попытке и текущему состоянию репозитория;
  • каждое требование сопоставлено с проверкой;
  • команды проверки записаны вместе с результатом;
  • не осталось блокирующих замечаний;
  • ограничения и пропущенные проверки явно указаны;
  • после сбоя можно определить безопасную точку возобновления.

Если хотя бы один пункт не подтверждён, корректный итог — не «готово», а повторная попытка или блокировка с объяснением.

Итог

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

Начните с малого: intake, spec, implement, verify и review. Добавляйте параллельные ветви только тогда, когда их результаты можно объединить формальным правилом. Такая архитектура делает выполнение возобновляемым, снижает зависимость от памяти одной сессии и позволяет восстановить ход работы по артефактам.

Дополнительные практические материалы собраны в разделе гайдов, а определения терминов — в глоссарии.