Запуски рабочих процессов

Workflow (рабочий процесс) — это программа, которую агент пишет, чтобы запустить множество агентов и объединить то, что они возвращают. Workflow run (запуск рабочего процесса) — это выполнение одного рабочего процесса. Dynamic workflows (динамические рабочие процессы) — это функция, которая позволяет агенту писать рабочие процессы и начинать запуски. Вы включаете или выключаете её с помощью настройки workflows в блоке multiagent агента.

Сервер выполняет рабочий процесс в фоновом режиме. Его агенты работают в «session threads» (потоках сессии), которые сервер создаёт по мере того, как они нужны рабочему процессу. Вы отслеживаете запуски в «event stream» (потоке событий) сессии. Чтобы остановить запуск, попросите агента остановить его (см. Прерывание сессии с открытыми запусками).

Как работают динамические рабочие процессы

Агент, которого запускает сессия, пишет каждый рабочий процесс под описанную вами работу. Рабочий процесс — это программа: она запускает других агентов, собирает то, что возвращает каждый из них, и объединяет результаты. Так агент может взяться за задачу, которая слишком велика для одного разговора, например за проверку сотен документов. Во время запуска агент может продолжать работу или завершить свой ход, а также может проверять состояние запуска.

На схеме показан один пример. У каждого рабочего процесса, который пишет агент, свои фазы и агенты. Запуск состоит из следующих уровней:

• Запуск рабочего процесса: Сервер выполняет рабочий процесс в фоновом режиме как один запуск рабочего процесса. В сессии одновременно может быть открыто несколько запусков.
• Фазы: Рабочий процесс может разделить свою работу на «phases» (фазы). Фаза — это именованный этап запуска, например «Прочитать договоры». Вы отслеживаете ход запуска по событиям его фаз.
• Потоки агентов: В фазе программа запускает агентов. Каждый агент работает в собственном потоке сессии по подсказке, которую написала программа. Агент в запуске может быть встроенным агентом («inline agent»), которого программа определяет сама, или предопределённым агентом («predefined agent»), которого вы указываете в списке predefined_agents настройки workflows. О том, что показывает каждый поток, см. Потоки запуска.

Программа может делать следующее:

• Запускать агентов одновременно: Программа может запускать множество агентов одновременно, что называется «fanning out» (веерный запуск). На схеме три агента читают договоры в первой фазе.
• Передавать результаты от одного агента другому: Каждый агент возвращает свой результат программе. Программа может передать этот результат другому агенту. На схеме агент во второй фазе работает с тем, что вернули первые три. Агенты запуска также работают с одними и теми же файлами в песочнице сессии.
• Самостоятельно делать следующий шаг: Результат агента поступает программе, а не агенту, которого запускает сессия. Программа определяет, какие агенты запускаются следующими, и пишет для них подсказки.
• Повторять и выбирать: Внутри фазы программа может повторять работу и выбирать следующий шаг на основе того, что вернул агент. Например, она может отправлять черновик на доработку, пока он не пройдёт проверку или не будет исчерпано заданное число раундов. На схеме программа может повторить шаг внутри второй фазы.
• Обрабатывать сбой агента: Когда один из её агентов завершается сбоем, сервер обычно запускает этого агента ещё раз в новом потоке, пока остальные агенты запуска продолжают работать. Если он снова завершится сбоем, программа может обработать сбой или позволить ему завершить запуск. Если программа обрабатывает сбой, запуск всё равно может завершиться с completed, поэтому попросите агента, которого запускает сессия, сообщать о том, что завершилось сбоем.

Когда запуск завершается, агент, которого запускает сессия, получает ход, чтобы прочитать, что сделал запуск. Затем он может ответить вам или начать другой запуск. В разделе События запуска перечислены случаи, когда этот ход наступает позже или не наступает вовсе.

Вы можете направлять то, как запуск выполняет работу, например как он разделяет работу и что делает при сбое агента. См. Укажите агенту, когда использовать запуск.

Перед началом запуска нет шага утверждения: агент начинает запуск в том же ходе, в котором пишет рабочий процесс. Чтобы сначала проверить план, попросите агента описать запуск и дождаться вашего одобрения. При начале запуска workflow_run.created показывает его имя, описание и фазы. Если начался запуск, который вы не одобряли, попросите агента остановить его (см. Прерывание сессии с открытыми запусками).

Как запуск переходит между состояниями

