Как использовать CrewAI для командной работы агентов

После выполнения инструкции у вас будет локальный проект CrewAI с несколькими агентами, которые работают как команда: либо по очереди, либо через менеджера. Вы создадите актуальный scaffold, установите зависимости, запустите crew и проверите результат по логам и выходному файлу.

• ⏱️ Время: 25–40 минут
• 🎯 Сложность: средний
• 💰 Стоимость: пакет CrewAI open-source; расходы на LLM, поиск, MCP и другие внешние сервисы оплачиваются отдельно
• 🛠️ Что потребуется: Python 3.10–3.13, установленный uv, доступ к терминалу, редактор кода, переменные окружения для выбранного провайдера модели
• 📌 Актуальная версия: CrewAI 1.15.16 на дату 2026-08-19; текущая документация — v1.15.16

Практический вердикт: если вы только начинаете строить команду агентов, стартуйте с JSON-first scaffold и процесса sequential. Режим hierarchical имеет смысл, когда вам действительно нужен менеджер, который распределяет задачи и валидирует результаты делегирования.

Редакционное ограничение: в официальных материалах есть расхождение между текущими docs и более старыми примерами из README. Ниже я опираюсь на docs v1.15.16 с командами crewai create crew, crewai install и crewai run; флаг --classic используйте только если вам осознанно нужен старый YAML/Python-формат.

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

1. Установите CLI CrewAI.

   На актуальной странице Installation официальный способ установки указан через uv. Если CLI уже установлен, там же предлагается команда обновления.

   uv tool install crewai
   uv tool list
   # при необходимости обновление
   uv tool install crewai --upgrade

   Ожидаемый результат: в выводе uv tool list отображается установленный crewai.

