temporality
Изменить страницу↗
Инженерные документы

Команды агентов

#1. Цель

Ввести команду агентов как first-class сущность Temporality: переиспользуемое, версионированное определение состава и порядка совместной работы нескольких агентов над задачей.

Механика совместной работы в ядре уже есть — инструменты delegate и plan с DAG, acceptance gates и rework-циклами (docs/agent-delegation.md). Команда не заменяет её, а накрывает переиспользуемым определением:

Ключевое требование к UX: пользователь описывает команду естественным языком и редактирует обычной формой. Внутренний манифест team.yaml — артефакт системы, а не пользовательский интерфейс (тот же принцип, что у skill.yaml и определений агентов).

#2. Проблематика текущего состояния

#3. Основные понятия

#3.1 Team (команда)

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

Команда — это определение, а не постоянно работающий процесс. Экземпляр команды существует только внутри запуска и распускается по его завершении.

#3.2 Role Slot (ролевой слот)

Роль в команде. Слот описывает:

Слот переживает смену агентов: пока агент удовлетворяет требованиям слота, команда работает. Это позволяет заменить QA-агента на другого, не трогая определение команды.

#3.3 Protocol (протокол)

Типовая топология совместной работы. Небольшой словарь:

Протоколы компилируются в существующие механизмы plan/delegate, а не исполняются отдельным движком.

#3.4 Team Run (командный запуск)

Экземпляр работы команды: снапшот определения версии, привязанные слоты, цель. Порождает обычные дочерние AgentRun-ы; события дополнительно помечаются team_id и версией.

#3.5 Roster (ростер)

Множество агентов, доступных для привязки с учётом эффективной видимости вызывающего (docs/org-structure.md). Определения агентов у нас уже роле-ориентированы — ростер это они и есть; отдельной сущности «роль» не требуется.

#4. Принципы

#Определение постоянно, экземпляр эфемерен

Команда-определение версионирована и переиспользуется. Команда-экземпляр живёт только внутри запуска. Нет «постоянно работающего отдела» с фоновым общением.

#Слот — это ответственность и контракт, а не промпт

Слот задаёт, за что роль отвечает и что обязана вернуть. Как в docs/evaluable-agent.md — роль определяет ответственность, а не стиль.

#Малый словарь топологий

Произвольные графы общения запрещены осознанно: свободный N-агентный чат доказанно дорог, дрейфует и не отлаживается (анти-паттерн ранних AutoGen GroupChat). Расширение словаря протоколов — продуктовое решение, а не рантайм-свобода агентов.

#Контекст передаётся явно

Дочерние раны не делят память неявно. Всё, что нужно слоту, передаётся ему: цель, контракты предыдущих слотов, командный scratch. Соответствует принципу «делегированный запуск — настоящий run» из docs/agent-delegation.md.

#Детерминированный скелет, агентные решения в точках

Порядок, зависимости и ворота задаёт протокол. Агентские решения допускаются только в определённых точках: декомпозиция (в lead_workers), выполнение задачи, вердикт ревью.

#Права не складываются

Команда не расширяет права участников. Каждый дочерний ран работает с правами и политиками своего агента; командное взаимодействие не является способом эскалации (наследует принцип «ребёнок работает только со своими правами»).

#Команда наблюдаема как целое

Дерево вызовов, DAG, события, знания, споры — всё видно в существующих панелях, плюс rollup-метрики уровня команды.

#5. Модель определения

Внутренний манифест (пользователь его не видит):

id: squad-code-delivery
version: 3
name: Code Delivery
description: Доставка изменения кода: реализация, ревью, проверка качества.
org_unit_id: null            # null = вся инсталляция, иначе узел + поддерево

protocol:
  kind: pipeline             # pipeline | lead_workers | fan_out | review_gate | dag
  max_rework: 2              # лимит доработок на ворота (DefaultMaxRework ядра)

slots:
  - id: coder
    title: Coder
    responsibility: Реализует изменение и проверяет его выполнимым кодом.
    requirements:
      capabilities: [read_files, modify_files, run_commands]
    contract:
      output: список изменённых файлов и доказательства проверки
    binding:
      mode: role             # role | fixed
      preferred_agent_id: coder    # подсказка подбору, не обязательство

  - id: reviewer
    title: Reviewer
    responsibility: Находит дефекты и оценивает достаточность доказательств.
    requirements:
      capabilities: [read_files, run_commands]
    contract:
      output: verdict accept | rework + список замечаний
    binding:
      mode: fixed
      agent_id: reviewer

defaults:
  max_turns: 40
  budget_usd: 5.0
  parallel_limit: 4          # одновременных дочерних ранов

#Версионирование

Каждое изменение определения создаёт новую версию (как у skills и агентов). Версия хранит: описание, слоты, протокол, дефолты, автора, дату. Запуск фиксирует снапшот версии — изменение определения во время запуска не влияет на него.

#6. Протоколы

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

Протокол Компиляция Что обобщает
pipeline последовательные дочерние раны; контракт слота N — вход слота N+1 пример LeadCoderReviewerQA
lead_workers один ран ведущего агента с правом delegate/plan; слоты = ростер для его декомпозиции обычное делегирование, но с фиксированным составом кандидатов
fan_out plan с независимыми задачами (depends_on: []) + сводящая задача, зависящая от всех параллельные исследования → синтез
review_gate plan c review_of и max_rework текущие acceptance gates
dag явный список шагов с depends_on/review_of; слоты подставляются как исполнители шагов прямой аналог tool-спеки plan, но в терминах слотов

Правила, общие для всех протоколов:

#Ограничения протоколов

#7. Привязка слотов