Запуск начинается в состоянии running (выполняется) или idle (простаивает). Например, достижение бюджета приостанавливает выполняющийся запуск, и он переходит в состояние idle; повышение или удаление бюджета затем снова возобновляет его выполнение, если только запуск не приостановило ещё и прерывание. Выполняющийся запуск завершается, когда его рабочий процесс заканчивается, агент останавливает его, он завершается сбоем, истекает его время жизни или сессия архивируется. Простаивающий запуск тоже может завершиться, например когда агент останавливает его или сессия архивируется.

Запуск открыт с момента события workflow_run.created до события workflow_run.status_ended, независимо от того, выполняется он или простаивает. Запуск простаивает, пока он приостановлен, например при достижении бюджета сессии. У запуска есть «lifetime» (время жизни), которое агент может задать при начале запуска. Время, которое запуск проводит в ожидании вашего клиента, засчитывается в это время жизни. Приостановка не останавливает отсчёт времени жизни запуска, поэтому запуск, который остаётся приостановленным, может завершиться с timeout_error. Следующие события сообщают о начале запуска, его фазах и его завершении. Приостановка при достижении бюджета тоже отправляет событие. Приостановка после прерывания может не отправить ни одного. Каждое событие workflow_run.* включает workflow_run_id, которое равно None только в workflow_run.error, когда запуск не был создан.

События запуска

События запуска поступают в поток событий сессии, который является потоком событий основного потока, и список событий сессии тоже их возвращает. События запуска не вызывают вебхуки. События статуса от потоков запуска поступают в тот же поток событий. Каждое из них указывает свой поток в session_thread_id, а потоки запуска — это те, чьё событие session.thread_created содержало workflow_run_id запуска.

Результат с ошибкой выглядит как {"type": "error", "error": {"type": "timeout_error", "message": "..."}}, где message безопасно записывать в журнал. Считайте нераспознанный result.type запуском, который завершился каким-то иным образом, а нераспознанный error.type — ошибкой. Когда отказывает что-то, от чего зависит сессия, например модель, сервер MCP, учётные данные или биллинг, поток событий отказавшего потока получает session.error. Само по себе это не завершает запуск. Но если это приводит к сбою одного из потоков запуска и рабочий процесс позволяет этому завершить запуск, запуск завершается с program_error.

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

1. workflow_run.created называет запуск «Find change-of-control clauses» и перечисляет фазы «Read the contracts» и «Reconcile the findings» в phases. Затем следует workflow_run.status_running.
2. События фаз отмечают каждую фазу, и каждый поток, который создаёт запуск, отправляет session.thread_created с workflow_run_id запуска.
3. Поступает workflow_run.status_ended с result: {"type": "completed"}.
4. Агент отвечает: «Такое положение есть в 41 из 300 договоров», и поступает session.status_idle с end_turn.

Первое событие запуска перечисляет его фазы:

