Гайд · TNWS AI

Как ветвить CrewAI Flow через @router

26 сентября 2026 4 мин—

Условный маршрут CrewAI Flow по status: @router возвращает approved или rejected, два listener, детерминированные тесты обеих веток.

Задача и применимость

Актуальный поисковый запрос: «как сделать условное ветвление CrewAI Flow router». Направить заявку в одну из двух явных веток по уже вычисленному статусу. @router(source_method) возвращает строку маршрута, а методы с @listen('route') реагируют на неё. Маршрут должен вычисляться доверенным кодом по проверенным данным; отдавать LLM право напрямую выбирать привилегированную ветку без валидации опасно. Материал сверён 26 сентября 2026 года с официальной документацией CrewAI 1.15.22. Примеры предназначены для Python 3.10+; закрепите версию пакета, потому что сигнатуры и поведение развиваются. Все коды, статусы и даты в примерах вымышлены.

Пошаговая настройка

Сохраните нормализованный статус в structured state.
После стартового шага вызовите router и верните одно из ограниченного множества имён.
Создайте отдельные listeners для approved и rejected.
Прогоните оба статуса и проверьте, что срабатывает только нужная ветка.

Перед запуском установите CrewAI по официальной инструкции. Для примеров с агентом задайте CREWAI_MODEL и учётные данные провайдера через переменные среды; доступность модели зависит от вашего аккаунта. Flow-примеры не требуют LLM и должны сначала проходить как детерминированные тесты. Не включайте действующие ключи и реальные клиентские данные в исходник или prompt.

Готовый шаблон

from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel

class RouteState(BaseModel):
    approved: bool = True

class ApprovalFlow(Flow[RouteState]):
    @start()
    def load(self):
        return self.state.approved

    @router(load)
    def choose(self):
        return "approved" if self.state.approved else "rejected"

    @listen("approved")
    def on_approved(self):
        return "APPROVED"

    @listen("rejected")
    def on_rejected(self):
        return "REJECTED"

assert ApprovalFlow().kickoff() == "APPROVED"

Конкретный вход и ожидаемый результат

При approved=True ожидается единственный финальный результат APPROVED; при False — REJECTED. Это маршрутизация, не реальное финансовое или юридическое одобрение. В боевой системе boolean должен формироваться проверенным правилом и аудитироваться. Не используйте свободный текст модели вроде «скорее одобрено» как имя маршрута.

Как фактически проверить

Запустите два экземпляра Flow с разными входными состояниями или inputs согласно вашей схеме. Введите счётчики в listeners и убедитесь, что ровно один увеличился. Добавьте защиту на неожиданный статус до router. В лог записывайте route и безопасный идентификатор решения, но не весь исходный документ.

Проверяйте не только итоговую строку, но и путь исполнения: входные данные, вызванный метод или Task, промежуточный результат и финальное преобразование. Успешный Python-процесс не доказывает правильность фактов LLM. Для агентных сценариев сделайте не менее трёх прогонов фиксированной модели и укажите долю прохождения критериев, а не выбирайте лучший ответ вручную.

Критерии приёмки

Python-код проходит синтаксическую проверку, а зависимости и версия зафиксированы.
Положительный пример даёт заранее описанный результат без новых фактов.
Отрицательный пример завершается явным отказом либо контролируемой веткой.
Ни один шаг не получает больше данных или полномочий, чем требуется задаче.
После обновления CrewAI или модели тот же набор выполняется повторно.

Протокол воспроизводимости

Сохраните дату, версию CrewAI, версию Python, идентификатор модели для agent-примеров и обезличенный вход. Для Flow зафиксируйте порядок событий и финальный state; для Task — TaskOutput, число попыток и результат guardrail. Не записывайте секреты, системные prompts и персональные данные без необходимости. Если ошибка плавающая, классифицируйте её как неверный маршрут, неверный аргумент, исключение Python или неподтверждённую генерацию — эти случаи исправляются по-разному.

Регрессионный набор

Не ограничивайтесь одним удачным примером. Добавьте стандартный вход, отсутствующее обязательное поле, похожий идентификатор, пустую строку и слишком длинное значение. Для каждого заранее укажите ожидаемое событие, состояние и финальный результат. В агентных задачах отдельно оценивайте правильность фактов и соблюдение формата; красивый текст не компенсирует неверный код. В Flow проверяйте, какой метод действительно вызван и сколько раз: одинаковая финальная строка может скрыть ошибочный маршрут. При изменении модели не переносите прежние показатели автоматически. При изменении схемы state предусмотрите миграцию сохранённых записей. Ошибка одного теста должна блокировать автоматическое внешнее действие, но не обязана останавливать независимые процессы системы. После исправления обязательно повторите весь набор, а не только упавший случай. Такой набор превращает статью в повторяемую инструкцию, а не в демонстрацию единственного счастливого пути.

Типичные ошибки и чего не делать

Не возвращайте произвольные строки, для которых нет listener.
Не используйте LLM-ответ как доверенное решение без детерминированной проверки.
Не выполняйте действие до завершения проверки маршрута.

Не увеличивайте retries, max_iter или таймаут после каждой ошибки автоматически. Ограничение останавливает цикл, но не исправляет отсутствующий факт или плохую схему. Не выполняйте платежи, удаление, публикацию и другие необратимые действия только на основании текста модели. Добавляйте детерминированную проверку и, где требуется, человеческое подтверждение.

FAQ

Что возвращает router?

Строку или значение маршрута, на которое подписан listener.

Можно ли иметь несколько веток?

Да, создайте отдельные имена и listeners.

Срабатывают ли обе ветки?

Для одного возвращённого маршрута должна выполняться соответствующая ветка.

Официальные источники

Частые вопросы

Что возвращает router?

Строку или значение маршрута, на которое подписан listener.

Можно ли иметь несколько веток?

Да, создайте отдельные имена и listeners.

Срабатывают ли обе ветки?

Для одного возвращённого маршрута должна выполняться соответствующая ветка.

Как ветвить CrewAI Flow через @router

Задача и применимость

Пошаговая настройка

Готовый шаблон

Конкретный вход и ожидаемый результат

Как фактически проверить

Критерии приёмки

Протокол воспроизводимости

Регрессионный набор

Типичные ошибки и чего не делать

FAQ

Что возвращает router?

Можно ли иметь несколько веток?

Срабатывают ли обе ветки?

Официальные источники

Частые вопросы

Читайте также

Как хранить данные в словарном state CrewAI Flow

Как объединить события CrewAI Flow через or_ и and_

Как передать результат одной задачи CrewAI в другую через context

Комментарии