Мультиагентные сессии

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



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

Все агенты используют общую песочницу, файловую систему и учётные данные хранилища, но каждый агент работает в собственном потоке сессии (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 по идентификатору. Если version не указана, ссылка закрепляется за последней версией этого агента на момент создания координатора.
• {"type": "agent", "id": agent.id, "version": agent.version} закрепляет конкретную версию агента.
• {"type": "self"} позволяет координатору создавать копии самого себя. Если сессия была создана с переопределениями конфигурации агента, эти переопределения также применяются к этим копиям; записи списка, на которые ссылаются по идентификатору, не затрагиваются.

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

Координатор может делегировать только на один уровень агентов; глубина > 1 игнорируется. В 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)

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



Потоки

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

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

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



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

Эти события отображают мультиагентную активность в основном потоке по адресу /v1/sessions/:id/events/stream.



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

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



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

Если субагенту требуется что-то от вашего клиента, например разрешение на запуск инструмента с режимом 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",
            }
        ],
    )