Минимальный рабочий пример Crew AI

# если пользуешься uv
uv tool install crewai

# или классика
python -m venv .venv
source .venv/bin/activate  # (Windows: .venv\Scripts\activate)
pip install crewai

# file: main.py
from crewai import Agent, Task, Crew, Process, LLM


def run():
    llm = LLM(model="ollama/gemma3:latest",     base_url="http://localhost:11434")

    TOPIC = "локальные LLM: как выбрать между Ollama, vLLM и LM Studio (для новичков)"

    writer = Agent(
        role="Writer",
        goal="Писать краткие, технически точные посты для Telegram",
        backstory="""Ты технический автор и разработчик. 
Пишешь коротко, без воды, даёшь минимально достаточный код/аргументы.""",
        verbose=True,
        llm=llm,
    )

    task = Task(
        description=f"Сделай пост для Telegram на тему: {TOPIC}",
        expected_output="""Структурированный пост до 2500 символов, с TL;DR (3 буллета), и коротким выводом. Без упоминания CrewAI.""",
        agent=writer,
    )

    crew = Crew(agents=[writer], tasks=[task])
    print(crew.kickoff())

Запуск

uv run crewai run

#crewai

Частые ошибки новичков в CrewAI

✔️ Не привязали Task к Agent → ValidationError. Всегда указывай agent в задаче или в YAML.

✔️ Неописанный backstory.

✔️ Смешивают промпт задачи в агенте. Роль и цель → в Agent; что сделать → в Task.

✔️ Нет expected_output. Формализуй формат результата (форма, длина, ключевые секции).

✔️ Процесс не указан, поведение неочевидно. Явно ставь process=Process.sequential (или другой), чтобы было ясно, как исполняются задачи.

#crewai

Агенты ищут в интернете, анализируют и пишут статьи.

В видеоредакторе Filmora 14.8 появилась поддержка генерации видео в Veo 3.

Смотреть пример на YouTube

#veo3 #filmora #tools

Часть 2. Архитектура CrewAI: Agent, Task, Crew, Process

Зачем вообще разбирать архитектуру
Если не разделить роли и зоны ответственности, вы получаете "одного большого промпт-монстра", который сложно поддерживать, тестировать, масштабировать и объяснять заказчику. CrewAI вводит четыре базовые сущности: Agent, Task, Crew, Process и вся магия начинается только тогда, когда вы начинаете мыслить ими как отдельными блоками.

🔸 Agent тот, кто делает работу. Роль с целью, предысторией, инструментами и тоном. Это персонаж, которого можно многократно переиспользовать.

🔸 Task то, что именно сейчас нужно сделать. Конкретное задание для конкретного агента, с чётким форматом ожидаемого результата.

🔸 Crew это оркестратор. Он собирает агентов и задачи в один рабочий процесс.

🔸 Process это стратегия исполнения задач. Например, по порядку (sequential) или с менеджментом иерархии (hierarchical).


Представьте продакшн команду
🔹 Agent = роль: автор, редактор, аналитик, менеджер, исполнитель.

🔹 Task = поручение: “написать драфт”, “проверить факты”, “сделать итоговый отчёт”.

🔹 Crew = команда проекта: вы собрали нужные роли и расписали, кто что делает.

🔹 Process = регламент: идём строго по шагам или менеджер сначала строит план, а потом раздаёт задачи.

#crewai

Что обязательно должно быть у Agent
Role это короткое имя роли (Writer, Critic, Manager…).
Goal это зачем роль существует, какой результат она должна обеспечивать в принципе.
Backstory это контекст, стиль, ограничения, принципы.
Tools (если есть) — чем агент может пользоваться: веб‑поиск, БД, RAG, Telegram Bot API и т.п.
Модель какая LLM стоит за агентом (локальная/облачная и т.д.).

Важно: Агент не описывает конкретную текущую задачу, он описывает поведение роли в целом.


