diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a191308
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# 8️⃣ Самописный поисковый агент на основе Deep Agents from Scratch
+
+**Project name:** `deep-search-agent`  
+**Goal:** Build a custom search agent that can browse the web, create virtual files in memory and finally export them to the real file system.
+
+---
+
+## 📖 Описание проекта
+
+В этом репозитории реализован **Deep Agent**, построенный на основе библиотеки [langchain](https://github.com/hwchase17/langchain) и примеров из репозитория `deep-agents-from-scratch`.  
+Агент умеет:
+
+1. Выполнять поисковые запросы в интернете (через `requests` + `BeautifulSoup`);
+2. Создавать виртуальные файлы, хранить их в памяти (`VirtualFileSystem`);
+3. В конце работы выгружать все виртуальные файлы на диск.
+
+Код находится в одном файле **`solution.py`** и содержит полностью рабочий пример с использованием OpenAI LLM (можно заменить на любой другой).
+
+---
+
+## ⚙️ Установка зависимостей
+
+```bash
+# Создайте виртуальное окружение (рекомендовано)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# Установите зависимости из requirements.txt
+pip install -r requirements.txt
+```
+
+`requirements.txt` содержит:
+
+```text
+langchain==0.2.0
+openai==1.12.0
+beautifulsoup4==4.12.3
+requests==2.32.3
+rich==13.7.1
+```
+
+> **Важно:**  
+> - Для работы с OpenAI понадобится переменная окружения `OPENAI_API_KEY`.  
+>   ```bash
+>   export OPENAI_API_KEY="sk-..."
+>   ```
+> - Если вы используете другую LLM, замените импорт и конфигурацию в коде.
+
+---
+
+## 🚀 Запуск
+
+```bash
+python solution.py
+```
+
+При запуске агент:
+
+1. Спросит у пользователя цель (например: «Найти информацию о последних новостях по теме X»).
+2. Выполнит поиск, создаст виртуальные файлы с найденными данными.
+3. После завершения работы выведет список созданных файлов и их путь к выгрузке.
+
+---
+
+## 📄 Пример использования
+
+```bash
+$ python solution.py
+Enter your goal: Find the latest news about AI breakthroughs in 2024.
+
+[Agent] Searching for "AI breakthroughs 2024"...
+[Agent] Found 3 relevant sources. Creating virtual files...
+
+Virtual file system created:
+- ai_breakthroughs_2024.html
+- ai_breakthroughs_2024_summary.txt
+
+Exporting virtual files to disk...
+✅ Files exported to ./output/
+
+Done! Check the output folder for results.
+```
+
+После выполнения вы увидите в каталоге `./output/` файлы:
+
+```text
+ai_breakthroughs_2024.html   # Полный HTML страницы
+ai_breakthroughs_2024_summary.txt  # Краткое резюме, созданное LLM
+```
+
+---
+
+## 📂 Структура проекта
+
+```
+deep-search-agent/
+├── solution.py          # Основной скрипт с агентом
+├── requirements.txt     # Зависимости
+└── README.md            # Это файл
+```
+
+---
+
+## 🔧 Как изменить поведение агента
+
+- **Изменить LLM** – замените `OpenAI()` на любой другой класс из `langchain.llms`.
+- **Добавить новые инструменты** – в список `tools` добавьте свои функции.
+- **Настроить поиск** – измените функцию `search_and_parse(url)` или используйте API поисковика.
+
+---
+
+## 📜 Лицензия
+
+MIT License. См. файл `LICENSE`.
+
+---
\ No newline at end of file