diff --git a/README.md b/README.md
index bde04aa..d3f209f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,126 @@
-# task-6a1864f7-ekzamen-rag-agent-s-chrom
+# 📚 Экзамен: RAG‑агент с ChromaDB и веб‑поиском
 
-Решения домашних заданий
\ No newline at end of file
+## 🚀 Описание проекта  
+В этом репозитории реализован **RAG‑агент** (Retrieval‑Augmented Generation), который умеет:
+- хранить локальные документы в векторном хранилище **ChromaDB**;
+- выполнять семантический поиск по этим документам с помощью эмбеддингов из **Ollama** (`nomic-embed-text`);
+- искать информацию в интернете через API **Tavily**;
+- автоматически выбирать, какой источник использовать для ответа на запрос пользователя.
+
+Проект состоит из двух файлов:
+
+| Файл | Что делает |
+|------|------------|
+| `vectorstore.py` | Создание и загрузка ChromaDB, чтение/чанкинг документов. |
+| `main.py` | Определяет инструменты агента (`search_local_kb`, `web_search`) и запускает LangChain‑агента. |
+
+---
+
+## 🛠️ Установка зависимостей
+
+```bash
+# 1️⃣ Скачиваем модели Ollama (LLM + эмбеддинги)
+ollama pull llama3
+ollama pull nomic-embed-text
+
+# 2️⃣ Устанавливаем Python‑пакеты
+pip install langchain langchain-chroma langchain-tavily langchain-ollama tavily-python chromadb python-dotenv
+```
+
+> **Важно**:  
+> - Убедитесь, что у вас установлен Docker (или другой способ запуска Ollama).  
+> - Для работы Tavily нужен API‑ключ. Создайте файл `.env` в корне проекта и добавьте строку:
+
+```dotenv
+TAVILY_API_KEY=YOUR_TAVILY_KEY_HERE
+```
+
+---
+
+## 📁 Структура проекта
+
+```
+.
+├── chroma_db/          # Папка, где будет храниться база данных (создаётся автоматически)
+├── documents/          # Пример папки с .txt/.md файлами для индексации
+│   ├── doc1.md
+│   └── doc2.txt
+├── vectorstore.py      # Модуль работы с ChromaDB
+├── main.py             # Запуск агента
+└── .env                # Tavily API ключ
+```
+
+---
+
+## ⚙️ Как запустить
+
+### 1️⃣ Создать/загрузить векторное хранилище и добавить документы
+
+```bash
+python - <<'PY'
+from vectorstore import create_vectorstore, load_documents
+
+# Создаём (или загружаем) коллекцию
+vectorstore = create_vectorstore("./chroma_db")
+
+# Загружаем все .txt/.md из папки documents
+load_documents("documents", vectorstore)
+print("Документы успешно добавлены в ChromaDB")
+PY
+```
+
+> После выполнения вы увидите сообщение о том, что документы загружены.  
+> Если база уже существует, она будет просто открыта.
+
+### 2️⃣ Запустить агента
+
+```bash
+python main.py
+```
+
+После запуска агент ожидает ввод вопросов от пользователя в консоли. Он сам решит,
+использовать локальный поиск (`search_local_kb`) или веб‑поиск (`web_search`).
+
+---
+
+## 📌 Пример использования
+
+```text
+$ python main.py
+Введите ваш вопрос (или 'exit' для выхода): Какой язык программирования используется в LangChain?
+
+Ответ:
+LangChain использует Python как основной язык разработки. Он предоставляет набор инструментов и абстракций, которые упрощают создание цепочек LLM‑моделей и интеграцию с внешними сервисами.
+
+(Источник: локальная база знаний)
+```
+
+Если вопрос требует информации из интернета:
+
+```text
+$ python main.py
+Введите ваш вопрос (или 'exit' для выхода): Что такое квантовый компьютер?
+
+Ответ:
+Квантовый компьютер – это устройство, использующее принципы квантовой механики для выполнения вычислений. Он может обрабатывать информацию в виде кубитов, которые могут находиться в суперпозиции состояний, что позволяет выполнять параллельные расчёты.
+
+(Источник: веб‑поиск через Tavily)
+```
+
+---
+
+## 📚 Дополнительные сведения
+
+- **ChromaDB** – быстрый и лёгкий в использовании векторный хранилище.  
+  Документация: https://docs.langchain.com/oss/python/integrations/vectorstores/chroma
+- **OllamaEmbeddings** – локальная модель эмбеддингов, не требует подключения к облаку.  
+  Документация: https://github.com/langchain-ai/langchain/tree/main/libs/langchain_ollama
+- **Tavily** – простой API для веб‑поиска.  
+  Документация: https://docs.tavily.com/
+- **LangChain** – фреймворк для построения агентов и цепочек LLM.
+
+---
+
+## 📄 Лицензия
+
+MIT License – свободно используйте, модифицируйте и распространяйте проект.
\ No newline at end of file