Что обязательно должно быть у Task
Description это то, что именно нужно сделать сейчас, конкретно.
Expected output это формат результата: длина, структура, стиль, ограничения, файл и т.д.
Agent это тот, кто выполняет задачу.
Сontext (опционально) на каких данных/предыдущих шагах основана эта задача.

Важно: отсутствие expected_output почти гарантирует расплывчатый результат.


Crew отвечает за то, чтобы:
🔸 собрать набор агентов и задач,
🔸 определить process (как они будут исполняться),
🔸 запустить их в нужной последовательности,
🔸 обеспечивать передачу контекста между задачами, если задано процессом/конфигурацией.


Process
Sequential (последовательный) простая линейная цепочка шагов. Хорош, когда план заранее понятен, и нам просто нужно пройти от А до Я. Дешевле в настройке, легче объяснить.

Когда выбирать: есть чёткий pipeline: Writer → Critic → Publisher.


Hierarchical (иерархический) есть агент (часто мanager), который планирует и распределяет работу.
Подходит, когда задачи не определены заранее, их нужно сформулировать, разбить и контролировать. Сложнее, но даёт гибкость.

Когда выбирать: задача расплывчата (сделать продуктовое исследование) и вам нужен планировщик.


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

#crewai

Часть 3. Инструменты (tool) для агентов

Что такое tool в контексте агентной системы
Под инструментом будем понимать описанную и ограниченную способность агента вызывать внешний мир. Это может быть веб поиск, обращение в БД, RAG, отправка сообщения в Telegram, получение расшифровки видео и т.д.

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


Работа с файлами и локальными данными
Базовые операции чтение/запись фалов. Поверх них идут специализированные RAG: PDF/DOCX/JSON/CSV/XML/MDX/TXT.

Для навигации по проекту есть DirectoryReadTool облегчает чтение и обработку структур каталогов, и их содержимого. DirectorySearchTool инструмент RAG для поиска в каталогах, полезный для навигации по файловым системам.

Web Scraping и управление браузером
Для парсинга подойдёт ScrapeWebsiteToo, если нужны точечные элементы по CSS селектору, то ScrapeElementFromWebsiteTool.

Динамические сайты с JS отрабатывают через SeleniumScrapingTool. Для больших объёмов и обхода антибот доступны интеграции уровня Firecrawl и Scrapfly, есть и Spider быстрый краулер.

Когда требуется управлять облачными headless браузерами и сложными сценариями, пригодятся BrowserbaseLoadTool, HyperbrowserLoadTool и обёртка Stagehand для пошаговой автоматизации.

Поиск и исследование
Чтобы искать по всему интернету, используются: SerperDevTool, TavilySearchTool, EXASearchTool. Есть и приватный BraveSearchTool.

Для RAG внутри конкретных ресурсов предусмотрен WebsiteSearchTool, а также инструменты для YouTube (YoutubeVideoSearchTool) поиск по каналу и по видео с извлечением релевантных фрагментов.

Для инженерных задач полезны GithubSearchTool поиск по репозиториям и CodeDocsSearchTool поиск по документации SDK/библиотек.

SQL и векторные БД
Когда данные лежат в БД, пригодятся PGSearchTool и MySQLSearchTool. Для преобразования естественного языка в SQL запросы — NL2SQLTool.

Если речь о семантическом поиске по embedding, есть интеграции с Weaviate и Qdrant.

RAG, интерпретатор кода, изображения и зрение
RagTool динамическая база знаний, наполняемая вашими источниками.

CodeInterpreterTool позволяет агентам CrewAI выполнять код Python, который они генерируют автономно. Эта функция особенно ценна, поскольку позволяет агентам создавать код, выполнять его, получать результаты и использовать эту информацию для принятия последующих решений и действий.

DallETool для генерации изображений в DALL‑E и Vision инструменты для извлечения текста с изображений.

