Как собрать multi-agent систему: router, supervisor и handoff

Что получится в результате

Соберем multi-agent систему, в которой несколько специализированных агентов работают над одной задачей, но не превращают процесс в хаос. Будет router для выбора маршрута, supervisor для контроля шагов, specialist agents для отдельных ролей, общий state, handoff между агентами, policy gate перед tools, reviewer для проверки результата и мониторинг всего run.

В результате будет рабочий MVP:

1. роли агентов описаны в `agent_registry`;
2. инструменты агентов лежат в `agent_tool_registry`;
3. права на инструменты лежат в `tool_policy`;
4. сценарии workflow описаны в `workflow_registry`;
5. граф переходов лежит в `workflow_graph`;
6. общий state хранится в `shared_state`;
7. задачи агентов лежат в `agent_task_queue`;
8. handoff между агентами пишется в `handoff_log`;
9. сообщения агентов пишутся в `agent_messages`;
10. решения supervisor пишутся в `supervisor_decisions`;
11. решения router пишутся в `routing_decisions`;
12. конфликты между агентами пишутся в `conflict_log`;
13. правила разрешения конфликтов лежат в `conflict_resolution_rules`;
14. проверки результата пишутся в `review_log`;
15. tool calls пишутся в `tool_call_log`;
16. approval идет через `approval_queue`;
17. весь путь выполнения пишется в `run_trace`;
18. стоимость пишется в `cost_log`;
19. ошибки и зацикливания пишутся в `error_log`;
20. тесты multi-agent маршрутов лежат в `multi_agent_eval_cases`;
21. результаты тестов пишутся в `multi_agent_eval_runs`;
22. все важные решения фиксируются в `audit_log`.

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

Что понадобится

Минимальный набор:

1. один реальный процесс, который сложно надежно закрыть одним агентом;
2. список ролей агентов;
3. список tools и прав доступа;
4. общий формат state;
5. правила handoff;
6. supervisor или router;
7. ограничения по числу шагов;
8. approval для опасных действий;
9. база данных для state, логов и очередей;
10. 20-40 тестовых сценариев;
11. мониторинг run, latency и стоимости.

Для первого запуска достаточно четырех ролей: `router_agent`, `research_agent`, `action_agent`, `reviewer_agent`. Все write-действия должны быть `draft_only` или `approval_required`.

Шаг 1. Проверьте, что multi-agent правда нужен

Multi-agent система сложнее, дороже и медленнее одного агента. Не начинайте с нее без причины.

Multi-agent нужен, если:

1. задача имеет разные роли с разными tools;
2. нужен отдельный reviewer;
3. один агент часто путает режимы;
4. есть разные уровни доступа;
5. нужно разделить read-only анализ и write-действия;
6. нужен supervisor для сложного workflow;
7. есть несколько источников данных;
8. требуется handoff человеку;
9. нужен контроль конфликтов;
10. процесс состоит из нескольких независимых этапов.

Multi-agent не нужен, если:

1. задача решается одним prompt;
2. нет tools;
3. нет разных ролей;
4. нет write-действий;
5. нет сложного routing;
6. нет бюджета на мониторинг;
7. достаточно обычного workflow с несколькими шагами.

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

Шаг 2. Выберите один MVP-сценарий

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

Хорошие первые сценарии:

1. обработка заявки клиента;
2. анализ договора и подготовка списка рисков;
3. ресерч конкурентов и отчет;
4. обработка инцидента DevOps;
5. подготовка коммерческого предложения;
6. проверка входящего документа;
7. triage задачи в Jira;
8. обновление базы знаний;
9. анализ таблицы и отчет;
10. обработка обращения в поддержку.

Для этой инструкции берем сценарий: заявка клиента приходит в систему, router определяет тип, research agent ищет контекст в базе знаний и CRM, action agent готовит черновик действия, reviewer agent проверяет риск, supervisor завершает run или отправляет человеку.

Проверка: сценарий заканчивается `review_log.status = passed` или `handoff_queue.status = open`, а не бесконечным обменом сообщений.

Шаг 3. Создайте базу проекта

Создайте базу `multi_agent_mvp`.

Добавьте таблицы:

