CrewAI: команды ИИ-агентов, Flows и автоматизация на Python

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

Фреймворк полезен, когда одного запроса к модели уже мало. Например, заявка клиента требует свериться с базой знаний, определить ответственного и подготовить черновик ответа. CrewAI связывает эти действия в приложение. Интерфейс для клиента, авторизацию и подключение к рабочим данным вы создаёте отдельно.

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

• Разработчику на Python, который собирает ассистента с доступом к данным компании и хочет разделить обязанности между агентами.
• Вайбкодеру, который готов читать сгенерированные файлы, настраивать окружение и проверять поведение каждого шага.
• Команде автоматизации: описать повторяемый процесс, сохранить промежуточные данные и найти этап, на котором результат испортился.
• Для простого пересказа текста сначала достаточно одного вызова модели. Команда из нескольких агентов добавляет запросы, задержки и точки отказа.

Роль агента задаётся текстом, но работу инструментов определяет код. Если помощник должен читать заказ по его номеру, понадобится функция получения заказа и проверка доступа. Фраза «ты менеджер» сама по себе такого доступа не даёт.

Начните с процесса, в котором вход и результат легко сверить: например, из заметки о проблеме получить категорию обращения и черновик ответа. Добавлять поиск по интернету и запись в CRM лучше после того, как этот короткий путь работает предсказуемо. Так ошибку проще найти, а стоимость одного запуска проще посчитать.

Агент может выбирать инструменты в пределах своей задачи. Внешний Flow задаёт порядок крупных этапов: получить входные данные, запустить Crew, проверить результат, передать его дальше. Обычные Python-функции можно оставить для расчётов и проверок, которые не требуют модели.

Process.sequential выполняет задачи по очереди. В Process.hierarchical работой руководит менеджер: он распределяет задания и оценивает результат. Для иерархического режима требуется manager_llm или собственный manager_agent. Менеджер тоже обращается к модели, поэтому такой режим добавляет расходы.

В Task.context можно явно указать задачи, результат которых нужен следующему исполнителю. Это удобнее, чем рассчитывать, что длинная общая переписка донесёт всё необходимое. В описании задания укажите, какие сведения нужно использовать, а в expected_output задайте форму ответа.

CrewAI требует Python 3.10–3.13: Python 3.14 не входит в поддерживаемый диапазон. Для командной строки используется uv, инструмент управления Python-окружениями и пакетами. Установка CLI и зависимости конкретного проекта находятся в разных окружениях.

uv tool install crewai
crewai create crew support-crew
cd support_crew
crewai install