2. Создайте новый проект crew в актуальном формате.

   Для новых проектов текущая документация использует JSON-first scaffold. Создайте отдельную папку команды одной командой.

   crewai create crew market_research_team

   По docs CLI создаёт структуру с agents/*.jsonc, crew.jsonc, .env, а также каталогами knowledge/, skills/ и tools/. Если вам нужен старый формат, используйте --classic, но не смешивайте оба подхода в одном проекте.

   Ожидаемый результат: у вас есть новая папка проекта с файлами конфигурации crew и агентов.

3. Выберите модель координации команды.

   Откройте сгенерированную конфигурацию проекта и определите один процесс: sequential или hierarchical. В первом случае задачи идут в фиксированном порядке; во втором менеджер распределяет работу и проверяет, что делегирование дало приемлемый результат.

   Для первого внедрения обычно достаточно sequential. Если ваша команда должна сама перераспределять исследование, написание и проверку, переходите на hierarchical.

   Ограничение источников: в переданном source pack нет полного пофайлового листинга JSONC-шаблона, поэтому я не привожу выдуманные имена полей. Используйте тот формат process-настройки, который показывает ваш сгенерированный scaffold и docs v1.15.16.

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

4. Назначьте каждой задаче конкретного агента.

   В созданных файлах агентов задайте роли участников команды, а в конфигурации crew свяжите задачи с конкретными исполнителями. Для sequential это критично: официальная документация прямо указывает, что каждая Task должна иметь назначенного agent.

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

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

5. Заполните .env для выбранной модели и инструментов.

   Официальный quickstart опирается на переменные окружения перед запуском. Внесите в .env ключи и параметры того LLM-провайдера и внешних сервисов, которые вы реально используете в проекте.

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

   Ожидаемый результат: файл .env заполнен, и вы понимаете, какие внешние сервисы участвуют в выполнении crew.

6. Установите зависимости проекта.

   После заполнения окружения выполните установку внутри папки проекта. Именно такая последовательность — сначала crewai install, затем запуск — указана в quickstart.

   crewai install

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

7. Запустите crew и получите результат.

   Из корня проекта выполните основной запуск.

   crewai run

   Официальный quickstart предлагает проверять успех по логам выполнения и по файлу output/report.md. Если вы изменили путь output_file или выбрали классический scaffold, итоговый файл может лежать в другом месте — ориентируйтесь на свою текущую конфигурацию.

   Ожидаемый результат: вы видите логи выполнения crew и итоговый артефакт с результатом работы команды.

Как проверить, что всё работает

• CLI установлен: команда uv tool list показывает crewai.
• Проект создался в нужном формате: после crewai create crew ... у вас есть agents/*.jsonc, crew.jsonc, .env, knowledge/, skills/ и tools/.
• Зависимости установились: crewai install завершается без ошибок.
• Команда агентов реально исполнилась: после crewai run есть логи выполнения задач.
• Финальный результат сохранён: в quickstart это output/report.md; если путь изменён вашей конфигурацией, проверьте именно ваш файл вывода.
• Координация соответствует выбранному процессу: при sequential задачи идут по очереди, при hierarchical менеджер делегирует и валидирует. Точная формулировка логов может отличаться от примеров в старом README.

Частые ошибки и исправления

• ❌ Ошибка: проект не запускается из-за версии Python.
  ✅ Решение: проверьте, что у вас Python не ниже 3.10 и ниже 3.14. По данным PyPI, пакет требует >=3.10 и <3.14.
• ❌ Ошибка: после установки команда crewai не находится.
  ✅ Решение: повторно выполните uv tool install crewai и проверьте установку через uv tool list. Если вы давно ставили CLI, обновите его командой uv tool install crewai --upgrade.
• ❌ Ошибка: вы открыли старый пример из README, а локальный проект создан в JSON-first формате.
  ✅ Решение: не смешивайте current docs и classic scaffold. Для новых проектов ориентируйтесь на docs v1.15.16; флаг --classic используйте только осознанно.
• ❌ Ошибка: часть задач не исполняется или логика команды непредсказуема.
  ✅ Решение: убедитесь, что у каждой Task назначен конкретный agent. Для sequential process это прямое требование документации.
• ❌ Ошибка: вы подключили MCP-сервер и получили рискованный или неожиданный доступ к данным и системам.
  ✅ Решение: подключайте только доверенные MCP-серверы. Документация отдельно предупреждает, что MCP-сервер может выполнять код, получать доступ к данным и взаимодействовать с другими системами.

Безопасность и ограничения

• MCP — это граница доверия. CrewAI умеет подключать внешние MCP-серверы как tools, но официальная security-документация советует доверять только проверенным серверам.
• Поддерживаются только tools MCP-сервера. В официальном MCP-разделе отдельно сказано, что prompts и resources не поддерживаются как часть этой интеграции.
• Базовый пакет бесплатный, но не бесплатна вся система. Сам CrewAI — open-source пакет, однако модели, поиск, MCP и другие внешние сервисы оплачиваются отдельно у соответствующих провайдеров.
• Порог входа технический. Для локального использования вам нужен Python 3.10–3.13 и рабочее окружение с uv.
• Документация неоднородна. Current docs уже ориентируются на JSON-first scaffold, а в репозитории всё ещё встречаются классические примеры. Перед фиксацией шаблона в проекте сверяйте именно docs v1.15.16 и текущий релиз на PyPI.
• Проверка результата зависит от вашей конфигурации. В quickstart фигурирует output/report.md, но при изменённом output_file или classic scaffold путь к артефакту будет другим.

Что делать дальше

• Если хотите удобнее править конфигурации и Python-код команды, посмотрите как использовать Cursor для автодополнения кода.
• Если вам ближе AI-IDE с акцентом на разработку, пригодится как использовать Windsurf (Codeium) для разработки.
• Если планируете давать агентам больше прав на запуск инструментов, сначала разберите, что такое sandbox для агентов.
• Если следующая задача вашей команды — проверка изменений в коде, откройте инструкцию как использовать ИИ для код-ревью.

Источники

• crewAI/lib/crewai-tools/README.md at main · crewAIInc/crewAI · GitHub

• crewai · PyPI
• Installation – CrewAI
• Quickstart – CrewAI
• Sequential Processes – CrewAI
• Hierarchical Process – CrewAI
• Using Annotations in crew.py – CrewAI
• MCP Servers as Tools in CrewAI – CrewAI
• MCP Security Considerations – CrewAI
• crewAI/README.md at main · crewAIInc/crewAI · GitHub

Вопросы и ответы

Можно ли использовать CrewAI без CrewAI AMP?

Да. Эта инструкция построена вокруг open-source пакета CrewAI из PyPI и официальных docs по локальной установке и запуску. Для первого проекта AMP не требуется.

Что выбрать для первой команды: sequential или hierarchical?

Начните с sequential, если у вас линейный рабочий процесс. Переходите на hierarchical, когда нужен менеджер, который делегирует задачи и валидирует результат.

Можно ли использовать старый YAML/Python-шаблон?

Да, для этого у crewai create crew есть флаг --classic. Но current docs используют JSON-first scaffold, поэтому для новых проектов логичнее начинать именно с него.

Поддерживает ли CrewAI все возможности MCP-сервера?

Нет. В официальной документации по MCP указано, что CrewAI использует MCP-серверы как tools. Prompts и resources в этой интеграции не поддерживаются.

Что делать, если после запуска нет файла output/report.md?

Сначала проверьте логи выполнения. В quickstart именно output/report.md служит ориентиром, но в вашем проекте путь может отличаться, если вы изменили output_file или используете classic scaffold.