agent_registry
agent_tool_registry
tool_policy
workflow_registry
workflow_graph
shared_state
agent_task_queue
agent_messages
handoff_log
supervisor_decisions
routing_decisions
conflict_log
conflict_resolution_rules
review_log
tool_call_log
approval_queue
run_trace
cost_log
error_log
multi_agent_eval_cases
multi_agent_eval_runs
audit_log

Проверка: до первого запуска есть таблицы для ролей, state, handoff, trace и ошибок.

Шаг 4. Опишите агентов в `agent_registry`

Каждый агент должен иметь узкую роль.

Колонки:

id
agent_code
agent_name
role_description
model_role
max_steps
risk_level
can_call_tools
can_write
is_active

Стартовые агенты:

router_agent | Router | определяет маршрут и тип задачи | fast | 2 | low | no | no
research_agent | Researcher | ищет факты в базе знаний, CRM и документах | balanced | 5 | medium | yes | no
action_agent | Action drafter | готовит черновики действий и tool payloads | balanced | 5 | high | yes | draft_only
reviewer_agent | Reviewer | проверяет ответ, риски, citations и approvals | reasoning | 4 | high | yes | no
supervisor_agent | Supervisor | управляет workflow, остановками и handoff | reasoning | 10 | high | yes | no

Проверка: нет агента с ролью "делает все".

Шаг 5. Опишите tools в `agent_tool_registry`

Tools должны быть привязаны к ролям.

Колонки:

id
agent_code
tool_name
tool_type
side_effect
input_schema_json
output_schema_json
risk_level
is_active

Пример:

research_agent | search_kb | retrieval | read_only | {...} | {...} | low
research_agent | read_crm | api | read_only | {...} | {...} | medium
action_agent | create_ticket_draft | api | draft_only | {...} | {...} | medium
action_agent | send_email | api | send_message | {...} | {...} | high
reviewer_agent | policy_check | validator | read_only | {...} | {...} | medium

Проверка: `router_agent` не имеет write-tools, а `action_agent` не читает закрытые документы без правила.

Шаг 6. Настройте `tool_policy`

Нельзя давать агентам tools только через prompt.

Колонки:

id
agent_code
tool_name
allow_call
requires_approval
max_calls_per_run
allowed_roles_json
blocked_conditions_json
is_active

Правила:

1. read-only tools можно выполнять без approval;
2. draft-only tools можно выполнять после schema validation;
3. write-tools требуют approval;
4. delete-tools запрещены в MVP;
5. external-send tools требуют approval;
6. каждый tool имеет max calls per run;
7. tool нельзя вызвать агенту без роли.

Проверка: если модель просит `send_email`, backend создает approval, а не отправляет письмо.

Шаг 7. Создайте `workflow_registry`

Workflow описывает сценарий как управляемый процесс.

Колонки:

id
workflow_code
workflow_name
entry_agent
max_total_steps
max_total_cost
timeout_seconds
status

Пример:

support_request_mvp | Обработка заявки клиента | router_agent | 20 | 1.50 | 120 | active

Проверка: у workflow есть лимит шагов, стоимости и времени.

Шаг 8. Опишите `workflow_graph`

Граф задает допустимые переходы между агентами.

Колонки:

id
workflow_code
from_agent
to_agent
condition
max_transitions
is_terminal

Пример:

start | router_agent | always | 1 | no
router_agent | research_agent | intent=question OR intent=support | 1 | no
research_agent | action_agent | action_needed=true | 1 | no
research_agent | reviewer_agent | answer_ready=true | 1 | no
action_agent | reviewer_agent | draft_ready=true | 1 | no
reviewer_agent | supervisor_agent | review_done=true | 1 | no
supervisor_agent | end | completed=true | 1 | yes
supervisor_agent | human_handoff | needs_human=true | 1 | yes

Проверка: агент не может передать задачу кому угодно, только по разрешенному переходу.

Шаг 9. Создайте общий `shared_state`

Shared state должен быть структурированным, а не общей перепиской агентов.

Колонки:

id
run_id
state_key
state_value_json
owner_agent
version
updated_at

Стартовые ключи:

user_request
detected_intent
customer_context
retrieved_facts
proposed_actions
risk_flags
approval_required
review_result
final_answer
handoff_reason

Правила:

