Мультиагентная оркестрация

Мультиагентная оркестрация (multiagent orchestration) позволяет одному агенту координировать работу с другими для выполнения сложных задач. Агенты могут действовать параллельно, каждый со своим изолированным контекстом, что помогает повысить качество результата, а также может сократить время выполнения.

Не уверены, что мультиагентная конфигурация подходит для вашей задачи? См. статью когда использовать мультиагентные системы (а когда нет).

Как это работает

Все агенты используют одну и ту же песочницу, файловую систему и учётные данные хранилища (vault credentials), но каждый агент работает в собственном потоке сессии (session thread) — изолированном по контексту потоке событий со своей историей разговора. Координатор сообщает о своей активности в основном потоке (primary thread), который совпадает с потоком событий уровня сессии; дополнительные потоки создаются во время выполнения, когда координатор делегирует работу.

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

Каждый агент использует собственную конфигурацию: модель, системную подсказку, инструменты, серверы MCP и навыки. Исключение составляют переопределения конфигурации агента на уровне сессии; они применяются к координатору и его копиям self. Инструменты, серверы MCP и контекст не являются общими.

Что делегировать

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

Хорошо работающие паттерны:

• Параллелизация: одновременно распределяйте независимые подзадачи (поиск по нескольким источникам, анализ отдельных файлов), а координатор синтезирует результаты.
• Специализация: направляйте задачи агентам с предметно-ориентированными системными подсказками и инструментами, например агенту по безопасности или агенту по документации, вместо того чтобы нагружать одного агента всеми возможностями.
• Эскалация: обращайтесь к более способному агенту или модели для подмножества сложных подзадач.

Настройка координатора

При определении вашего агента задайте multiagent, чтобы объявить список (roster) агентов, которым координатор может делегировать работу:

ant beta:agents create < coordinator.agent.yaml

name: Engineering Lead
model: claude-opus-5
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID # replace before running command
    - type: agent
      id: $TEST_WRITER_AGENT_ID # replace before running command

multiagent.agents может принимать любое из следующих значений:

• {"type": "agent", "id": agent.id} ссылается на ранее созданного агента agent по ID. Если version не указана, ссылка закрепляется за последней версией этого агента на момент создания координатора.
• {"type": "agent", "id": agent.id, "version": agent.version} закрепляет конкретную версию агента.
• {"type": "self"} позволяет координатору создавать копии самого себя. Если сессия была создана с переопределениями конфигурации агента, эти переопределения также применяются к этим копиям; записи списка, на которые ссылаются по ID, не затрагиваются.
• {"type": "advisor", "model": "<model id>"} предоставляет основному потоку сессии советника (advisor), к которому он может обращаться в середине хода. Не более одной записи советника на список. См. Предоставление сессии советника.

Конфигурация координатора, включая его список multiagent.agents, фиксируется в виде снимка при создании или обновлении координатора. Агенты, на которые есть ссылки, остаются закреплёнными за версиями, разрешёнными в тот момент, и не подхватывают автоматически последующие обновления своих определений. Чтобы делегировать работу более новой версии агента, на которого есть ссылка, обновите координатора, чтобы его список ссылался на эту версию.

Координатор может делегировать только одному уровню агентов; ссылка на агента, у которого есть собственный список multiagent.agents, приводит к отклонению запроса на создание или обновление с ошибкой валидации. В multiagent.agents можно указать максимум 20 уникальных агентов, но координатор может вызывать несколько копий каждого агента.

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

Предоставление сессии советника

Запись советника в multiagent.agents предоставляет основному потоку сессии советника (advisor): модель, к которой он может обращаться в середине хода за стратегическими рекомендациями, например для планирования подхода, выхода из тупика или проверки работы перед завершением. Запись содержит ровно два поля, type и model:

curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Backend engineer",
    "model": "claude-sonnet-5",
    "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "advisor", "model": "claude-opus-5"}
      ]
    }
  }'

Список может содержать не более одной записи советника наряду с любыми другими формами записей списка. Запись занимает зарезервированное имя в списке anthropic.advisor: список, в котором указаны и запись советника, и участник с буквальным именем anthropic.advisor, отклоняется с ошибкой валидации 400. В ответах запись советника возвращается последней в списке независимо от позиции, в которой она была отправлена.

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

Советник также доступен как серверный инструмент в Messages API. Поверхность Managed Agents отличается конфигурацией и способом доставки: запись списка не имеет полей max_uses, max_tokens или caching, а рекомендации поступают через события потоков, а не через блоки advisor_tool_result.

Как работают консультации

Каждая консультация выполняется как создаваемый платформой поток с именем anthropic.advisor, который завершает сам себя по окончании консультации, а рекомендация доставляется в основной поток как событие agent.thread_message_received. Консультация генерирует стандартные события потоков, идентифицируемые зарезервированным именем anthropic.advisor (события жизненного цикла потока несут его как agent_name, а доставка рекомендации — как from_agent_name), обычно в следующем порядке:

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received (рекомендация)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