{
  "type": "workflow_run.created",
  "id": "sevt_01abc...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "name": "Find change-of-control clauses",
  "description": "Reads each contract and lists those that have the clause.",
  "phases": [
    {
      "id": "wrph_01Kd3a1f3",
      "name": "Read the contracts",
      "description": "Reads each contract for the clause."
    },
    { "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
  ],
  "processed_at": "2026-10-09T14:01:45Z"
}

Каждое событие фазы указывает свою фазу через workflow_run_phase_id. Это id из phases, но API этого не гарантирует:

{
  "type": "workflow_run.phase_started",
  "id": "sevt_01def...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "workflow_run_phase_id": "wrph_01Kd3a1f3",
  "processed_at": "2026-10-09T14:01:46Z"
}

Последнее событие запуска сообщает, как он завершился:

{
  "type": "workflow_run.status_ended",
  "id": "sevt_01ghi...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "result": { "type": "completed" },
  "processed_at": "2026-10-09T14:09:12Z"
}

Потоки запуска

Каждый агент в запуске работает в собственном потоке сессии, который сервер создаёт, когда он нужен рабочему процессу. Вы можете получать список потоков запуска, читать их и получать их события в режиме потоковой передачи, как для любого дочернего потока, а также отвечать на их вызовы инструментов из основного потока событий. Чтобы остановить их, попросите агента остановить запуск (см. Прерывание сессии с открытыми запусками).

• Группировка: Поток запуска имеет workflow_run_id запуска, как и событие session.thread_created, которое о нём сообщает. У других потоков и событий session.thread_created, которые о них сообщают, workflow_run_id равно None.
• Агент: agent показывает агента, которого запускает поток. Для агента, которого вы указали в списке predefined_agents настройки workflows в multiagent, agent содержит id и version этого агента, как в потоке указанного вами субагента. Для агента, которого определяет рабочий процесс (встроенного агента), agent имеет type inline и не содержит id или version. Он содержит системную подсказку, которую написал рабочий процесс, а не подсказку агента сессии. Он также содержит имя и описание, которые дал ему рабочий процесс. Сервер назначает имя, если рабочий процесс его не дал. Такой агент использует модель агента сессии — агента, которого запускает сессия. Его инструменты, серверы MCP и навыки являются подмножеством инструментов, серверов MCP и навыков агента сессии. Он получает их все, но API этого не гарантирует. Его инструменты сохраняют свои политики разрешений.
• Что общего у потоков: Потоки запуска работают в песочнице сессии, поэтому каждый поток работает с одними и теми же файлами. Это включает файлы хранилища памяти, которое монтирует сессия. Агент, которого определяет рабочий процесс, использует свои серверы MCP с учётными данными, которые сессия для них разрешает. У каждого потока своя история разговора.
• События: События session.thread_created, session.thread_status_running, session.thread_status_idle и session.thread_status_terminated потока запуска также поступают в основной поток событий (см. События запуска). Его события сообщений остаются в его собственном потоке событий. Вебхуки потоков отправляются для него так же, как для любого дочернего потока. О том, что записывает собственный поток событий потока, см. События потока сессии.
• Фазы: Ни одно событие или поле не сообщает, в какой фазе работает поток, и потоки одного запуска могут иметь одинаковое agent_name. Отслеживайте ход запуска по событиям его фаз, а различайте его потоки по session_thread_id.
• Архивирование: Сервер архивирует каждый поток не позднее завершения его запуска. Он может архивировать поток раньше, как только поток вернёт свой результат или запуск закончит с ним работу. Если в этот момент поток ещё выполняется или ожидает вашего клиента, сервер сначала останавливает его. Архивированный поток остаётся в списке потоков со статусом terminated. Вам не нужно архивировать потоки запуска самостоятельно.
• Инструменты: Запуск может создать более одного потока для одной и той же части работы, поэтому сделайте инструменты, которые вызывают ваши агенты, безопасными для повторного вызова.

Как узнать, что работа выполнена

Пока запуск выполняется, ожидайте, что сессия останется в состоянии running, даже когда ни один из его потоков не работает. Она переходит в idle с requires_action, когда ни один поток не работает и какой-либо поток ожидает вашего клиента. Состояние idle само по себе не означает, что работа выполнена. Работа выполнена, когда верны оба условия:

1. Каждый запуск, создание которого вы видели, получил свой workflow_run.status_ended.
2. После этого поступает session.status_idle с stop_reason end_turn, и его не вызвал ваш собственный запрос, например прерывание. После прерывания учитывайте только idle, который наступает после вашего следующего user.message или user.define_outcome.

• Приостановленные запуски: Приостановленный запуск не удерживает сессию в состоянии running, поэтому сессия может перейти в idle, пока запуск ещё открыт. Например, при достижении бюджета сессия переходит в idle с budget_reached. Работа не выполнена, пока запуск не завершится.
• Другой запуск: Агент может начать новый запуск, когда читает результат, поэтому проверяйте снова.
• Результаты: Если вы определили результат, никакая оценка не начинается, пока запуск открыт, независимо от того, выполняется он или простаивает. Ход, в котором агент читает результат запуска, может начать оценку.
• retries_exhausted: Ход агента завершился сбоем из-за ошибки: повторные попытки исчерпаны, или ошибка не допускает повторных попыток, например сбой биллинга. Когда наступает этот idle, запуск может ещё выполняться. Если запуск завершился, а агент ещё не прочитал его результат, сервер начинает новый ход без ввода с вашей стороны. Сессия снова переходит в running, поэтому дождитесь следующего idle. Если сессия остаётся в idle, прочитайте session.error, который пришёл перед ним, и устраните причину. Затем отправьте user.message или прочитайте result каждого запуска самостоятельно.

Отслеживание запуска

Этот пример отслеживает сессию от вашего сообщения до ответа агента. Он открывает поток событий и отправляет сообщение. Затем он делает следующее:

• Отслеживает каждый запуск от его workflow_run.created до его workflow_run.status_ended и выводит каждую фазу при её начале.
• Отвечает на вызовы пользовательских инструментов при поступлении каждого agent.custom_tool_use, потому что поток запуска может ожидать вашего клиента, пока сессия остаётся в состоянии running. Если инструменты вашего агента запрашивают подтверждение, добавьте ветвь, которая отвечает на каждый agent.tool_use или agent.mcp_tool_use, у которого evaluated_permission равно ask. В примере такой ветви нет, потому что ветвь, разрешающая каждый вызов, превратила бы always_ask в «всегда разрешать».
• Останавливается, когда работа выполнена: ни один запуск не открыт, и сессия переходит в idle с end_turn. Он также останавливается, если сессия прекращается. При idle с любой другой причиной остановки, кроме requires_action, например budget_reached, retries_exhausted или refusal, он выводит причину и останавливается, поэтому обрабатывайте такие случаи в собственном коде. Он останавливается на retries_exhausted, даже когда сервер вот-вот сам начнёт новый ход. Он продолжает ожидание при requires_action, а также при end_turn, пока запуск открыт.

open_runs: dict[str, str] = {}  # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {}  # (run ID, phase ID) -> phase name

# Сначала откройте поток, затем отправьте сообщение пользователя
with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Which contracts in /contracts have a change-of-control clause?",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "workflow_run.created":
                open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    phase_names[event.workflow_run_id, phase.id] = phase.name
                print(f"Run started: {event.name}")
            case "workflow_run.phase_started":
                phase_id = event.workflow_run_phase_id
                key = (event.workflow_run_id, phase_id)
                print(f"  Phase: {phase_names.get(key, phase_id)}")
            case "workflow_run.status_ended":
                name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
                print(f"Run ended: {name} ({event.result.type})")
            case "agent.custom_tool_use":
                # Отвечайте, когда придёт событие. Поток запуска может ожидать вашего
                # клиента, пока сеанс остаётся в состоянии выполнения.
                result = call_tool(event.name, event.input)
                try:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[
                            {
                                "type": "user.custom_tool_result",
                                "custom_tool_use_id": event.id,
                                "content": [{"type": "text", "text": result}],
                            },
                        ],
                    )
                except anthropic.BadRequestError as error:
                    # Сервер отклоняет результат, пришедший слишком поздно, после того как он
                    # заархивировал поток вызова. Продолжайте отслеживать запуск.
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # Готово, когда все запуски завершены и агент закончил свой ход
                if not open_runs and event.stop_reason.type == "end_turn":
                    break
                # Состояние idle с requires_action ожидает вашего клиента, поэтому продолжайте чтение.
                # При любой другой причине остановки выведите её и остановитесь.
                if event.stop_reason.type not in ("end_turn", "requires_action"):
                    print(f"Session idle: {event.stop_reason.type}")
                    break
            case "session.status_terminated":
                break

Прерывание сессии с открытыми запусками

Отправьте user.interrupt без session_thread_id или с ID основного потока. Это останавливает ход агента. Это не завершает ни одного запуска. Запуски сессии могут приостановиться или продолжить выполнение, и их события могут не показывать, что именно произошло. Время жизни приостановленного запуска продолжает истекать, поэтому запуск может завершиться с timeout_error, пока он приостановлен.

• Ожидающие вызовы инструментов: После прерывания вызов инструмента потока запуска может всё ещё ожидать вашего клиента. Ответьте на каждый из них. Чтобы отменить вызов, запрашивающий подтверждение, отклоните его. Чтобы отменить вызов пользовательского инструмента, отправьте результат с is_error, равным true, и текстом в content, объясняющим причину. Пока сессия находится в состоянии idle с requires_action, user.message возвращает 400, поэтому сначала ответьте на вызовы.
• Чтобы остановить запуски: Отправьте user.message с просьбой к агенту остановить свои запуски. Остановленный запуск завершается с result {"type": "stopped"}. Пока сессия находится в состоянии idle с budget_reached, user.message возвращает 400, пока вы не повысите или не удалите бюджет. Повышение или удаление бюджета также возобновляет приостановленные им запуски, если только их не приостановило ещё и прерывание.
• Чтобы продолжить: Отправьте user.message с просьбой к агенту продолжить свои запуски. После прерывания запуски могут ожидать этого сообщения. Если сессия находится в состоянии idle с budget_reached, сначала повысьте или удалите бюджет.
• Результаты запусков: Запуск, который завершается после прерывания, всё равно отправляет workflow_run.status_ended.

