Профили субагентов (Model Routing)

0. Прежде чем начать

Что такое профили субагентов?

Когда агент решает большую задачу, он может передавать часть работы субагентам — встроенным (например, Code, Ask, Test, Review, Plan, Debug или General) и пользовательским. По умолчанию субагент работает на той же модели, что и основной (родительский) агент.

Профили субагентов (функция Model Routing) позволяют заранее описать набор именованных профилей — например, fast, balanced, strong — и привязать к каждому из них конкретную модель и параметры рассуждения. Главный агент затем выбирает подходящий профиль для каждой подзадачи по его текстовому описанию.

Профиль состоит из:

• псевдонима (alias) — короткого имени, которым главный агент ссылается на профиль;
• описания (description) — инструкции на естественном языке, когда использовать профиль;
• (необязательно) конкретной модели провайдера, на которую профиль закрепляется;
• (необязательно) уровня рассуждения (reasoning) для этой модели.

Если модель у профиля не задана, он наследует модель родительского агента.

Профиль можно передать любому обычному субагенту, включая пользовательский. Model Routing не поддерживается для MCP-backed субагентов.

Зачем это нужно

Профили решают типичную проблему: на разных подзадачах оправданы разные модели.

• Дешёвая и быстрая модель — для простого поиска по коду, чтения файлов, кратких ответов.
• Сбалансированная модель — для рутинного анализа и генерации тестов.
• Самая мощная (и дорогая) модель — для сложной архитектуры, нетривиальных правок, глубокого ревью и трудного дебага.

Описание профиля задаёт правило выбора для главного агента. Закреплённые модель и reasoning определяют параметры запроса, когда агент выбрал этот профиль.

Встроенные профили

В системе присутствуют три профиля по умолчанию (fast, balanced, strong). Их нельзя удалить, но можно отредактировать (задать модель, изменить описание).

Профиль	Назначение по умолчанию
fast	Лёгкий поиск только на чтение, чтение файлов, суммаризация, простое изучение кодовой базы.
balanced	Обычный анализ, Q&A средней сложности, рутинная генерация тестов, типовая поддержка реализации.
strong	Сложный анализ архитектуры, нетривиальные правки кода, трудный дебаг и глубокое ревью.

По умолчанию у встроенных профилей модель не закреплена — они наследуют модель родительского агента (Inherit parent); чтобы профили начали маршрутизировать запросы на разные модели, закрепите за ними конкретные модели.

Помимо встроенных, вы можете создавать собственные профили с произвольными псевдонимами (например, second-reviewer, planner).

1. Настройка профилей в Settings

Профили настраиваются в Settings → Tools → Veai → Model Routing.

Область применения (Scope)

В верхней части окна выбирается область, к которой относятся профили:

• Global используйте для личных профилей, которые должны быть доступны во всех проектах на этой машине. Выберите Global, настройте профили и нажмите Apply.
• Project используйте для правил маршрутизации конкретного репозитория — например, когда команде нужны одинаковые названия профилей и закреплённые модели. Выберите Project, настройте полный набор нужных профилей, нажмите Apply и при необходимости добавьте .veai/model-routing.yaml в VCS.

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

Таблица профилей

В разделе Profiles отображается таблица из трёх колонок:

• Alias — псевдоним профиля;
• Description — описание (когда использовать профиль);
• Model — закреплённая модель и уровень reasoning, либо Inherit parent, если модель не задана.

Диалог создания и редактирования профиля

Добавить профиль — Add profile; отредактировать — Edit profile (или двойным кликом по строке); удалить — Remove profile.

В диалоге доступны поля: Alias, Description, Mode, Model и Reasoning.

2. Поля профиля

Alias

Короткое имя профиля, которым на него ссылается главный агент.

• Должен соответствовать шаблону [a-z][a-z0-9-]* — строчные латинские буквы, цифры и дефис, начинается с буквы (например, fast, gpt-5, reviewer).
• Должен быть уникальным в пределах области.
• У встроенных профилей псевдоним менять нельзя.

Description

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

• Не может быть пустым.
• Пишите его как короткую инструкцию по сценарию использования, например: «Use for lightweight read-only lookup and file reading».