Генератор создаёт JSONC-проект: agents/*.jsonc хранит настройки агентов, crew.jsonc описывает задачи и команду, .env содержит ключи. JSONC похож на JSON, но допускает комментарии. Старый шаблон с crew.py и YAML можно получить через crewai create crew support-crew --classic. Выберите один вариант и следуйте его структуре.

На Windows при ошибке сборки зависимости с C++ могут понадобиться Visual Studio Build Tools с компонентом Desktop development with C++. Если команда не находится после установки, проверьте PATH; uv tool update-shell помогает настроить путь к CLI.

В созданном проекте замените роль и задачу на обработку обращения. Для первого запуска используйте тестовый текст без персональных данных. Настройте ключ провайдера в .env; имя модели выбирайте из доступных вашей учётной записи.

{
  "role": "Специалист поддержки",
  "goal": "Подготовить понятный черновик ответа по тексту обращения",
  "backstory": "Ты уточняешь проблему и не придумываешь правила компании.",
  "settings": {
    "allow_delegation": false,
    "max_iter": 6
  }
}

{
  "name": "Support draft",
  "agents": ["researcher"],
  "inputs": {"ticket": "После обновления приложение не открывается."},
  "tasks": [
    {
      "name": "draft_reply",
      "description": "Прочитай обращение: {ticket}. Напиши черновик ответа на русском. Не утверждай, что проблема решена.",
      "expected_output": "Краткое описание проблемы, один уточняющий вопрос и вежливый ответ.",
      "agent": "researcher"
    }
  ],
  "process": "sequential"
}

# В файле .env:
OPENAI_API_KEY=<ключ-провайдера>
MODEL=openai/<доступная-модель>

# В терминале из каталога проекта:
crewai run

Сверьте ответ с входным обращением. Если агент добавил обещание возврата денег или срок ремонта, которого вы ему не давали, исправьте инструкции и добавьте проверку результата. Успешное завершение команды означает, что процесс отработал; качество ответа оценивается отдельно.

Python API удобен для приложения, которое уже получает обращения из очереди или HTTP-запроса. Пример ниже использует одного автора и одного проверяющего. Он обрабатывает переданный текст и не обращается к CRM или поиску.

uv init crew-demo
cd crew-demo
uv add "crewai[openai]" python-dotenv

import os
from dotenv import load_dotenv
from crewai import Agent, Crew, LLM, Process, Task

load_dotenv()
llm = LLM(model=os.environ["MODEL"])
writer = Agent(
    role="Автор ответа", goal="Понятно ответить на обращение",
    backstory="Ты работаешь только с переданными фактами.",
    llm=llm, allow_delegation=False, max_iter=6,
)
reviewer = Agent(
    role="Проверяющий", goal="Убрать неподтверждённые обещания",
    backstory="Ты сверяешь ответ с исходным обращением.",
    llm=llm, allow_delegation=False, max_iter=6,
)
draft = Task(
    description="Составь ответ на русском по обращению: {ticket}",
    expected_output="Черновик ответа с уточняющим вопросом.", agent=writer,
)
check = Task(
    description="Сверь черновик с обращением {ticket}. Исправь придуманные факты.",
    expected_output="Исправленный ответ без неподтверждённых обещаний.",
    agent=reviewer, context=[draft],
)
result = Crew(
    agents=[writer, reviewer], tasks=[draft, check], process=Process.sequential,
).kickoff(inputs={"ticket": "После обновления приложение не открывается."})
print(result.raw)

Поместите MODEL и ключ в .env, затем выполните uv run python main.py. Контекст задачи check содержит результат draft. Проверяющий получает исходное обращение ещё раз, поэтому может сравнить его с ответом, а не оценивать только стиль.

Свободный текст удобен человеку, но программе нужны поля. Task.output_pydantic задаёт модель Pydantic, то есть схему с типами и проверками. output_json тоже принимает модель схемы. Структура помогает обработать результат без разбора произвольных абзацев.

from pydantic import BaseModel

class TicketResult(BaseModel):
    category: str
    reply_draft: str
    needs_human: bool

structured = Task(
    description="Разбери обращение: {ticket}. Определи категорию и предложи ответ.",
    expected_output="Поля category, reply_draft и needs_human.",
    agent=writer, output_pydantic=TicketResult,
)
result = Crew(agents=[writer], tasks=[structured]).kickoff(
    inputs={"ticket": "Прошу вернуть оплату за заказ."}
)
if result.pydantic is None:
    raise ValueError("Не получен результат нужной структуры")
print(result.pydantic.model_dump())

Схема проверяет типы полей. Для бизнес-правил нужны отдельные проверки: категория входит в разрешённый список, номер заказа существует, возврат действительно доступен. Флаг needs_human, предложенный моделью, не заменяет обязательное правило согласования в вашем приложении.

Инструмент даёт агенту конкретное действие: прочитать статус заказа, найти документ, вызвать API. Простую Python-функцию можно оформить декоратором @tool. Укажите типы аргументов и понятное описание: по ним модель понимает, когда вызывать функцию.

from crewai.tools import tool

@tool("Read order status")
def read_order_status(order_id: str) -> str:
    """Возвращает статус тестового заказа по его идентификатору."""
    statuses = {"DEMO-1": "В обработке", "DEMO-2": "Отправлен"}
    return statuses.get(order_id, "Заказ не найден")

# При создании Agent передайте tools=[read_order_status].

В реальной функции проверьте пользователя и его право читать заказ. Ошибки сети и отсутствие записи возвращайте явно. Для записи в систему лучше отдельный инструмент с ограниченным набором действий, чтобы агент не получал произвольный доступ ко всей базе.

Flow связывает методы Python через события. @start() отмечает начало, @listen() запускает шаг после другого шага, @router() выбирает маршрут. Состояние можно описать Pydantic-моделью. В нём хранятся входные данные, результат Crew и статус проверки.

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

class TicketState(BaseModel):
    ticket: str = ""
    length: int = 0

class TicketFlow(Flow[TicketState]):
    @start()
    def validate(self):
        if not self.state.ticket.strip():
            raise ValueError("Пустое обращение")
        self.state.length = len(self.state.ticket)

    @listen(validate)
    def finish(self):
        return {"length": self.state.length}

print(TicketFlow().kickoff(inputs={"ticket": "Не открывается приложение"}))

Декоратор @persist из crewai.flow.persistence сохраняет состояние; по умолчанию используется SQLite. Для восстановления нужен идентификатор сохранённого процесса. Хранение состояния и защита внешних действий решают разные задачи: повторная попытка шага не должна повторно списывать деньги или создавать одинаковые записи.

CrewAI подключает провайдеров через LLM. Для OpenAI, Anthropic, Gemini, Azure, Bedrock и Snowflake доступны нативные интеграции с соответствующими дополнительными зависимостями. Другие подключения используют LiteLLM; для них добавляют crewai[litellm]. У разных моделей отличается поддержка инструментов и структурированного ответа.

Для Ollama и совместимых локальных серверов настройте адрес и модель по инструкции подключения. Локальный Python-процесс сам по себе не означает, что данные остаются на компьютере: выбранный провайдер модели, поиск и инструменты могут отправлять их наружу.

Стоимость запуска складывается из всех обращений к модели, повторных попыток, поиска и дополнительных сервисов. Ограничьте max_iter, max_execution_time и max_rpm у агентов. Измеряйте расходы на законченную заявку: дешёвый отдельный ответ ещё не означает дешёвый процесс из нескольких этапов.

Memory хранит сведения, которые пригодятся в дальнейшей работе. В текущем API это единый класс: при сохранении модель помогает определить область, категории и значимость записи; поиск учитывает смысловую близость, давность и важность. Memory можно использовать отдельно, с Agent, Crew или внутри Flow.

from crewai import Memory

memory = Memory()
memory.remember("Для базы заказов выбрали PostgreSQL.")
for match in memory.recall("Где храним заказы?", limit=3):
    print(match.record.content)

Knowledge даёт агенту справочные материалы. Поддерживаются источники из строк и файлов; для файлов используется каталог knowledge. Этот слой полезен для регламентов и инструкций. Память о прошлых действиях и утверждённые документы лучше хранить раздельно, чтобы случайный вывод модели не превратился в правило компании.

RAG означает поиск подходящих фрагментов перед ответом модели. Для сложных PDF и сканов сначала подготовьте текст и структуру. Обзоры Docling и MinerU в блоке связанных материалов помогают выбрать обработчик документов. CrewAI управляет дальнейшими действиями агента, а качество исходного текста остаётся отдельной задачей.

MCP, Model Context Protocol, задаёт общий способ подключать инструменты внешних серверов к агенту. В CrewAI есть поле mcps для простых ссылок и структурированных конфигураций. Поддерживаются локальный транспорт stdio и сетевые HTTP/SSE-подключения; можно фильтровать доступные инструменты.

Подключение MCP-сервера добавляет возможности, которые этот сервер предоставляет. Проверьте список действий, способ авторизации и маршрут передачи данных. Для чтения базы знаний обычно достаточно поиска и получения документа; доступ на удаление записей такому помощнику не нужен.

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

Task.human_input позволяет запросить проверку человеком перед завершением задачи. Для собственного интерфейса и длительных процессов рассмотрите механизмы human-in-the-loop в Flow: место остановки и способ продолжения нужно связать с вашим приложением.

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

• Задайте обязательные поля результата и список разрешённых категорий.
• Перед записью в CRM проверьте права и наличие исходной записи.
• Действия, которые требуют согласования по правилам компании, останавливайте независимо от ответа модели.
• Сохраняйте причину отказа проверки, чтобы исправлять конкретный шаг.

Команда crewai test запускает Crew несколько раз и выводит показатели. Количество повторов задаётся через --n-iterations или -n; старый --n_iterations устарел. Оценивание тоже обращается к модели. Такие оценки удобно дополнять собственными проверками результата.

crewai test --n-iterations 3

Составьте небольшой набор обращений: обычное, неполное, с неизвестным номером заказа и с противоречивыми данными. Сравнивайте ответ с ожидаемыми фактами и фиксируйте стоимость. Для инструментов отдельно проверьте ошибку API и повторный вызов; это часто объясняет проблему лучше общей оценки текста.

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

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

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

CrewAI собирает техническую телеметрию использования. Согласно её описанию, по умолчанию промпты, ответы, ключи и данные задач в неё не включаются. share_crew расширяет состав отправляемых сведений. Трассировку AMP и собственные интеграции наблюдаемости настройте отдельно.

CREWAI_DISABLE_TELEMETRY=true

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

Код CrewAI распространяется по MIT. Его можно использовать, менять и включать в коммерческие приложения; при распространении сохраняются уведомление об авторских правах и текст лицензии. Гарантии работоспособности лицензия не предоставляет. У AMP, моделей и сторонних сервисов действуют собственные условия.

• Команда агентов не гарантирует верные факты. Ошибка первого шага может перейти в итоговый документ.
• Большой контекст, делегирование и повторные попытки увеличивают время и стоимость обработки.
• Сохранённое состояние не заменяет защиту внешних действий от повторного исполнения.
• Поддержка локальной модели зависит от её возможностей, особенно вызова инструментов.
• Ключи, разрешения и разделение данных пользователей остаются частью вашего приложения.

Для выбора соберите один и тот же короткий процесс: входная заявка, получение данных и проверенный черновик. Оцените, где понятнее хранится состояние, как перезапустить неудачный шаг и сколько кода требует интеграция. Подробные обзоры LangGraph и Microsoft Agent Framework открываются из таблицы альтернатив ниже.

• CrewAI на GitHub
• Официальный сайт CrewAI
• Документация CrewAI