Дослідницький Агент

Система автоматизації досліджень, побудована на фреймворку SmolaGents, розроблена для збору, аналізу та синтезу інформації з різних джерел для підтримки дослідницьких завдань. Система підтримує інтеграцію з Model Context Protocol (MCP) для розширення можливостей пошуку.

Можливості

• Обробка дослідницьких запитів природною мовою (українською та англійською)
• Пошук та отримання інформації з множинних джерел
• Глибокий аналіз та синтез даних
• Структуровані звіти з цитуванням джерел
• Налаштовувані робочі процеси досліджень
• Автоматичне визначення та підтримка мови запиту

Архітектура

Система побудована на модульній архітектурі:

• Модуль керування дослідженнями: Координує процес дослідження
• Аналітичний модуль: Обробляє та аналізує зібрані дані
• Модуль інтерфейсу: Інтегрується з зовнішніми системами
• Модуль зберігання: Підтримує контекст та проміжні результати

Інструменти

• Веб-пошук через Model Context Protocol (MCP) та API сервіси:
  • MCP Brave Search як основний пошуковий двигун
  • BraveSearch API як резервний для українських запитів
  • Serper API як додатковий резервний варіант
• Завантаження вмісту URL
• Аналіз PDF документів
• Аналіз та візуалізація даних
• Управління базою даних для зібраної інформації

Налаштування

1. Клонуйте репозиторій: git clone [URL репозиторію]
2. Створіть віртуальне середовище: python -m venv venv
3. Активуйте середовище:
   • Windows: venv\Scripts\activate
   • Unix/MacOS: source venv/bin/activate
4. Встановіть залежності: pip install -r requirements.txt
5. Скопіюйте .env.example в .env та заповніть своїми API ключами:
   • OPENAI_API_KEY - ключ для OpenAI API (обов'язково)
   • ANTHROPIC_API_KEY - ключ для Anthropic API (опціонально)
   • SERPER_API_KEY - ключ для Serper API (резервний пошук)
   • BRAVESEARCH_API_KEY - ключ для BraveSearch API (для MCP та прямого доступу)
6. Налаштуйте MCP (опціонально, але рекомендовано):
   • Клонуйте репозиторій MCP серверів: git clone https://github.com/modelcontextprotocol/servers.git
   • Встановіть залежності для MCP: cd servers && PUPPETEER_SKIP_DOWNLOAD=true npm install
   • Скомпілюйте MCP Brave Search сервер: cd src/brave-search && npm run build
7. Запустіть додаток за допомогою скрипту: ./run.sh

Використання

# Базове використання
python main.py "Дослідницький запит"

# З файлом конфігурації
python main.py --config config/default_config.json

# Експорт результатів у файл
python main.py "Дослідницький запит" --output звіт.md

# Вказання конкретної мови (uk або en)
python main.py "Дослідницький запит" --language uk

Model Context Protocol (MCP)

Система підтримує інтеграцію з Model Context Protocol (MCP), що дозволяє розширити можливості пошуку та інтеграції з зовнішніми сервісами. Основні переваги використання MCP:

• Уніфікований інтерфейс для різних сервісів та API
• Модульна архітектура дозволяє легко додавати нові сервіси
• Покращена обробка помилок та резервні механізми

Налаштування MCP

Система використовує MCP Brave Search сервер для пошуку. Скрипт run.sh автоматично запускає MCP сервер перед запуском агента та зупиняє його після завершення роботи.

Для ручного запуску MCP сервера:

cd servers/src/brave-search
BRAVE_API_KEY=ваш_ключ_brave_search node dist/index.js

Резервні механізми

Система налаштована на використання резервних механізмів у випадку недоступності MCP:

1. Спочатку спробує використати MCP Brave Search
2. Якщо MCP недоступний, переходить на пряме використання Brave Search API
3. Якщо Brave Search API недоступний, використовує Serper API

Конфігурація

Система використовує файл конфігурації в форматі JSON. Основні параметри:

• llm: Налаштування моделі мови (провайдер, модель, температура)
• tools: Конфігурація інструментів (пошук, URL, PDF, аналіз даних тощо)
• planning: Параметри планування дослідження
• language: Налаштування мови (основна, підтримувані, автовизначення)
• output: Формат виводу та включення цитувань

Приклад конфігурації з MCP:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4-turbo",
    "temperature": 0.7
  },
  "tools": {
    "search": {
      "enabled": true,
      "engine": "mcp",
      "max_results": 10,
      "mcp": {
        "server_url": "http://localhost:3000",
        "tool_name": "brave_web_search"
      },
      "fallback": {
        "api_key_env": "BRAVESEARCH_API_KEY",
        "engine": "brave"
      }
    }
  },
  "planning": {
    "research_depth": "deep"
  },
  "language": {
    "primary": "uk",
    "supported": ["uk", "en"],
    "auto_detect": true
  }
}

Тестування

Для запуску тестів використовуйте:

# Запуск всіх тестів
pytest

# Запуск конкретного модуля тестів
pytest tests/test_research_agent.py

# Запуск з деталізованим виводом
pytest -v

Середовище для тестування

1. Створіть окреме віртуальне середовище для тестів:

   python -m venv test_venv
   source test_venv/bin/activate  # для Unix/MacOS
   

2. Встановіть залежності для тестування:

   pip install -r requirements_dev.txt
   

3. Створіть файл .env.test з тестовими API ключами.

Додавання нових тестів

При додаванні нових функцій, рекомендується створювати відповідні тести:

1. Створіть тестовий файл у директорії tests/
2. Використовуйте fixture-и для повторного використання коду
3. Імплементуйте тести для успішних сценаріїв та обробки помилок

Розробка

• Дотримуйтесь модульної архітектури
• Документуйте код за допомогою docstrings
• Додавайте тести для нових компонентів
• Зберігайте API ключі у змінних середовища
• Використовуйте чіткі назви функцій та класів
• Перевіряйте новий код за допомогою лінтерів та форматерів

Вирішення проблем

Поширені помилки

• 401 Unauthorized при пошукових запитах: Перевірте правильність API ключів у .env файлі
• Помилка імпорту модулів: Переконайтесь, що всі залежності встановлені
• RuntimeError при серіалізації даних: Переконайтесь, що дані перетворені у JSON-сумісний формат

Логування

Система використовує модуль logging для запису діагностичних повідомлень. Щоб змінити рівень логування:

import logging
logging.basicConfig(level=logging.DEBUG)  # Для детальнішого логування

Ліцензія

MIT