Пока запуск открыт

Восстановление состояния запусков после переподключения

Восстанавливайте состояние каждого запуска по событиям сессии. Поток событий не воспроизводит то, что вы пропустили: новое соединение доставляет только события, сгенерированные после его открытия. Поэтому получите список событий с фильтром types, указав по одной записи для каждого типа события, как в разделе Получение списка прошлых событий. Передавайте next_page из каждого ответа как page, пока next_page не станет None или не будет отсутствовать. События workflow_run.created, workflow_run.status_running, workflow_run.status_idle и workflow_run.status_ended дают состояние каждого запуска, за исключением того, что запуск, приостановленный после прерывания, может по-прежнему отображаться как выполняющийся. События workflow_run.phase_started и workflow_run.phase_ended позволяют восстановить ход выполнения. Запуск, для которого ещё нет ни одного события статуса, ещё не начал выполняться. Конечной точки для получения списка запусков нет.

Стоимость и бюджеты

Запросы к модели, которые делает запуск, засчитываются в бюджет сессии. У запуска нет собственной цены. Токены, которые используют его агенты, оплачиваются так же, как другие токены сессии, по тарифам каждой модели. Обо всех расходах сессии см. Цены на Claude Managed Agents.

• Использование одного запуска: Получите список потоков сессии и сложите количество токенов в usage потоков с workflow_run_id этого запуска. Список включает архивированные потоки со статусом terminated, поэтому потоки завершённого запуска тоже учитываются. Передавайте next_page из каждого ответа как page, пока next_page не станет None или не будет отсутствовать, и пропускайте потоки без usage. Если вместо этого сложить list_cost потоков, в итог не войдёт время выполнения сессии, а каждое значение округляется отдельно.
• При достижении бюджета: Все открытые запуски приостанавливаются, и сессия сообщает idle с budget_reached или requires_action, если также ожидает вызов инструмента. Каждый поток завершает уже начатый запрос к модели, поэтому запуск может превысить бюджет на один запрос для каждого работающего потока. Повышение или удаление бюджета возобновляет приостановленные им запуски, если только их не приостановило ещё и прерывание. Если использование сессии включает модель без прейскурантной цены, возобновляет их только удаление бюджета; см. Модели без прейскурантной цены. Время жизни приостановленного запуска продолжает истекать, поэтому запуск может завершиться с timeout_error, пока он приостановлен.

Ограничения

Сервер сокращает name запуска или фазы до 64 символов, а description — до 256. У сервера есть и другие ограничения для рабочих процессов, а также правила для них, которые здесь не перечислены. То, что вы увидите, зависит от того, когда сервер обнаружит проблему:

Сессия может начать любое количество запусков за время своей жизни.

• Начало запусков: Запуски начинает только агент в основном потоке сессии. Агент, работающий в потоке запуска, не может начать собственный запуск, поэтому запуски не вкладываются друг в друга.
• Завершение запусков: Ни одно отправляемое вами событие не завершает запуск; это может сделать архивирование сессии.
• Потоки запуска: Вы не можете остановить поток по его ID или архивировать его, пока его запуск открыт.
• Ограничение потоков: На потоки запуска не распространяется ограничение дочерних потоков сессии.
• Видимость: Вы не видите код рабочего процесса, но можете запросить рабочий процесс у агента, как описано в совете в разделе Потоки запуска. Вы также не видите вызовы инструментов, которые агент делает для начала запусков и управления ими, и результат, который каждый поток возвращает рабочему процессу.

Ограничения скорости

Работа запуска засчитывается в ограничения скорости, которые уже действуют для вашей организации.

Когда запрос к модели из одного из потоков запуска ограничивается по скорости или модель перегружена, собственный поток событий этого потока может получить session.error типа model_rate_limited_error или model_overloaded_error:

• Если его retry_status.type равен retrying, сервер повторяет запрос, и поток продолжает работать.
• Если он равен exhausted, поток завершился сбоем. Если рабочий процесс позволяет этому сбою завершить запуск, запуск завершается с program_error, который не указывает причину. Прочитайте события потоков, завершившихся сбоем, чтобы найти её.

Сервер также ограничивает объём работы, которую все сессии вашей организации выполняют за минуту. Поток, который достигает этого ограничения, останавливается с session.error в собственном потоке событий, сообщение которого указывает на ограничение скорости. Подождите минуту, прежде чем просить агента продолжить.