Совет: если временно нужно «отговорить» агента от использования встроенного профиля, который нельзя удалить, задайте ему описание вроде «never use it».

Mode: Inherit parent и Model

Поле Mode задаёт, как профиль выбирает модель:

• Inherit parent используйте, когда профиль должен описывать тип подзадачи, но менять модель родительского агента не требуется. Выберите Inherit parent, заполните Description и сохраните профиль; поля Model и Reasoning останутся неактивными.
• Model используйте, когда подзадачу нужно направлять на заранее выбранную модель — например, чтобы независимо проверить результат другой моделью. Выберите Model, затем модель и доступный уровень Reasoning, после чего сохраните профиль.

Reasoning

Поле Reasoning задаёт запрашиваемый уровень рассуждения для закреплённой модели. Оно доступно только в режиме Model. Поддержка уровней и их фактическое поведение зависят от модели и провайдера.

• Default — используйте, когда хотите оставить выбор уровня модели или провайдеру. Выберите Default и сохраните профиль.
• None — используйте для простой подзадачи, где отдельный reasoning не требуется, например для буквального поиска или извлечения данных. Выберите None и сохраните профиль.
• Low — используйте для короткого анализа с небольшим числом шагов, например для первичной классификации файлов. Выберите Low и сохраните профиль.
• Medium — используйте для обычной подзадачи, где нужно сопоставить несколько фактов или вариантов реализации. Выберите Medium и сохраните профиль.
• High — используйте для сложной подзадачи с несколькими зависимостями или гипотезами, например для анализа архитектурного изменения. Выберите High и сохраните профиль.
• XHigh — используйте для редкой особенно сложной подзадачи, если выбранная модель поддерживает этот уровень. Выберите XHigh и сохраните профиль.

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

3. Файл model-routing.yaml

Профили хранятся в YAML-файле model-routing.yaml:

• проектный — в .veai/model-routing.yaml в корне проекта;
• глобальный — в ~/.veai/model-routing.yaml.

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

Текущий контракт файла

У формата нет отдельного поля версии. Ниже приведён контракт, который использует текущий парсер Veai. Значения provider и model в примере условные: для рабочей конфигурации используйте идентификаторы из файла, сохранённого через Settings.

profiles:
  fast:
    description: "Use for lightweight read-only lookup and file reading."
  balanced:
    description: "Use for regular analysis and common implementation support."
    provider: "OpenAI"
    model: "gpt-5"
    reasoning: "medium"
  strong:
    description: "Use for complex architecture and deep review."
    provider: "Anthropic"
    model: "claude-sonnet-4"
    reasoning: "high"
  second-reviewer:
    description: "Use for an independent second review."

Ключ	Тип	Обязательность и ограничения
profiles	объект: alias → profile	В файле, которым управляет Veai, должны присутствовать fast, balanced и strong
description	строка	Обязательна и не должна быть пустой после удаления пробелов по краям
provider	строка	Необязательна; задаётся только вместе с model, пробелы внутри значения запрещены
model	строка	Необязательна; задаётся только вместе с provider, пробелы внутри значения запрещены
reasoning	строка	Допустима только вместе с provider и model; значения: default, none, low, medium, high, xhigh без учёта регистра

Alias должен соответствовать [a-z][a-z0-9-]*. Неизвестные ключи считаются ошибкой структуры. Если provider и model отсутствуют, профиль наследует модель родительского агента. Значения идентификаторов модели и провайдера берите из файла, сохранённого через Settings: отображаемое название в интерфейсе не всегда совпадает со значением в YAML.

Типичные ошибки

Ошибка в файле	Что сообщит валидатор
description: ""	описание профиля не должно быть пустым
alias Second Reviewer	alias не соответствует [a-z][a-z0-9-]*
задан model, но нет provider	provider обязателен, когда задан model
задан provider, но нет model	model обязателен, когда задан provider
reasoning: extreme	допустимы только перечисленные уровни reasoning
reasoning без модели	reasoning допустим только вместе с provider и model
отсутствует fast, balanced или strong	конфигурация должна определять отсутствующий встроенный профиль
повторяется YAML-ключ	синтаксическая ошибка дублирующегося ключа

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