1. агент читает только нужные state keys;
2. агент пишет только разрешенные keys;
3. каждое изменение увеличивает version;
4. спорные значения не перезаписываются молча;
5. полный raw chain-of-thought не хранится.

Проверка: `research_agent` не перезаписывает `review_result`.

Шаг 10. Настройте очередь задач `agent_task_queue`

Каждый агент получает конкретную задачу.

Колонки:

id
run_id
workflow_code
agent_code
task_type
input_state_keys_json
output_state_keys_json
status
attempts
created_at
started_at
finished_at

Статусы:

1. `pending`;
2. `running`;
3. `completed`;
4. `failed`;
5. `blocked_by_policy`;
6. `waiting_approval`;
7. `handoff`.

Проверка: задача агента имеет входные и выходные state keys, а не произвольную историю.

Шаг 11. Настройте router agent

Router не должен решать задачу, он только выбирает маршрут.

Router возвращает JSON:

{
  "intent": "support_question",
  "priority": "normal",
  "required_agents": ["research_agent", "reviewer_agent"],
  "risk_level": "medium",
  "needs_human": false
}

Проверяйте:

1. intent из разрешенного enum;
2. список агентов разрешен workflow_graph;
3. high-risk intent идет к supervisor;
4. unknown intent идет в handoff;
5. router не вызывает tools.

Проверка: вопрос про возврат денег не идет напрямую к `action_agent` без review.

Шаг 12. Настройте research agent

Research agent собирает факты, но не принимает решений.

Разрешенные действия:

1. искать в базе знаний;
2. читать доступные CRM-данные;
3. читать документы через RAG;
4. делать summary найденного;
5. возвращать citations;
6. помечать недостаток данных.

Запрещено:

1. отправлять сообщения;
2. менять CRM;
3. обещать возврат;
4. принимать финальное решение;
5. скрывать пустой retrieval.

Проверка: `research_agent` пишет `retrieved_facts`, но не пишет `final_answer`.

Шаг 13. Настройте action agent

Action agent готовит черновики действий.

Разрешенные output:

{
  "action_type": "create_ticket_draft",
  "requires_approval": true,
  "payload": {},
  "reason": "пользователь просит действие с внешним эффектом",
  "risk_level": "medium"
}

Правила:

1. только draft для write-действий;
2. schema validation обязательна;
3. high-risk всегда `requires_approval=true`;
4. action agent не делает final answer;
5. tool call проходит policy gate;
6. rejected approval останавливает действие.

Проверка: action agent создает черновик письма, но не отправляет его.

Шаг 14. Настройте reviewer agent

Reviewer проверяет результат до пользователя или tool execution.

Проверяет:

1. ответ опирается на факты;
2. есть citations;
3. нет запрещенных обещаний;
4. нет утечки PII;
5. tool payload валиден;
6. risk_level корректный;
7. нужен ли approval;
8. не нарушены policy;
9. нет конфликта между агентами;
10. нужно ли отправить человеку.

Результат:

{
  "review_status": "passed",
  "issues": [],
  "requires_human": false,
  "approved_state_keys": ["final_answer"]
}

Проверка: финальный ответ без citations получает `review_status=failed`.

Шаг 15. Настройте supervisor agent

Supervisor управляет процессом, но не должен бесконечно думать.

Supervisor решает:

1. кому передать следующую задачу;
2. завершить run;
3. повторить шаг;
4. остановить по лимиту;
5. отправить человеку;
6. запросить approval;
7. разрешить конфликт;
8. включить fallback.

Создайте `supervisor_decisions`.

Колонки:

id
run_id
decision_type
from_agent
to_agent
reason
state_version
created_at

Проверка: supervisor не может сделать больше `max_total_steps`.

Шаг 16. Настройте handoff

Handoff должен передавать контекст, а не просто "передаю дальше".

Создайте `handoff_log`.

Колонки:

id
run_id
from_agent
to_agent
handoff_reason
context_summary
state_keys_json
status
created_at

Причины:

1. task completed;
2. need more data;
3. tool required;
4. review required;
5. high risk;
6. conflict;
7. low confidence;
8. unknown intent;
9. human required;
10. policy block.

Проверка: следующий агент получает summary, нужные state keys и причину handoff.

Шаг 17. Логируйте сообщения агентов

Создайте `agent_messages`.

Колонки:

id
run_id
from_agent
to_agent
message_type
content_summary
content_hash
state_keys_json
created_at

Не храните бесконечную переписку как единственный источник правды. Источник правды - `shared_state`, а сообщения нужны для trace.

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

Шаг 18. Обрабатывайте конфликты

Конфликты будут: один агент предлагает ответ, reviewer блокирует; research нашел один факт, CRM другой.

Создайте `conflict_log`.

Колонки:

id
run_id
conflict_type
agent_a
agent_b
state_key
value_a_json
value_b_json
status
created_at

Создайте `conflict_resolution_rules`.

Колонки:

id
conflict_type
priority_order_json
resolution_action
requires_human
is_active

Правила:

1. reviewer важнее action agent;
2. access policy важнее research;
3. свежая CRM-запись важнее старого RAG-документа;
4. high-risk конфликт уходит человеку;
5. спорные данные не перезаписываются молча.

Проверка: конфликт суммы из двух источников попадает в `conflict_log`, а не исчезает.

Шаг 19. Добавьте approval

Создайте `approval_queue`.

Колонки:

id
run_id
agent_code
requested_action
risk_level
payload_summary
approver
status
approved_at
rejected_reason

Через approval идут:

1. отправка email;
2. изменение CRM;
3. платежи;
4. возвраты;
5. удаление данных;
6. публикация ссылок;
7. изменение прав;
8. внешний API с side effect;
9. массовые операции;
10. финальный ответ high-risk.

Проверка: multi-agent система не обходит approval через другого агента.

Шаг 20. Настройте run trace

Создайте `run_trace`.

Колонки:

id
run_id
span_id
parent_span_id
agent_code
span_type
status
started_at
finished_at
latency_ms
summary

Span types:

1. `routing`;
2. `agent_task`;
3. `model_call`;
4. `tool_call`;
5. `handoff`;
6. `review`;
7. `approval`;
8. `conflict_resolution`;
9. `final_answer`.

Проверка: по trace видно дерево выполнения, а не только финальный ответ.

Шаг 21. Ограничьте циклы

Multi-agent система легко зацикливается.

Добавьте лимиты:

1. `max_total_steps`;
2. `max_agent_steps`;
3. `max_handoffs`;
4. `max_tool_calls`;
5. `max_retries`;
6. `max_cost`;
7. `timeout_seconds`;
8. `max_conflicts`;
9. `max_review_failures`;
10. `max_same_agent_repeats`.

Проверка: если reviewer дважды отклонил ответ, run уходит человеку.

Шаг 22. Считайте стоимость

Создайте `cost_log`.

Колонки:

id
run_id
agent_code
model_id
input_tokens
output_tokens
tool_cost
estimated_cost
created_at

Отдельно считайте:

1. стоимость router;
2. стоимость research;
3. стоимость action;
4. стоимость reviewer;
5. стоимость supervisor;
6. стоимость tools;
7. стоимость retries;
8. стоимость failed runs.

Проверка: видно, какой агент делает систему дорогой.

Шаг 23. Логируйте ошибки

Создайте `error_log`.

Колонки:

id
run_id
agent_code
component
error_code
error_message
retryable
attempt
created_at

Ошибки:

1. wrong route;
2. invalid JSON;
3. tool denied;
4. tool timeout;
5. retrieval empty;
6. review failed;
7. conflict unresolved;
8. approval rejected;
9. cycle detected;
10. cost limit exceeded.

Проверка: ошибка маршрутизации видна отдельно от ошибки модели.

Шаг 24. Соберите eval cases

Создайте `multi_agent_eval_cases`.

Колонки:

id
case_name
input_json
expected_route_json
expected_final_state_json
forbidden_agents_json
forbidden_tools_json
risk_level
is_active

Добавьте тесты:

1. обычный вопрос поддержки;
2. вопрос без ответа в базе;
3. запрос на возврат;
4. prompt injection;
5. конфликт CRM и RAG;
6. tool error;
7. high-risk action;
8. unknown intent;
9. длинный контекст;
10. необходимость handoff человеку;
11. reviewer должен отклонить;
12. supervisor должен остановить цикл.

Проверка: eval проверяет маршрут, а не только финальный текст.

Шаг 25. Запускайте eval runs

