Agentic RAG Assistant с FastAPI + MCP

Ассистент для внутренней документации, объединяющий четыре вещи, которые рекрутеры сейчас проверяют у кандидатов:

• Agentic AI — цикл использования инструментов, где LLM сама решает: искать ли в базе знаний, выполнить ли расчёт или ответить напрямую.

• FastAPI — чистый REST-бэкенд (/ingest, /query, /agent/chat) с автоматически сгенерированной Swagger-документацией.

• RAG — документы разбиваются на чанки, индексируются и извлекаются по семантической релевантности перед тем, как LLM даёт ответ.

• MCP (Model Context Protocol) — те же инструменты (RAG-поиск + бизнес-логика) доступны как MCP-сервер, чтобы любой MCP-совместимый клиент (Claude Desktop, Claude Code и т.д.) мог использовать их напрямую, а не только через этот API.

Архитектура

                     ┌────────────────────┐
                     │   FastAPI Service   │
                     │  (app/main.py)      │
                     └─────────┬───────────┘
                               │
                     ┌─────────▼───────────┐
                     │   Agent Loop         │◄──── Groq API (tool use)
                     │  (app/agent.py)      │
                     └─────────┬───────────┘
                               │ calls
                 ┌─────────────┼──────────────┐
                 ▼                             ▼
        ┌────────────────┐           ┌──────────────────┐
        │  RAG Engine      │           │  Business Tools    │
        │  (app/rag.py)    │           │  (app/tools.py)     │
        └────────────────┘           └──────────────────┘
                 ▲                             ▲
                 └─────────────┬───────────────┘
                                │  same tools, exposed via
                     ┌──────────▼───────────┐
                     │   MCP Server           │
                     │  (app/mcp_server.py)   │
                     └────────────────────────┘

Установка

python -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env           # add your GROQ_API_KEY

Запуск API

uvicorn app.main:app --reload --port 8000

Откройте http://localhost:8000/docs для интерактивной Swagger-документации.

Попробуйте

# Pure retrieval, no LLM call
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "how many days of leave do I get?"}'

# Full agentic chat — LLM decides which tool(s) to call
curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "I joined in March and have taken 4 days off. How much leave do I have left, and what is the WFH policy?"}'

Второй вызов демонстрирует многоинструментальное рассуждение: модель вызывает rag_search для политики удалённой работы И calculate_leave_balance для расчёта — в одном диалоге.

Запуск как MCP-сервер

python -m app.mcp_server

Укажите любой MCP-хост на этот скрипт через stdio (например, добавьте его в claude_desktop_config.json в Claude Desktop как кастомный MCP-сервер), и он откроет rag_search, get_current_datetime и calculate_leave_balance как вызываемые инструменты.

Что рассказать о проекте на собеседовании

• Почему TF-IDF вместо эмбеддингов по умолчанию: демо остаётся запускаемым без API-ключей и без внешних загрузок; класс VectorStore написан так, что замена на FAISS/Chroma + настоящие эмбеддинги — это точечное изменение, а не переписывание.

• Почему инструменты живут в одном файле (tools.py) и подключаются дважды (agent.py и mcp_server.py): единый источник правды, без дублирования логики между HTTP-путём и MCP-путём.

• Цикл агента — это ручная реализация паттерна использования инструментов (а не чёрный ящик-фреймворк), поэтому можно объяснить каждый шаг: модель запрашивает инструмент → сервер выполняет его → результат возвращается → модель продолжает или отвечает.

Возможные расширения (хорошие ответы на «что бы вы улучшили»)

• Заменить TF-IDF на настоящие эмбеддинги (OpenAI/Voyage/локальные sentence-transformers) + постоянную векторную БД.

• Добавить память диалога между ходами (сейчас каждый вызов /agent/chat не сохраняет состояние).

• Добавить стриминг ответов через Server-Sent Events.

• Добавить аутентификацию (API-ключ или JWT) перед публичным развёртыванием.

• Контейнеризировать с Docker + docker-compose для запуска одной командой.