MCP подключение внешних инструментов
CrewAI умеет использовать серверы по Model Context Protocol (MCP) как источники инструментов. Это открывает доступ к целым экосистемам действий, которые можно прикрепить к агенту практически без кода вокруг API.

Это не все возможности CrewAI, у фреймворка богатая библиотека инструментов. Также есть возможность писать свои инструменты.

#crewai

Часть 4. Память, контекст и рассуждение в CrewAI

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

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

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

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

Настройка памяти
В CrewAI память включается непосредственно при создании Crew и автоматически включает три уровня:
🔸 Short‑Term Memory, в рамках одного запуска
🔸 Long‑Term Memory, персистентная база SQLite по умолчанию
🔸 Entity Memory, структура фактов о сущностях с RAG

Пример:

crew = Crew(
    agents=[writer, critic],
    tasks=[...],
    process=Process.sequential,
    memory=True,# включает все уровни памяти
    verbose=True
)

По умолчанию используются локальные хранилища ChromaDB для short-term, SQLite для long-term. Можно переопределить путь через CREWAI_STORAGE_DIR или подключить свой LongTermMemory/ShortTermMemory.

Рассуждение
С включённым параметром reasoning, агент заранее оценивает задачу, может построить внутренний план или критически переосмыслить само решение. Можно комбинировать с агентом критиком, который анализирует результат.

Пример:

agent = Agent(
    role="Writer",
    goal="...",
    backstory="...",
    reasoning=True,# включает рассуждение
    max_reasoning_attempts=2,# сколько попыток на анализ
    verbose=True
)

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


Как это работает
memory=True сохраняет результаты задач, промежуточные тексты, сущности и позволяет последующим task'ам / агентам учесть историю.

reasoning=True позволяет агенту сначала проанализировать задачу, возможно переопределить стратегию, прежде чем приступать к приведению результата.

Вместе они обеспечивают: цепочку контекста + возможность самопроверки и планирования.

Частые ошибки
Просто reasoning=True, но нет max_reasoning_attempts → агент может зациклиться на анализе.

Переопределён бекенд памяти вручную, но storage не сериализует нужные объекты → возможны ошибки.

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


#crewai

Часть 5. Flow в CrewAI и контроль сложных сценариев

CrewAI изначально строит агентные команды (Crews), но настоящий контроль достигается при помощи Flows — структурированных, событийно-управляемых сценариев исполнения. Это возможность вставлять условия, ветвления, параллели и динамическую маршрутизацию задач.

Flow позволяет:
🔸 запускать код, выполнять прямые запросы в LLM и запускать агентов внутри одного пайплайна

🔸 отслеживать состояние во время всего выполнения (state → state lifecycle)

🔸 реагировать на события и результаты предыдущих шагов через декораторы @start() и @listen(), включая and_(), or_() или @router() для условной маршрутизации

Flow запускается через CLI crewai flow kickoff. Состояние делают на основе словаря или Pydantic модели. Состояние автоматически сохраняется между этапами и может быть сохранено для долгосрочных сценариев.

Flow эффективен в задачах создания интерактивных ассистентов, реализации бизнес-логики, автоматизации техподдержки, генерации отчётов, публикаций и сценариев с участием человека.

Интеграция с Crews
Flow запускает Crews как шаги, передавая им параметры состояния, затем обрабатывает результаты.

Это позволяет: контролировать, какие агенты когда запускаются, проверять условия перед запуском Crew и управлять результатами сверху. Flow работает на уровне верхнего оркестра, а Crews на уровне агентской команды.

#crewai

Часть 6. Как писать goal и backstory для агентов в CrewAI

При создании агента в CrewAI две ключевые характеристики формируют его поведение и специализацию: goal (цель) и backstory (предыстория). Они используются при генерации системных промптов и напрямую влияют на эффективность агента в рамках задачи.

Что такое цель (goal)?
Цель это чёткое и краткое описание миссии агента. Оно должно быть конкретным и релевантным его роли.

✅ Пример правильной цели:
Собирать свежие новости IT и переписывать их в короткие публикации для Telegram канала.