Для консультации не генерируются события agent.tool_use, и в потоке событий сессии не появляется событие agent.thread_message_sent, поскольку входные данные консультации формируются платформой, а не отправляются агентом. Если вы запросите список собственных событий потока советника, рекомендация также появится там как событие agent.thread_message_sent. Доставка рекомендации (событие 3) не гарантированно приходит раньше событий idle и terminated потока советника, поэтому не рассматривайте их как сигнал того, что рекомендация уже доставлена.

Может ли ваш клиент прочитать рекомендацию, определяется политикой модели советника, и это отражает разделение на варианты результата в инструменте советника Messages API. Модели советника, которые там возвращают результаты в виде открытого текста, здесь доставляют рекомендацию как читаемое текстовое содержимое; модели советника, которые там возвращают скрытые (redacted) результаты, здесь доставляют заполнитель [{"type": "redacted"}] в качестве содержимого сообщения на каждой клиентской поверхности, при этом сам агент по-прежнему читает полную рекомендацию на стороне сервера. В приведённом выше примере Claude Opus 5 является советником со скрытым результатом, поэтому ваш клиент видит заполнитель, в то время как агент читает полную рекомендацию; выберите вместо него Claude Opus 4.8 в качестве советника, если хотите, чтобы рекомендация была читаемой в потоке событий. Мышление советника никогда не раскрывается. Клиенты не могут сами отправлять блоки redacted; событие, содержащее такой блок, отклоняется с ошибкой валидации 400.

Неудачная или прерванная консультация никогда не приводит к сбою хода агента: агент продолжает работу после общего уведомления о том, что консультация не удалась. user.interrupt на уровне сессии во время консультации завершает поток советника без доставки рекомендации; user.interrupt с session_thread_id потока советника отменяет только эту консультацию.

Потоки советника

Советник не является агентом из списка: он невидим для инструмента координатора list_agents, ему нельзя отправить сообщение с помощью send_to_agent, и обращаться к нему может только основной поток сессии. Агенты из списка не могут.

Потоки советника не учитываются в лимите одновременных потоков. Они отображаются в списке потоков сессии с полем agent, установленным в форму советника точно так, как она настроена ({"type": "advisor", "model": ...}), и parent_thread_id, указывающим на основной поток.

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

Удаление советника

Чтобы удалить советника, обновите агента, указав список, который больше не содержит записи советника. Если советник — единственная запись в списке, очистите список полностью, установив "multiagent": null.

Создание сессии

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

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)

Подключение агентов к серверам MCP

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

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

Переопределения конфигурации агента при создании сессии могут заменить серверы MCP координатора и его копий self.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-5",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

В этом примере только исследователь (researcher) объявляет сервер MCP GitHub, поэтому координатор не имеет к нему доступа. vault_ids сессии предоставляют учётные данные GitHub потоку исследователя.

Потоки

Поток событий уровня сессии (/v1/sessions/{session_id}/events/stream) считается основным потоком и содержит сжатое представление всей активности во всех потоках. Вы не видите полную активность субагентов, но видите начало и конец их работы, а также блокирующие события, такие как запросы разрешений на использование инструментов.

Потоки сессии — это место, где вы можете детально изучить активность конкретного агента.

status сессии является агрегацией активности всех агентов; если хотя бы один поток находится в состоянии running, то и общий статус сессии также running.

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

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")

События основного потока

Эти события отражают мультиагентную активность в основном потоке по адресу /v1/sessions/{session_id}/events/stream. События, связанные с направлением сообщений, именуются относительно потока, в чьём потоке событий они появляются: agent.thread_message_received означает, что в этот поток пришло сообщение из другого потока, а agent.thread_message_sent означает, что этот поток отправил сообщение. Например, задача, которую делегирует координатор, приходит в собственный поток событий дочернего потока как событие agent.thread_message_received.

Консультации советника генерируют эти же события потоков под зарезервированным именем anthropic.advisor (как agent_name в событиях жизненного цикла потока и from_agent_name при доставке рекомендации); последовательность см. в разделе Предоставление сессии советника.

События потоков сессии

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

Каждый поток сессии имеет собственный поток событий по адресу /v1/sessions/{session_id}/threads/{thread_id}/stream, и он принимает тот же параметр event_deltas[], что и поток уровня сессии, поэтому вы можете предварительно просматривать текст субагента по мере его генерации моделью. Соединение показывает предварительный просмотр только того потока, который оно читает: предварительные просмотры дочернего потока никогда не появляются в потоке уровня сессии, поэтому, чтобы наблюдать за субагентом в реальном времени, откройте его собственный поток событий. О том, как включить, накапливать и согласовывать предварительные просмотры, см. в разделе Предварительный просмотр событий потоков сессии.

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_status_idle":
                break

Разрешения инструментов и пользовательские инструменты

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

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["sevt_01XYZ..."]
  }
}

Отправьте user.tool_confirmation (с tool_use_id) или user.custom_tool_result (с custom_tool_use_id); сервер автоматически направит ответ в нужный поток.

Следующий пример расширяет обработчик подтверждения инструментов для маршрутизации ответов. Тот же паттерн применим к user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )