Многоагентные сессии

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

Многоагентность — это функция Research Preview. Запросите доступ, чтобы попробовать её.

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

Все запросы к API Managed Agents требуют бета-заголовка managed-agents-2026-04-01. Для функций research preview требуется дополнительный бета-заголовок. SDK автоматически устанавливает эти бета-заголовки.

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

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

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

Каждый агент использует собственную конфигурацию (модель, системный запрос, инструменты, MCP-серверы и навыки), определённую при создании этого агента. Инструменты и контекст не являются общими.

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

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

Проверка кода: Агент-рецензент с сфокусированным системным запросом и инструментами только для чтения.
Генерация тестов: Агент для тестирования, который пишет и запускает тесты без изменения production-кода.
Исследование: Агент поиска с веб-инструментами, который суммирует результаты для координатора.

Объявление вызываемых агентов

При определении вашего агента перечислите дополнительные ID агентов, которых он может вызывать:

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

Затем создайте сессию, ссылающуюся на координатора:

Вызываемые агенты разрешаются из конфигурации координатора. Вам не нужно ссылаться на них при создании сессии.

Потоки сессии

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

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

Перечислите все потоки в сессии следующим образом:

Потоковая передача событий из конкретного потока:

Перечислите прошлые события для потока:

Типы событий многоагентной системы

Эти события отображают многоагентную деятельность в потоке сессии верхнего уровня.

Тип	Описание
`session.thread_created`	Координатор создал новый поток. Включает `session_thread_id` и `model`.
`session.thread_idle`	Поток агента завершил свою текущую работу.
`agent.thread_message_sent`	Агент отправил сообщение в другой поток. Включает `to_thread_id` и `content`.
`agent.thread_message_received`	Агент получил сообщение из другого потока. Включает `from_thread_id` и `content`.

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

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

session_thread_id присутствует: событие произошло в потоке подагента. Повторите его в вашем ответе.
session_thread_id отсутствует: событие пришло из основного потока. Ответьте без этого поля.
Сопоставьте tool_use_id, чтобы связать запросы с ответами.

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

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
callable_agents:
  - type: agent
    id: $REVIEWER_AGENT_ID
    version: $REVIEWER_AGENT_VERSION
  - type: agent
    id: $TEST_WRITER_AGENT_ID
    version: $TEST_WRITER_AGENT_VERSION
YAML

with client.beta.sessions.threads.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_idle":
                break

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])