❌ Плохая цель:
Работать с текстом.
(слишком общее и непонятно, что именно агент должен делать)

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

✅ Пример хорошего backstory:
Ты — опытный редактор, который работает в сфере технологий. Умеешь быстро находить суть в потоке информации, писать короткие, понятные и цепляющие тексты. Делаешь новости живыми и интересными.

❌ Плохой backstory:
Ты работаешь с информацией.
(недостаточно контекста и поведенческих указаний)


CrewAI автоматически добавляет системные инструкции поверх ваших goal и backstory, гарантируя, что ответ следует нужному формату и стилю. Поэтому важно, чтобы эти поля были дизайн ориентированы, а не литературные.

Рекомендации по созданию
Начните с ясной цели, что создаётся, кем, какое качество.

Затем сформируйте backstory, почему и как этот агент делает работу, какой у него тон, аудитория и ценности.

По возможности уточняйте роль агента: вместо обобщённого "Писатель" или "Иследователь" лучше использовать конкретные формулировки, например "Старший исследователь в области искусственного интеллекта".

#crewai

Часть 7. Как писать Task в CrewAI

Task это формализованное задание, которое включает не только описание действия, но и его контекст, ожидаемый результат и привязку к конкретному агенту. От того, насколько грамотно вы его сформулируете, зависит точность, воспроизводимость и надёжность всей системы.

Что включает Task
description это формулировка задания. Должна описывать, что именно агент должен сделать, и в каком виде должен быть результат. Не путайте с goal агента, description описывает конкретную задачу, а не общую роль.

expected_output это чёткое указание, как должен выглядеть результат. Это снижает галлюцинации модели и делает вывод предсказуемым. Можно указать формат: JSON, Markdown, список тезисов, статья и т.д.

В agent указываем агента, который будет выполнять задачу. Без этого Task в sequential режиме не выполнится.

Дополнительные параметры:
🔸 context=[...] — передаёт результат предыдущих Task.
🔸 tools=[...] — инструменты которыми может пользоваться агент.
🔸 output_json / output_pydantic — валидация результата по pydantic модели.
🔸 callback / guardrail — обработка результата или проверка качества перед следующими действиями.

Пример Task

Task(
  description="""Проанализируй текстовую расшифровку видео и выдели 3 наиболее интересных фрагмента длительностью от 5 до 60 секунд. Каждый фрагмент должен содержать: время начала, длительность и краткое описание того, чем он интересен.""",
  expected_output="JSON с полями start_time, duration, summary",
  agent=analyst_agent,
  context=[transcription_task],
  output_json=VideoFragmentList
)

Частые ошибки
Слишком общее задание: "Сделай анализ текста" - неясно, как именно анализировать, что считать результатом.

Несколько целей в одной таске: "Проанализируй текст, найди фрагменты и сделай нарезку" — разбейте на отдельные задачи.

В description не пишите общий контекст или цели, для этого есть goal, backstory, context.


Советы
🔸 Помните, каждый Task это единица логики, которую можно тестировать и переиспользовать.

🔸 Делайте Task атомарными: одна задача = один результат.

🔸 Не бойтесь быть конкретным. Чем точнее задание, тем лучше результат.

🔸 Для сложных систем пишите output с помощью pydantic.

#crewai

Тестирую qwen3:8b, полет нормальный.

А это работа с включенной памятью в CrewAI

Часть 8. Стратегии выбора: Crews, Flows или их комбинация

В CrewAI ключевым архитектурным решением является выбор между подходами: Crews, Flows или их комбинацией. Документация рекомендует делать выбор на основе оценки сложности (complexity) и точности (precision) вашей задачи.


Что такое complexity и precision
Complexity: отражает структуру задачи, сколько этапов, какие зависимости между ними, нужны ли ветвления, циклы, условная логика.

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

Комбинация этих показателей позволяет визуально спроектировать архитектуру с помощью матрицы "complexity vs precision".

