# Многоагентный фреймворк CrewAI

## Обзор

[CrewAI](https://github.com/crewAIInc/crewAI) это передовая платформа для оркестровки **автономных ИИ-агентов, исполняющих роли**, с **44K+ звёздами на GitHub**. В отличие от систем с одним агентом, CrewAI позволяет вам определять специализированных агентов (исследователь, писатель, кодер, аналитик ...) которые сотрудничают как «экипаж» для выполнения сложных задач — каждый агент с собственной ролью, целью, предысторией и набором инструментов.

На **Clore.ai**, CrewAI может быть развернут в контейнере Docker всего за **$0.05–0.20/час**. Хотя сам CrewAI загружает CPU (он оркестрирует вызовы API), сочетание его с локальным сервером Ollama или vLLM на том же GPU-узле даёт полностью приватную, работающую офлайн многоагентную систему.

**Ключевые возможности:**

* 👥 **Многоагентные экипажи** — определяйте персоны агентов с ролями, целями и предысториями
* 🎯 **Делегирование задач** — агент-менеджер автоматически назначает задачи подходящему специалисту
* 🛠️ **Экосистема инструментов** — веб-поиск, ввод/вывод файлов, выполнение кода, доступ к БД, пользовательские инструменты
* 🔁 **Последовательное и параллельное** — выполняйте задачи по порядку или запускайте независимые задачи одновременно
* 🧠 **Память агентов** — типы памяти: кратковременная, долгосрочная, по сущностям и контекстная
* 🔌 **Независимость от LLM** — работает с OpenAI, Anthropic, Google, Ollama, Groq, Azure и другими
* 📊 **CrewAI Studio** — визуальный интерфейс для создания экипажей без кода (для корпоративных клиентов)
* 🚀 **Конвейеры** — связывайте несколько экипажей для сложных многоступенчатых рабочих процессов

***

## Требования

CrewAI — библиотека на Python. Она работает на CPU и требует только системного Python 3.10+ или Docker. GPU опционален, но открывает мощный локальный вывод моделей.

| Конфигурация                           | GPU              | VRAM  | ОЗУ системы | Диск   | Clore.ai Цена     |
| -------------------------------------- | ---------------- | ----- | ----------- | ------ | ----------------- |
| **Минимальная** (облачные API)         | Нет / только CPU | —     | 2 GB        | 10 ГБ  | \~$0.03/час (CPU) |
| **Стандартный**                        | Нет / только CPU | —     | 4 ГБ        | 20 ГБ  | \~$0.05/час       |
| **+ Локальная LLM (маленькая)**        | RTX 3080         | 10 ГБ | 8 ГБ        | 40 ГБ  | \~$0.15/час       |
| **+ Локальная LLM (большая)**          | RTX 3090 / 4090  | 24 ГБ | 16 ГБ       | 60 ГБ  | $0.20–0.35/час    |
| **+ Высококачественная локальная LLM** | A100 40 GB       | 40 ГБ | 32 ГБ       | 100 ГБ | \~$0.80/час       |

### API-ключи

CrewAI работает с большинством основных поставщиков LLM. Вам нужен как минимум один:

* **OpenAI** — GPT-4o (лучшее рассуждение для сложных задач)
* **Anthropic** — Claude 3.5 Sonnet (отлично подходит для экипажей, ориентированных на написание)
* **Groq** — Бесплатный уровень, быстрая выдача (Llama 3 70B)
* **Ollama** — Полностью локально, ключ API не требуется (см. [Ускорение с помощью GPU](#gpu-acceleration))

***

## Быстрый старт

### 1. Арендуйте сервер Clore.ai

Войдите в систему в [clore.ai](https://clore.ai):

* **Только CPU** если используете облачные LLM API
* **RTX 3090/4090** для локального вывода Ollama
* SSH доступ включён
* Нет особых требований к портам для использования CLI (открывайте порты только для веб-интерфейсов)

### 2. Подключитесь и подготовьтесь

```bash
ssh root@<clore-server-ip> -p <ssh-port>

# Обновите систему
apt-get update && apt-get upgrade -y

# Установите Python 3.11 (если отсутствует)
apt-get install -y python3.11 python3.11-venv python3-pip
python3 --version   # Должен быть 3.10+

# Проверьте Docker
docker --version
```

### 3. Вариант A — прямая установка через pip (быстрее всего)

```bash
# Создайте виртуальное окружение
python3 -m venv crewai-env
source crewai-env/bin/activate

# Установите CrewAI со всеми инструментами
pip install crewai crewai-tools

# Проверить установку
python -c "import crewai; print(crewai.__version__)"
crewai --version
```

### 4. Вариант B — контейнер Docker (рекомендуется для воспроизводимости)

```bash
# Создайте директорию проекта
mkdir my-crew && cd my-crew

# Запишите Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.11-slim

# Установите системные зависимости
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Установите рабочую директорию
WORKDIR /app

# Установите CrewAI и распространённые инструменты
RUN pip install --no-cache-dir \
    crewai \
    crewai-tools \
    langchain-openai \
    langchain-anthropic \
    python-dotenv

# Скопируйте код приложения
COPY . .

# Команда по умолчанию
CMD ["python", "main.py"]
EOF

# Постройте образ
docker build -t my-crewai-app .
```

### 5. Создайте ваш первый экипаж

```bash
# Инициализируйте новый проект CrewAI с помощью CLI
source crewai-env/bin/activate
crewai create crew my-research-crew
cd my-research-crew

# Настройте API-ключи
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
# Или для Anthropic:
# ANTHROPIC_API_KEY=sk-ant-...
# Или для Ollama (ключ не требуется):
# OPENAI_API_BASE=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
EOF

# Установите зависимости проекта
crewai install

# Запустите экипаж
crewai run
```

***

## Конфигурация

### Структура проекта (из `crewai create`)

```
my-research-crew/
├── .env                    # API-ключи и настройки
├── pyproject.toml          # Зависимости
├── src/
│   └── my_research_crew/
│       ├── config/
│       │   ├── agents.yaml   # Определения агентов
│       │   └── tasks.yaml    # Определения задач
│       ├── tools/
│       │   └── custom_tool.py  # Ваши пользовательские инструменты
│       ├── crew.py           # Сборка экипажа
│       └── main.py           # Точка входа
```

### agents.yaml — Определите ваших агентов

```yaml
researcher:
  role: >
    Старший исследователь-аналитик
  goal: >
    Выявлять передовые разработки в области {topic} и синтезировать практические выводы
  backstory: >
    Вы эксперт-исследователь с талантом находить и связывать информацию
    из разнообразных источников. У вас острый взгляд на достоверность и релевантность.
  tools:
    - SerperDevTool
    - ScrapeWebsiteTool
  llm: gpt-4o                # Можно задавать для каждого агента отдельно
  verbose: true
  max_iter: 15               # Максимум итераций рассуждений
  memory: true               # Включить память агента

writer:
  role: >
    Эксперт по техническому письму
  goal: >
    Преобразуйте сложные исследования в понятный, убедительный и точный контент
  backstory: >
    Вы составляете объяснения, которые делают сложные темы доступными без потери глубины.
    Вы цитируете источники и структурируете контент для максимальной читаемости.
  llm: claude-3-5-sonnet-20241022
  verbose: true
```

### tasks.yaml — Определите задачи

```yaml
research_task:
  description: >
    Исследуйте последние события в теме {topic} за последние 6 месяцев.
    Определите ключевые тренды, прорывы и их последствия.
    Соберите не менее 10 достоверных источников.
  expected_output: >
    Подробный исследовательский отчёт с выводами, организованными по темам,
    включая URL источников и даты публикаций.
  agent: researcher

writing_task:
  description: >
    Используя исследовательский отчёт, напишите полноценный блог-пост о {topic}.
    Целевая длина: 1500–2000 слов. Включите заголовок, введение, основные разделы,
    и заключение с прогнозом на будущее.
  expected_output: >
    Готовый к публикации блог-пост в формате Markdown.
  agent: writer
  context:
    - research_task    # Задача письма получает вывод исследователя
  output_file: output/blog_post.md
```

### crew\.py — Сборка экипажа

```python
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

@CrewBase
class MyResearchCrew():
    """Экипаж для исследований и написания"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            tools=[SerperDevTool(), ScrapeWebsiteTool()],
            verbose=True
        )

    @agent
    def writer(self) -> Agent:
        return Agent(
            config=self.agents_config['writer'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def writing_task(self) -> Task:
        return Task(
            config=self.tasks_config['writing_task'],
            output_file='output/blog_post.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,  # или Process.hierarchical
            verbose=True,
            memory=True,
            max_rpm=10   # Ограничение частоты вызовов API
        )
```

### Запуск с Docker Compose (с Ollama)

```yaml
# docker-compose.yml
version: "3.8"

services:
  crewai:
    build: .
    volumes:
      - ./src:/app/src
      - ./output:/app/output
    environment:
      - OPENAI_API_BASE=http://ollama:11434/v1
      - OPENAI_API_KEY=ollama
      - OPENAI_MODEL_NAME=llama3.1:70b
      - SERPER_API_KEY=${SERPER_API_KEY}
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:
```

```bash
# Запустите стек
docker compose up -d ollama

# Загрузите вашу модель
docker compose exec ollama ollama pull llama3.1:70b

# Запустите ваш экипаж
docker compose run --rm crewai python src/my_research_crew/main.py
```

***

## Ускорение с помощью GPU

Сам CrewAI не использует GPU — но использует LLM, к которой обращается. Запустите Ollama или vLLM на том же сервере Clore для ускоренного локального вывода на GPU.

### Настройка Ollama (рекомендуется для простоты)

```bash
# Установите Ollama на хосте
curl -fsSL https://ollama.com/install.sh | sh

# Проверьте обнаружение GPU
nvidia-smi
ollama run llama3:8b "Test"   # Должен использовать GPU

# Загрузите модели для различных потребностей агентов
ollama pull llama3.1:8b          # Быстрое, лёгкое рассуждение
ollama pull llama3.1:70b         # Сложное рассуждение (требует A100+)
ollama pull codestral:latest     # Специализировано для код-агентов
ollama pull nomic-embed-text     # Для эмбеддингов памяти/RAG

# Настройте CrewAI на использование Ollama
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b
```

### Настройка LLM CrewAI для каждого агента

```python
from crewai import Agent, LLM

# Использовать Ollama для конкретного агента
local_llm = LLM(
    model="ollama/llama3.1:8b",
    base_url="http://localhost:11434"
)

# Использовать облачный API для другого агента (например, для сложных рассуждений)
cloud_llm = LLM(
    model="gpt-4o",
    api_key="sk-..."
)

researcher = Agent(
    role="Researcher",
    goal="Find information",
    backstory="Expert researcher",
    llm=local_llm    # Использует локальный GPU
)

strategist = Agent(
    role="Strategist",
    goal="Plan actions",
    backstory="Strategic thinker",
    llm=cloud_llm    # Использует облачный API
)
```

### Рекомендации по моделям для задач агентов

| Тип задачи               | Рекомендуемая модель | VRAM   | Примечания                   |
| ------------------------ | -------------------- | ------ | ---------------------------- |
| Исследования + веб-поиск | Llama 3.1 70B        | 40 ГБ  | Лучшее локальное рассуждение |
| Генерация кода           | Codestral 22B        | 13 GB  | Специализированная для кода  |
| Письмо                   | Llama 3.1 8B         | 6 GB   | Быстро, хорошее качество     |
| Сложная оркестрация      | GPT-4o (API)         | —      | Лучшее в целом               |
| Эмбеддинги/память        | nomic-embed-text     | < 1 ГБ | Требуется для памяти         |

> См. [Ollama на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/ollama.md) и [vLLM на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/vllm.md) для полных руководств по настройке вывода.

***

## Подсказки и лучшие практики

### Оптимизация затрат

```bash
# Отслеживайте расходы на API LLM с помощью встроенного трекинга использования CrewAI
# Добавьте в ваш экипаж:
result = crew.kickoff(inputs={"topic": "AI agents"})
print(f"Всего использовано токенов: {result.token_usage}")

# Используйте более дешёвые модели для простых задач, премиум — для сложных
# Llama 3.1 8B на Ollama = $0 стоимость API
# GPT-4o = ~$0.005/1K входных токенов

# Установите max_iter, чтобы предотвратить бесконтрольную работу агентов
Agent(max_iter=10, max_execution_time=120)  # Тайм-аут 2 минуты

# Кешируйте ответы LLM во время разработки
os.environ["CREWAI_DISABLE_CACHE"] = "false"
```

### Запуск экипажей как постоянного сервиса

```bash
# Обслуживайте экипажи через endpoint FastAPI
pip install fastapi uvicorn

cat > server.py << 'EOF'
from fastapi import FastAPI, BackgroundTasks
from my_research_crew.crew import MyResearchCrew
import asyncio

app = FastAPI()
results = {}

@app.post("/run/{topic}")
async def run_crew(topic: str, background_tasks: BackgroundTasks):
    job_id = f"job-{topic}-{len(results)}"
    background_tasks.add_task(execute_crew, job_id, topic)
    return {"job_id": job_id, "status": "started"}

async def execute_crew(job_id: str, topic: str):
    crew = MyResearchCrew().crew()
    result = crew.kickoff(inputs={"topic": topic})
    results[job_id] = str(result)

@app.get("/result/{job_id}")
async def get_result(job_id: str):
    return {"result": results.get(job_id, "pending")}

EOF

# Запустите сервер
uvicorn server:app --host 0.0.0.0 --port 8080 &

# Запустите выполнение экипажа
curl -X POST http://<clore-ip>:8080/run/quantum-computing
```

### Полезные встроенные инструменты CrewAI

```python
from crewai_tools import (
    SerperDevTool,        # Поиск Google через Serper API
    ScrapeWebsiteTool,    # Веб-скрапинг
    FileReadTool,         # Чтение локальных файлов
    FileWriterTool,       # Запись файлов
    DirectoryReadTool,    # Перечисление содержимого директории
    CodeInterpreterTool,  # Выполнение Python-кода
    GithubSearchTool,     # Поиск по репозиториям GitHub
    YoutubeVideoSearchTool, # Поиск на YouTube
    PGSearchTool,         # Запросы к PostgreSQL
)
```

### Реализация схемы с участием человека (human-in-the-loop)

```python
# Попросить ввод от человека на конкретной задаче
task = Task(
    description="Research {topic}",
    expected_output="Research report",
    agent=researcher,
    human_input=True    # Пауза и запрос обратной связи от пользователя
)
```

***

## Устранение неполадок

### "openai.AuthenticationError" даже при наличии действительного ключа

```bash
# Проверьте, загружен ли ваш API-ключ
python3 -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('OPENAI_API_KEY')[:10])"

# Если используете Ollama, убедитесь, что установлены эти параметры:
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b

# Проверьте доступность Ollama
curl http://localhost:11434/v1/models
```

### Агент застрял в цикле рассуждений

```bash
# Установите жёсткий лимит по итерациям
Agent(
    max_iter=10,            # Максимум шагов рассуждений
    max_execution_time=300  # Жёсткий таймаут 5 минут
)

# Включите verbose, чтобы увидеть, где он зацикливается
Agent(verbose=True)

# Проверьте, поддерживает ли модель вызов инструментов
# Некоторые маленькие модели не поддерживают; используйте llama3.1 или mistral-nemo
```

### Ошибка инструментов CrewAI (SerperDevTool 403)

```bash
# SerperDevTool требует бесплатного API-ключа с serper.dev
export SERPER_API_KEY=your-serper-key

# Альтернатива: используйте DuckDuckGo (ключ API не требуется)
from langchain_community.tools import DuckDuckGoSearchRun
from crewai import tool

@tool("DuckDuckGo Search")
def ddg_search(query: str) -> str:
    """Поиск в сети с помощью DuckDuckGo."""
    return DuckDuckGoSearchRun().run(query)
```

### Ошибки памяти (ChromaDB / эмбеддинги)

```bash
# Память CrewAI использует ChromaDB для векторного хранилища
# Если она падает, проверьте место на диске и права доступа
df -h
ls -la ~/.local/share/crewai/

# Очистите повреждённую память
rm -rf ~/.local/share/crewai/

# Или отключите память, если она не нужна
Crew(memory=False)

# Если используете эмбеддинги Ollama, убедитесь, что модель загружена
docker exec ollama ollama pull nomic-embed-text
```

### Сборка Docker падает из-за несовместимости ARM/x86

```bash
# Серверы Clore.ai x86_64; укажите платформу явно:
docker build --platform linux/amd64 -t my-crewai-app .

# Или в docker-compose.yml:
services:
  crewai:
    platform: linux/amd64
    build: .
```

### Ограничение по частоте от LLM API

```bash
# Уменьшите запросы в минуту
Crew(max_rpm=5)   # 5 запросов в минуту

# Добавьте логику повторных попыток в конфигурацию LLM
LLM(
    model="gpt-4o",
    max_retries=3,
    timeout=60
)
```

***

## Дополнительное чтение

* [Официальная документация CrewAI](https://docs.crewai.com)
* [Репозиторий CrewAI на GitHub](https://github.com/crewAIInc/crewAI)
* [Документация по инструментам CrewAI](https://docs.crewai.com/concepts/tools)
* [Репозиторий примеров CrewAI](https://github.com/crewAIInc/crewAI-examples)
* [Запуск Ollama на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/ollama.md)
* [Запуск vLLM на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/vllm.md)
* [Сравнение GPU Clore.ai](/guides/guides_v2-ru/nachalo-raboty/gpu-comparison.md)
* [Сообщество CrewAI в Discord](https://discord.com/invite/X4JWnZnxPb)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/ai-platformy-i-agenty/crewai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.