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

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

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



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

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

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

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



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

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

Паттерны, которые хорошо работают:

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



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

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

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
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
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

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

• {"type": "agent", "id": agent.id} ссылается на ранее созданный agent по ID. Если version не указана, ссылка закрепляется за последней версией этого агента на момент создания координатора.
• {"type": "agent", "id": agent.id, "version": agent.version} закрепляет конкретную версию агента.
• {"type": "self"} позволяет координатору создавать копии самого себя. Если сессия была создана с переопределениями конфигурации агента, эти переопределения также применяются к этим копиям; записи списка, на которые ссылаются по ID, не затрагиваются.

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

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



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

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

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-4-8",
    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)

В этом примере только исследователь объявляет сервер GitHub MCP, поэтому координатор не имеет доступа. 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.



События потока сессии

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

Каждый поток сессии имеет свой собственный поток событий по адресу /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": ["toolu_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",
            }
        ],
    )