Создайте `multi_agent_eval_runs`.

Колонки:

id
eval_case_id
workflow_code
agent_versions_json
actual_route_json
final_state_json
passed
failure_reason
cost
latency_ms
created_at

Запускайте evals:

1. перед добавлением нового агента;
2. перед заменой модели;
3. перед изменением workflow_graph;
4. перед добавлением tool;
5. после инцидента;
6. по расписанию.

Проверка: critical failure блокирует релиз multi-agent workflow.

Шаг 26. Настройте мониторинг

Dashboard должен показывать:

1. runs count;
2. completion rate;
3. wrong route rate;
4. handoff rate;
5. conflict rate;
6. review fail rate;
7. tool denial rate;
8. cycle detected;
9. cost per run;
10. latency p95;
11. top failing agents;
12. approval pending.

Проверка: если система стала хуже одного агента, это видно по метрикам.

Шаг 27. Проверьте end-to-end сценарий

Сценарий:

1. пользователь пишет заявку;
2. `router_agent` определяет intent;
3. `routing_decisions` сохраняет маршрут;
4. `research_agent` ищет факты;
5. `shared_state.retrieved_facts` обновляется;
6. `action_agent` готовит черновик;
7. `policy_gate` проверяет tool;
8. high-risk действие идет в `approval_queue`;
9. `reviewer_agent` проверяет citations и policy;
10. `supervisor_agent` завершает run;
11. `run_trace` показывает весь путь;
12. `audit_log` фиксирует решения.

Проверка: финальный ответ прошел review, а опасное действие не выполнено без approval.

Шаг 28. Минимальный результат для запуска

MVP готов, если выполнены условия:

1. есть `agent_registry`;
2. у каждого агента узкая роль;
3. есть `workflow_graph`;
4. есть структурированный `shared_state`;
5. есть `handoff_log`;
6. есть supervisor или router;
7. tools ограничены через `tool_policy`;
8. write-действия требуют approval;
9. reviewer проверяет результат;
10. конфликты пишутся в `conflict_log`;
11. циклы ограничены;
12. есть `run_trace`;
13. считается стоимость;
14. есть eval cases на routing;
15. production-мониторинг показывает ошибки маршрутов.

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

Что нельзя автоматизировать в первой версии

В первой версии не автоматизируйте:

1. бесконтрольное общение агентов друг с другом;
2. write-tools без approval;
3. удаление данных;
4. платежи и возвраты;
5. отправку внешних сообщений без проверки;
6. создание новых агентов на лету;
7. изменение workflow_graph моделью;
8. передачу секретов между агентами;
9. хранение chain-of-thought как state;
10. бесконечные retries;
11. маршрутизацию без evals;
12. финальный ответ без reviewer;
13. high-risk решение без человека;
14. общий доступ всех агентов ко всем tools;
15. production-запуск без run_trace и cost limits.

Сначала сделайте маленький workflow из 3-4 ролей. Добавлять агентов нужно только когда есть метрика, что текущая роль перегружена или опасно смешивает задачи.

Частые вопросы

Когда multi-agent лучше одного агента?

Когда есть разные роли, разные tools, разные права доступа, отдельный reviewer, сложный routing или high-risk действия. Если задача простая, один агент с workflow и guardrails обычно надежнее.

Кто должен управлять multi-agent системой?

Нужен router или supervisor. Router выбирает маршрут, supervisor следит за шагами, лимитами, handoff, conflict resolution и завершением run. Без этого агенты легко зацикливаются.

Как агенты должны обмениваться контекстом?

Через структурированный `shared_state`, а не через бесконечную переписку. Каждый агент читает нужные state keys и пишет только разрешенные output keys.

Как понять, что multi-agent система стала хуже?

Смотрите wrong route rate, handoff rate, conflict rate, review fail rate, cost per run, latency p95 и долю runs, где supervisor остановил цикл. Если метрики хуже одного агента, схему надо упрощать.

Какие фреймворки подходят для multi-agent?

Для контролируемых графов часто подходит LangGraph. Для crew-подхода с ролями можно смотреть CrewAI. Для code-first агентных приложений полезны OpenAI Agents SDK и Google ADK. Но фреймворк не заменяет state, policy, evals и мониторинг.