📍 Четыре сценария и рекомендуемые стратегии и матрица использования CrewAI

🔹 Низкая сложность, низкая точность
Применяется в простых задачах, например, генерация идей, креативный текст. Ошибки не критичны.
Рекомендуется: простые Crews с минимальным набором агентов.

🔹 Низкая сложность, высокая точность
Требуется строго структурированный вывод (JSON, XML), повторяемость результатов, минимальный разброс.
Рекомендуется: Flows с прямыми вызовами LLM или простые Crews с обязательной структурированной валидацией.

🔹 Высокая сложность, низкая точность
Много этапов, несколько агентов, задач достаточно для сотрудничества. Качество может быть менее строго.
Рекомендуется: Crews с распределением ролей, исследователь, писатель, критик и пр.

🔹 Высокая сложность, высокая точность
Сложные пайплайны с жёсткими требованиями, регламентированными форматами, проверками ошибок.
Рекомендуется: Flows, которые оркестрируют работу нескольких Crews, с явной логикой ветвлений и валидаторами.

Как выбрать подходящую стратегию
Оцените complexity, сколько шагов? Есть ли ветвления? Нужна условная логика?

Оцените precision, насколько важна точность вывода? Нужна структура или вариативность?

Спроецируйте результаты на матрицу:
🔸 Low‑Low → Crew
🔸 Low‑High → проста Flow или сложные Crews
🔸 High‑Low → мультиагентные Crews
🔸 High‑High → Flows + Crews

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

#crewai

Практическая структура оценки при выборе стратегии в CrewAI

Чтобы определить правильный подход для вашего конкретного случая, следуйте этой пошаговой схеме оценки.
​
Шаг 1: Оцените сложность
Оцените сложность вашего приложения по шкале от 1 до 10, приняв во внимание:

1) Сколько различных операций (шагов) требуется?
- 1-3 шага: Низкая сложность (1-3)
- 4-7 шагов: Средняя сложность (4-7)
- 8+ шагов: Высокая сложность (8-10)

2) Насколько взаимосвязаны различные части?
- Мало зависимостей: низкая сложность (1-3)
- Некоторые зависимости: Средняя сложность (4-7)
- Множество сложных зависимостей: Высокая сложность (8-10)

3) Условная логика: сколько ветвлений и принятия решений необходимо?
- Линейный процесс: низкая сложность (1-3)
- Некоторое ветвление: Средняя сложность (4-7)
- Сложные деревья решений: Высокая сложность (8-10)

4) Знание предметной области: насколько специализированы требуемые знания?
- Общие знания: Низкая сложность (1-3)
- Некоторые специальные знания: Средняя сложность (4-7)
- Глубокие познания в различных областях: Высокая сложность (8-10)

Рассчитайте свой средний балл, чтобы определить общую сложность.
​
Шаг 2: Оценка требований к точности
Оцените ваши требования к точности по шкале от 1 до 10, приняв во внимание:

1) Насколько структурированным должен быть выходной сигнал?
- Текст свободной формы: низкая точность (1-3)
- Полуструктурированный: Средняя точность (4-7)
- Строго отформатировано (JSON, XML): Высокая точность (8-10)

2) Насколько важна фактическая точность?
- Творческий контент: Низкая точность (1-3)
- Информативность: Средняя точность (4-7)
- Критическая информация: Высокая точность (8-10)

3) Воспроизводимость: насколько последовательными должны быть результаты при разных запусках?
- Допустимое отклонение: низкая точность (1-3)
- Необходима некоторая последовательность: средняя точность (4-7)
- Требуется точная воспроизводимость: высокая точность (8-10)

4) Устойчивость к ошибкам: каково влияние ошибок?
- Низкое воздействие: Низкая точность (1-3)
- Умеренное воздействие: средняя точность (4-7)
- Высокая ударопрочность: высокая точность (8-10)

