Как построить мультиагентную систему: практическое руководство по паттерну supervisor

Когда вы уже усвоили концепцию «координации нескольких ИИ» из статьи Что такое мультиагентная система?, следующий вопрос — как её реально построить. В этой статье мы пройдём практический процесс из 5 шагов для начинающих, используя де-факто стандарт 2026 года: паттерн supervisor.

Прежде чем говорить о фреймворках, вот самый важный принцип: «сначала стройте на одном агенте и добавляйте агентов минимально — только когда упрётесь в предел». Начинать сразу с толпы агентов — как правило, переусложнение. Во второй половине статьи — минимальный читаемый код по официальной документации Claude Agent SDK и OpenAI Agents SDK, а также то, как делить роли, и ошибки, которые встречаются на практике. Та же логика работает, если вы подключаете инструменты через MCP.

Примечание: код написан по официальной документации Claude Agent SDK и OpenAI Agents SDK (проверено 4 октября 2026 года). Эти SDK быстро меняются, поэтому перед запуском сверяйте имена параметров с официальной документацией. Для каждой цифры в статье указан источник.

1. Перед началом: действительно ли вам нужна мультиархитектура?

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

Как говорилось в предыдущей статье, мультиагентность на линейном процессе обходится дорого. В исследовании Google Research (опубликовано в январе 2026 года, сравнивались 180 конфигураций) все проверенные мультиагентные варианты справились на 39–70% хуже одного агента с задачей на строго последовательное рассуждение (PlanCraft). Растут и расходы: в разборе собственного исследовательского агента Anthropic пишет, что агенты расходуют примерно в 4 раза больше токенов, чем чат, а мультиагентные системы — примерно в 15 раз. Отправная точка: больше агентов не значит умнее.

2. Базовая форма: паттерн supervisor

Если сомневаетесь, какой паттерн выбрать, безопаснее всего начать с паттерна supervisor. Основные SDK описывают его как базовый. В Claude Agent SDK главный агент вызывает субагентов через инструмент Agent; в OpenAI Agents SDK ему соответствует «agents as tools»: агент-менеджер вызывает агентов-специалистов как инструменты.

Механика проста. Supervisor получает общую задачу, разбивает её на подзадачи, делегирует их специализированным worker и агрегирует результаты. Supervisor не обязан знать, как worker выполняет свою работу — только какого worker вызвать и в каком формате вывода. Экспертиза живёт в worker.

Учтите: в OpenAI Agents SDK handoff означает нечто более узкое, чем передача работы в шаге 4: агент-диспетчер передаёт сам разговор специалисту, и дальше тот отвечает пользователю напрямую. Supervisor при этом не остаётся, так что это отдельный паттерн (когда что выбирать — в разделе 6).

3. Построение за 5 шагов

Соберите минимальную конфигурацию supervisor за пять шагов. Правило большого пальца: начинайте с 2-3 worker, а затем добавляйте новых только тогда, когда это оправдано измерениями.

4. Минимальный код ①: Claude Agent SDK (Python)