4. Рекомендации

• Начните с того, что закрепите модели за встроенными fast/balanced/strong — этого уже достаточно, чтобы главный агент разводил подзадачи по разным моделям.
• Пишите описания как чёткие правила выбора: главный агент полагается именно на них. Чем конкретнее сценарий («только чтение», «генерация тестов», «глубокое ревью»), тем точнее маршрутизация.
• Используйте Project-область и коммитьте model-routing.yaml в репозиторий, чтобы команда работала с одинаковыми правилами маршрутизации.
• Если у моделей различаются ограничения или тарификация, учитывайте это при назначении профилей и проверяйте фактический расход в своей конфигурации провайдера.
• Если профиль временно не нужен, но удалить его нельзя (встроенный) — переведите его в режим Inherit parent или опишите как нежелательный для вызова.

Примеры использования

Межмодельный консилиум: одна задача — три модели параллельно

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

Подготовка:

1. Создайте три профиля, например gpt, opus и glm, и закрепите за каждым разные модели провайдеров. Названия условны, выбирайте любые.
2. Описания сделайте достаточно общими, чтобы главный агент мог направить на каждый профиль одну и ту же подзадачу.

Режим работы. Запускайте главный агент в режиме Orchestrator: он сам не правит файлы, а раздаёт подзадачи субагентам, что хорошо подходит для координации трёх моделей. Подойдёт и General, если задача может разрастись и вы хотите, чтобы главный агент тоже выполнил часть работы сам. Субагентов запускайте в режиме Code (если нужны правки) или Ask (исследование и брейншторм, read-only).

Затем дайте главному агенту инструкцию примерно такого вида:

Реши эту задачу параллельно тремя субагентами — профилями gpt, opus и glm.
Каждый должен независимо предложить решение. Затем сверь их ответы,
найди расхождения и сформулируй итоговое решение с учётом всех точек зрения.

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

Совет: пусть общий файл в .tasks/ работает как «доска обсуждения», где каждый агент отмечает, с чем согласен, а с чем спорит. Так вместо трёх независимых ответов получается одно обсуждение с общим итогом.

Готовый навык. Сохраните промпт как .veai/skills/multi-model-consilium/SKILL.md — тогда его можно запускать командой /multi-model-consilium или автоматически, когда агент сочтёт нужным. Профили поправьте под себя.

---
name: "multi-model-consilium"
schemaVersion: "v0.1"
description: "Решить задачу параллельно тремя моделями и сверить результаты (межмодельный консилиум)"
agent: "General"
used-by:
  - "Orchestrator"
  - "General"
---

1. Запусти задачу параллельно тремя субагентами в режиме Code с профилями `gpt`, `opus` и `glm` (см. Model Routing). Для исследования без правок используй режим Ask.
2. Каждый субагент независимо предлагает решение и записывает его в свой раздел общего файла `.tasks/consilium/<задача>.md`.
3. Когда все три закончат, прочитай файл, сверь ответы и найди расхождения.
4. Сформулируй итоговое решение с учётом всех точек зрения и зафиксируй его в том же файле.

Межмодельное ревью

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

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

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

Запрос главному агенту:

Проведи ревью этих изменений параллельно профилями gpt, opus и glm.
Каждый должен независимо найти проблемы. Затем объедини замечания,
убери дубликаты и выдай единый список с приоритетами.

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

Готовый навык. Сохраните промпт как .veai/skills/multi-model-review/SKILL.md — тогда его можно запускать командой /multi-model-review или автоматически, когда агент сочтёт нужным. Профили поправьте под себя.

---
name: "multi-model-review"
schemaVersion: "v0.1"
description: "Проверить изменения параллельно тремя моделями и выдать единый список проблем"
agent: "Orchestrator"
used-by:
  - "Orchestrator"
  - "General"
---

1. Запусти ревью изменений параллельно тремя субагентами в режиме Review с профилями `gpt`, `opus` и `glm`.
2. Каждый субагент записывает найденные проблемы в свой раздел общего файла `.tasks/review/<ревью>.md`.
3. Когда все три закончат, объедини замечания: убери дубликаты и проставь приоритеты.
4. Выдай единый консолидированный список проблем.