Запуск собственного AI-агента перестал быть уделом исследовательских лабораторий. Фреймворк CrewAI позволяет собрать мультиагентную систему на Python за вечер, без необходимости писать низкоуровневый код взаимодействия с LLM. Но между чтением документации и рабочим результатом — несколько граблей, о которые спотыкаются почти все новички.
Этот материал — не пересказ репозитория, а практический маршрут: что устанавливать, как проектировать роли, где искать ошибки и когда CrewAI вообще не нужен.
Что такое CrewAI и зачем он нужен
CrewAI — это фреймворк для оркестрации нескольких AI-агентов, каждый из которых выполняет свою роль и может делегировать задачи другим. В отличие от цепочек вызовов одной модели, здесь агенты обмениваются контекстом, перепроверяют результаты и работают параллельно.
На практике это выглядит так: один агент собирает данные, второй их анализирует, третий пишет отчёт, четвёртый проверяет факты. Вся координация — через CrewAI, без ручного переноса данных между вызовами API.
Установка и первая настройка
CrewAI ставится через pip. Потребуется Python 3.10 или новее.
pip install crewai
Фреймворк поддерживает OpenAI, Anthropic, Google Gemini, Groq и локальные модели через Ollama. Для первого запуска проще всего использовать OpenAI — ключ задаётся через переменную окружения.
python
import os
os.environ[“OPENAI_API_KEY”] = “sk-…”
Если работаете с локальной моделью через Ollama, потребуется дополнительная настройка эндпоинта. CrewAI ожидает OpenAI-совместимый API, так что для Ollama нужно указать базовый URL.
Проектирование агентов: роли, цели и бэкстори
Каждый агент в CrewAI — это объект с тремя обязательными полями: роль, цель и бэкстори. Ошибка новичков — делать их общими. Если написать «агент-помощник» и «помогать пользователю», система будет выдавать расплывчатые результаты.
Пример рабочей конфигурации для агента-исследователя:
python
researcher = Agent(
role=”Сборщик данных о технологиях”,
goal=”Найти три последних релиза AI-инструментов и извлечь ключевые характеристики”,
backstory=”Ты аналитик, который ежедневно просматривает GitHub, Hacker News и arXiv. Ты краток, используешь только проверенные источники.”,
verbose=True,
allow_delegation=False
)
Ключевые моменты: бэкстори задаёт стиль и ограничения, allow_delegation=False на первом этапе — чтобы агент не пытался переложить задачу на другого, если тот ещё не настроен.
Задачи и ожидаемый результат
Задача — это описание того, что должен сделать агент, и формат, в котором нужно вернуть результат. CrewAI использует шаблонизацию: в описании задачи можно ссылаться на контекст других задач.
python
task1 = Task(
description=”Найди последние статьи на arXiv по теме ‘agentic workflows’ за последнюю неделю. Верни список из 5 ссылок с кратким описанием.”,
expected_output=”Маркированный список: название, ссылка, 1-2 предложения сути”,
agent=researcher
)
Поле expected_output часто игнорируют, и зря. Без него модель возвращает многословный текст в произвольном формате, который следующий агент не сможет распарсить.
Сборка команды и запуск
Crew объединяет агентов и задачи. Простейший вариант — последовательное выполнение:
python
crew = Crew(
agents=[researcher, writer, validator],
tasks=[task1, task2, task3],
verbose=True
)
result = crew.kickoff()
Флаг verbose=True на этапе отладки обязателен — CrewAI выводит, что каждый агент «думает» и какие инструменты использует. Без этого вы будете гадать, почему результат пустой.
Типичные ошибки и как их обойти
Плохой промпт агента. Если агент пишет «я не могу выполнить задачу», значит, его роль или цель сформулированы неконкретно. Добавьте в бэкстори примеры успешных действий.
Отсутствие инструментов. Агент без доступа к поиску или чтению файлов может только генерировать текст. Для сбора данных из интернета нужен инструмент типа SerperDevTool или DuckDuckGoSearchTool.
Слишком длинные цепочки. Пять агентов подряд, каждый из которых ждёт результат предыдущего, работают медленно и дорого. CrewAI поддерживает параллельное выполнение независимых задач, но его нужно явно включать.
Игнорирование лимитов токенов. Если агент обрабатывает большой документ, контекстное окно может переполниться. Решение: разбивать задачи и передавать только релевантные фрагменты.
Сравнение CrewAI с альтернативами
| Фреймворк | Язык | Сложность | Параллельные агенты | Локальные модели |
|---|---|---|---|---|
| CrewAI | Python | Средняя | Да | Через Ollama |
| LangChain | Python | Высокая | Через LCEL | Да |
| AutoGen | Python | Средняя | Да | Да |
| Swarm (OpenAI) | Python | Низкая | Нет | Нет |
| Semantic Kernel | C#/Python | Средняя | Да | Да |
CrewAI выигрывает у LangChain простотой старта, но уступает в гибкости. Swarm от OpenAI проще, но не поддерживает локальные модели и параллельное выполнение.
Когда CrewAI не нужен
Если ваша задача — один вызов LLM с промптом, фреймворк избыточен. Если вам нужно обработать 10 000 документов последовательно — лучше написать скрипт на asyncio без оркестрации агентов.
CrewAI оправдан, когда есть несколько ролей с разными инструкциями, нужна передача контекста между шагами и потенциальное ветвление сценариев.
Практический следующий шаг
Откройте документацию CrewAI в разделе «Examples» — там есть готовые проекты для исследования рынка, написания статей и анализа данных. Возьмите один, замените API-ключ и посмотрите, как агенты взаимодействуют в логах. Это даст больше понимания, чем месяц чтения теории.
Ограничение: CrewAI активно развивается, и API меняется. Если гайд из интернета старше трёх месяцев, проверьте совместимость версий. На момент публикации актуальна версия 0.30+, где изменился механизм передачи контекста между задачами.