Сначала соберём один supervisor и два worker (исследователя и проверяющего) на Claude Agent SDK от Anthropic. Подготовка — только pip install claude-agent-sdk и переменная окружения ANTHROPIC_API_KEY (официальный quickstart; файлы .env SDK автоматически не читает). Код следует официальной странице Subagents. Об SDK в целом — в нашем руководстве по Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # supervisor (главный агент)
    system_prompt=(
        "Ты координируешь исследовательский отчёт. Поиск поручай researcher, проверку "
        "фактов — reviewer, итоговый текст пиши сам. Поручая задачу, всегда указывай "
        "цель, формат ответа и границы."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # инструменты, которые работают без запроса разрешения
    agents={
        "researcher": AgentDefinition(
            description="Собирает первоисточники. Использовать, когда нужны факты или цифры.",
            prompt="Найди первоисточники по вопросу и верни список с URL каждого источника. Не заполняй пробелы догадками.",
            tools=["WebSearch", "WebFetch"],  # единственные инструменты этой роли
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Проверяет черновики. Использовать всегда перед финальной версией.",
            prompt="Сверь каждое утверждение черновика с источником и перечисли фразы без подтверждения.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # лимит циклов для всего запуска
    max_budget_usd=5.0,   # лимит расходов (оценка SDK)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # worker не создают своих субагентов
)


async def main():
    try:
        async for message in query(
            prompt="Найди три официальные статистики об использовании генеративного ИИ в работе и напиши короткий отчёт",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Остановлено досрочно: {error}")  # сюда же попадает достижение лимита


asyncio.run(main())

Пять моментов, на которые стоит обратить внимание:

• Worker перечисляются в agents как записи AgentDefinition. Supervisor читает description каждого worker и решает, кого и когда вызвать, поэтому конкретно описывайте, что делает роль и когда её использовать.
• Если перечислить tools, у роли будут только эти инструменты. Поэтому у проверяющего нет инструментов записи. А allowed_tools — это список инструментов, которые запускаются без запроса разрешения; он ничего не ограничивает (официальный справочник Python).
• Ставьте лимиты в трёх местах. maxTurns для каждой роли, общий max_turns и лимит расходов max_budget_usd. При достижении общего лимита подтип результата становится error_max_turns или error_max_budget_usd, и запуск останавливается (документация по циклу агента).
• Остановите вложенность. Субагенты могут порождать своих субагентов. Если задать переменной окружения CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH значение 1, worker будут выполнять работу сами. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (по умолчанию 20) ограничивает, сколько их работает одновременно.
• Поля AgentDefinition пишутся в camelCase. Если написать max_turns вместо maxTurns, при создании возникнет TypeError (официальное примечание). Supervisor использует текущую claude-opus-5-5, а worker — псевдоним "sonnet", чтобы код продолжал работать при выходе новой версии.

Официальная документация отмечает, что Opus 5 охотнее предыдущих моделей поручает работу субагентам, и советует задавать лимиты глубины, параллельности и расходов в дополнение к инструкциям в промпте. Инструкция меняет лишь то, как Claude просит о помощи; надёжно останавливают запуск только лимиты.

5. Минимальный код ②: OpenAI Agents SDK (Python)

В Agents SDK от OpenAI та же форма строится так: агенты-специалисты превращаются в инструменты через as_tool() и передаются в tools supervisor (официальный раздел «agents as tools»). Подготовка — pip install openai-agents и переменная окружения OPENAI_API_KEY (официальный quickstart). Если не указать model, будет использована модель SDK по умолчанию; она меняется от версии к версии, поэтому сверяйтесь со страницей Models.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Найди первоисточники по вопросу и верни список с URL каждого источника. Не заполняй пробелы догадками.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Сверь каждое утверждение полученного черновика с источником и перечисли фразы без подтверждения.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "Ты координируешь исследовательский отчёт. Поиск поручай research, проверку "
        "фактов — review, итоговый текст пиши сам."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Собрать первоисточники со ссылками",
            max_turns=10,  # лимит циклов этой роли
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Проверить факты в черновике",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Найди три официальные статистики об использовании генеративного ИИ в работе и напиши короткий отчёт",
        max_turns=10,  # при превышении — MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

Что у двух SDK общего и чем они различаются:

• Worker не знает разговора родителя. Агент, вызванный через as_tool(), не наследует автоматически состояние разговора родительского запуска (официальная документация). В Claude Agent SDK так же: от родителя субагент получает только промпт инструмента Agent. Пути к файлам, тексты ошибок и принятые решения пишите прямо в поручении.
• Лимит — Runner.run(..., max_turns=). При превышении выбрасывается MaxTurnsExceeded. Если передать error_handlers={"max_turns": ...}, вместо исключения можно вернуть заранее заданный ответ (Running agents).
• С handoff код выглядел бы так: Agent(..., handoffs=[billing_agent, refund_agent]). Принимающий агент берёт разговор на себя и по умолчанию видит всю предыдущую историю. Если какие-то данные ему передавать нельзя, сузьте их через input_filter.

6. Как делить роли: удачные и неудачные разбиения

Разделить роли сложнее, чем написать код. Anthropic пишет, что каждому субагенту нужны цель, формат вывода, указания, какие инструменты и источники использовать, и чёткие границы задачи (тот же разбор). Ниже — разбиения, которые выполняют эти четыре условия, и те, что не выполняют.

В том же разборе есть ориентир, сколько агентов запускать. Anthropic вписала правила масштабирования в промпт своего исследовательского supervisor: для простого поиска фактов — 1 агент и 3–10 вызовов инструментов, для прямого сравнения — 2–4 субагента по 10–15 вызовов, сложное исследование может задействовать больше 10 субагентов. Это цифры для исследовательской работы, поэтому в своей задаче начинайте с малого и добавляйте только после измерений.

Выбирать между supervisor и handoff помогает понятный критерий из документации OpenAI. Если итоговый ответ должен принадлежать одному агенту или нужно объединить результаты нескольких специалистов — supervisor (agents as tools). Если сама маршрутизация и есть работа, а выбранный специалист должен отвечать пользователю напрямую (например, распределение обращений в поддержку), — handoff. Их можно сочетать.

7. Частые ошибки и способы их избежать

Места, где спотыкаются, предсказуемы. Ниже — ошибки, которые, по словам Anthropic, реально случались с её исследовательским агентом, и то, о чём предупреждает официальная документация обоих SDK.

Общий урок: «промпты, проектирование инструментов и набор evals решают успех в большей степени, чем фреймворк». Документация OpenAI тоже называет вложения в хорошие промпты, мониторинг и доработку, специализированных агентов и evals. Важнее эффектной архитектуры — дисциплина строить мало, измерять и добавлять только тогда, когда это окупается; в итоге именно она оказывается самой быстрой.

Итоги

Построение мультиагентной системы не страшно, если начать с паттерна supervisor в минимальной конфигурации. Давайте подведём итог.

«Стройте мало, измеряйте, потом добавляйте». Держите эту дисциплину — и мультиагентная система станет мощным партнёром для сложной работы. Про концепцию см. Что такое мультиагентная система?; про построение одиночного агента — Как построить ИИ-агента.

FAQ