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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

События запуска поступают в поток событий сессии, то есть в поток событий основного потока, и список событий сессии тоже их возвращает. События запуска не вызывают webhooks (вебхуки). События состояния из потоков запуска поступают в тот же поток событий. Каждое из них указывает свой поток в 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» и перечисляет в phases фазы «Read the contracts» и «Reconcile the findings». Затем следует 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"
}

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

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

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

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

Пока запуск выполняется, ожидайте, что сессия останется в состоянии 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, по одной записи types[] для каждого типа событий, как в разделе Получение списка прошлых событий. Передавайте next_page каждого ответа как page, пока next_page не станет null или не будет отсутствовать. 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 не станет null или не будет отсутствовать, и пропускайте поток, у которого usage равен null. Если вместо этого сложить list_cost потоков, итог не будет включать время выполнения сессии, а каждое значение округляется отдельно.
• При достижении бюджета: Каждый открытый запуск приостанавливается, и сессия сообщает idle с budget_reached или requires_action, если также ожидает вызов инструмента. Каждый поток завершает уже начатый запрос к модели, поэтому запуск может превысить бюджет на один запрос для каждого работающего потока. Повышение или удаление бюджета возобновляет приостановленные им запуски, если только их не приостановило ещё и прерывание. Если использование сессии включает модель без прейскурантной цены, это делает только удаление бюджета; см. Модели без прейскурантной цены.

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

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

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

Работа запуска засчитывается в «rate limits» (ограничения скорости), которые уже есть у вашей организации.

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

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

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

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