Рассчитайте средний балл, чтобы определить общие требования к точности.
​
Шаг 3: Сопоставьте с матрицей
Отобразите оценки сложности и точности на матрице:
▫️ Низкая сложность (1-4), низкая точность (1-4): простые crew
▫️ Низкая сложность (1–4), высокая точность (5–10): flow с прямыми вызовами LLM
▫️ Высокая сложность (5-10), низкая точность (1-4): сложные crew
▫️ Высокая сложность (5-10), высокая точность (5-10): flow, организующие crew
​
Шаг 4: Рассмотрите дополнительные факторы
Помимо сложности и точности, примите во внимание:

1) Время разработки: команды часто быстрее создают прототипы.

2) Потребности в обслуживании: Потоки обеспечивают лучшую долгосрочную ремонтопригодность.

3) Опыт команды: примите во внимание знакомство вашей команды с различными подходами.

4) Требования к масштабируемости: потоки обычно лучше масштабируются для сложных приложений.

5) Потребности интеграции: продумайте, как решение будет интегрироваться с существующими системами.


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

Источник

#crewai

Недавно решал одну задачу на CrewAI для стримера.

Суть задачи
Нужно собирать новости компьютерных игр на текущую дату. Формировать пост для телеграм и отправлять боту в ТГ. Посты всегда должны быть одного формата.
Нужны были не просто новости, а новые игры, dlc, патчи, обновления и только на платформу PC.

Так же одним из требований было, минимальные затраты на использование. Т.е. дешёвый сервер и дешёвый API LLM. Если с сервером проблем нет, то вот с LLM как бы есть.

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

Второй агент, на основе этих данных формирует пост для телеграм + хештеги.
После завершения задач, скрипт отправляет пост боту в ТГ.

Проблемы с которыми столкнулся
Иногда второй агент выдавал новости которых нет. Первым шагом скорректировал промпт, чтобы он основывался только на данных которые ему были переданы.

Вторая проблема, он выдавал часть новостей, которым пара лет. Эта проблема была решена с помощью доработки промпта и введением агента менеджера.

Использовать API хороших LLM нет возможности.
Было принято решение в бета версии использовать локальную LLM. По результатам тестов остановился на qwen3:8b. Выдает достойный результат и подходит под ресурсы ПК.

На результат работы можно посмотреть в Телеграм канале стримера.


#crewai

OpenAI представила GPT-OSS, новую открытую серию языковых моделей

Компания OpenAI официально анонсировала серию открытых языковых моделей под названием GPT-OSS (GPT Open-Source Series).

Модель представлена в двух вариантах: gpt-oss-20b и gpt-oss-120b, которые разработаны специально для задач рассуждения и агентских функций.

Особенностью GPT-OSS является лицензия Apache 2.0, что позволяет свободно использовать, модифицировать и распространять модель в коммерческих целях. Модели обучаются с использованием передовых методов предварительного и пост-обучения с особым акцентом на рассуждения и логические задачи.

Одно из преимуществ GPT-OSS это возможность запуска на обычном ноутбуке, но нужно 18-32 Гб ОЗУ.


Источник

#openai #gpt #gptoss

🚀 ChatGPT‑5

OpenAI анонсировала официальную презентацию GPT‑5 сегодня, в формате прямой трансляции в 20:00 по МСК. Логотип «LIVE5TREAM» намекает на запуск модели.

Предполагаемый релиз — в течение августа 2025, возможно, в середине или конце месяца.

Уже во внутренних тестах GPT‑5 продемонстрировала усилившиеся способности к решению задач (особенно в кодировании и логике), но прирост не такой впечатляющий, как при переходе от GPT‑3 к GPT‑4.

Что ожидаем от GPT‑5
Улучшенное рассуждение и агинские возможности: способность выполнять задачи без подробных инструкций, действуя как самостоятельный агент.

Поддержка мультимодальности: входы и выходы в текст, изображение, аудио, возможно и видео.

Источник

#chatgpt5