Привязка выполняется при запуске (launch-time binding):

  1. слот fixed → указанный агент; если агент невидим в скоупе запуска (ростер вызывающего + проектный скоуп) — команда не стартует с осмысленной ошибкой;
  2. слот role → подбор из ростера по требованиям: capabilities (семантика карточек ростера: незаданная capability = разрешена, явный false отсекает; delegation — только явная выдача) и skills; preferred_agent_id используется как тай-брейк при нескольких кандидатах, а не как обязательство; однозначный кандидат привязывается автоматически;
  3. несколько равных кандидатов без preferred → запуск отклоняется (409) со списком кандидатов для явного выбора; ноль кандидатов → отклонение (422) с перечнем требований;
  4. пользователь при запуске может зафиксировать привязки в bindings (они обязаны попадать в ростер) или предварительно посмотреть разрешение через GET /v1/agent/teams/{id}/resolve;
  5. ни одного кандидата → честная ошибка до старта, без частичного запуска (effect=none).

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

#8. Создание команды (Formation)

Wizard по образцу Skill Builder:

  1. Пользователь описывает задачу команды естественным языком:

    «Нужна команда, которая реализует фичи: один кодер пишет, ревьюер проверяет, QA прогоняет тесты».

  2. Team Builder Agent:

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

  3. Происхождение значений визуально различается (как у skills): из инструкции / предложено агентом / из доступных агентов / подтверждено / требует уточнения.

  4. Уточняющие вопросы задаются прямо в wizard:

    «Ревьюер может отклонять работу кодера. Сколько кругов доработки допускаем?»

  5. Результат открывается в обычной форме редактирования (CRUD): название, описание, протокол, слоты, дефолты. Пользователь правит то, что агент понял неточно.

Обязательный опрос не проводится: если значение разумно выводится — оно выводится и помечается.

#Режим «Переформировать»

При существенном изменении описания пользователь может переформировать определение. Перед заменой показывается diff и затронутые ручные правки; ничего не теряется молча (как у агентов, docs/evaluable-agent.md §13).

#Шаблоны команд

Продукт поставляется с шаблонами («Code Delivery», «Research Fan-out», «Delivery + QA gate»), а не с предсозданными командами — по уроку встроенных агентов: шаблон хороший, создавать сущность под себя — пользователь.

#9. Командный запуск

POST /v1/agent/teams/{team_id}/runs
{ project, goal, bindings?: { slot_id: agent_id }, version?: 3 }

Порядок в ядре:

  1. загрузить определение (указанную или последнюю версию);
  2. снапшотировать его в контекст запуска;
  3. разрешить привязки слотов (§7) — все до старта;
  4. скомпилировать протокол в последовательность plan/delegate вызовов;
  5. исполнять как обычные дочерние AgentRun-ы с существующими гарантиями (каузальность, отмена вниз по дереву, бюджеты).

#События

Существующие delegation.* и plan.* сохраняются без изменений. Добавляются:

Таким образом существующие панели (DelegationTree, PlanGraph, трейс) работают для командных запусков без переделки.

#10. Командный контекст

#Team scratch

Общее персистентное хранилище в рамках командного запуска (префикс в существующем workspace storage):

#Артефакты контрактов

Контракт выхода слота записывается в team scratch (файлом), а зависимые слоты получают и текст в промпте, и ссылку на артефакт. Длинные результаты (логи, диффы, отчёты) не раздувают промпты.

#Scoped hints

Знания, сформированные внутри командного запуска (knowledge.proposed → confirmed), доступны подсказками всем слотам этого запуска — команда учится в рамках задачи. Глобальные знания — как обычно, через эффективную видимость.

#11. Наблюдаемость

#12. Эволюция команды

На вкладке «Эволюция» карточки команды — сопоставление версий определения с результатами:

v3  ● текущая
      ↑ 214 запусков
      ↑ accept-first-try 71% (+9 к v2)
      ↑ средние rework-циклы 0.6 (−0.4)
      ↑ 1 предложение изменения

      ──────────────────────────────────────────
      Изменение v2 → v3: добавлен слот QA, max_rework 3 → 2
      Причина: 12% запусков v2 упирались в лимит доработок
      [Посмотреть доказательства]

Метрики по версии определения:

Evolution proposals — по модели docs/living-skills.md: система обнаруживает устойчивые паттерны из evidence запусков (например, «ревьюер отклоняет 70% работ слота coder → предложить добавить шаг self-check или сменить пару») и предлагает изменение определения; человек смотрит доказательства и принимает или отклоняет. Проваливание в первоисточник сохраняется: proposal → evidence → executions → trajectories → knowledge → версия определения.

#13. Видимость и доступ

#14. Безопасность

#15. API

Списки фильтруются по эффективной видимости; для admin-токенов ядра — без фильтра (как у остальных ресурсов).

#16. UI

#17. Связь с существующими механизмами

Механизм Отношение
plan / delegate двигатели; команда компилируется в них, отдельный оркестратор не вводится
Acceptance gates ворота протоколов review_gate/dag — это они
DelegationTree / PlanGraph работают для командных запусков без переделки
RunDisputes споры агрегируются в метрики команды
Cost accounting rollup поверх существующего per-run учёта
Knowledge / hints scoped hints внутри командного запуска (§10)
Org structure модель видимости переиспользуется целиком
Approval model применяется к каждому слоту без изменений
Пример LeadCoderReviewerQA мигрирует в шаблон команды pipeline; код примера удаляется

#18. Анти-паттерны (зафиксировано осознанно)

#19. Фазы реализации

#20. Критерии готовности (MVP, фазы 1–4)

#21. Открытые вопросы